Skip to content

EliasOulkadi/shokunin / .pack/skills/documentation

documentation

Verified

Generate READMEs, API docs, changelogs, and knowledge base articles. Covers README structure with personality, OpenAPI-based API documentation, changelogs from conventional commits, typedoc patterns, and support KB articles.

Documentation

Write docs that developers actually read. Based on Stripe API docs, Standard Readme, Keep a Changelog, and OpenAPI.

Sub-Commands

CommandDescription
readmeGenerate a README from project files
apiGenerate API docs from OpenAPI spec or route handlers
changelogGenerate changelog from conventional commits
kbWrite a knowledge base article

README Structure

# Project Name [Badges]

> One-line description

## Features (3-6 quantified benefits)
## Quick Start — copy-paste runnable (no placeholders, no omitted imports)
## API Reference — every export in table format
## Examples — 2-3 real-world scenarios
## Configuration — env vars, config file, CLI flags
## Contributing — dev setup commands
## License — SPDX identifier

The Hook (first paragraph)

Answers: what (5 words), who, why.

Bad: "A React component library for building modern user interfaces." Good: "Buttons, modals, forms, done right. No design debt. Zero dependencies."

Quick Start Rules

Copy-paste runnable. No omitted imports. No placeholders. No "coming soon". Include expected output.

Badge Requirements

BadgeRequired?
CI (build status)Yes
Package versionYes
LicenseYes
CoverageRecommended

API Documentation

Structure per Endpoint

### [METHOD] [Path]
**Description**: one sentence
**Auth required**: Yes/No [type]
**Request**: Headers, Parameters (path/query/body)
**Response 200**: Body with example
**Error responses**: 400, 401, 404, 500 with descriptions

Rules per Endpoint

  • Request example (curl + one SDK)
  • Response example with ALL fields
  • Error responses for ALL possible status codes
  • Pagination docs (if applicable)
  • Rate limit headers documented

Changelog Format

## [2.1.0] - 2026-05-16

### Added
- New feature (#PR)

### Changed
- Behavior change with migration note (#PR)

### Fixed
- Bug fix (#PR)

### Deprecated / Removed / Security

Rules: Keep a Changelog format. Every entry links to PR. Migration notes for breaking changes. Unreleased section at top. Semantic versioning. Explain WHY not just WHAT.

Knowledge Base

Article Format

Title: as a question user would search for
Context: 1-2 sentences — who, what product/feature
Steps: numbered, one action per step, action verb first
Expected result: after last step
Escalation: if it still doesn't work

Rules: One action per step. Bold UI labels exactly as they appear. Max 15 words per step. No jargon.

Production Checklist

  • All examples tested from clean environment
  • No "TODO", "coming soon", "TBD", placeholder text
  • Consistent tone across all sections
  • Every link resolves
  • License badge matches LICENSE file
  • API docs: curl + SDK example per endpoint
  • Changelog: unreleased section present, versions correct
  • KB: tested by someone unfamiliar with the product

Workflow

  1. Identify document type — README, API docs, changelog, or knowledge base article. Each has a distinct structure and rule set.
  2. Gather source material — for README: project files, package.json, build system. For API: OpenAPI spec or route handlers. For changelog: git log. For KB: product expertise.
  3. Apply the template — README: hook → features → quick start → API → examples → config → contributing → license. API: method → path → description → auth → request → response → errors.
  4. Fill every section with real data — no "TODO", "coming soon", "TBD", placeholder text. Quick start must be copy-paste runnable. API docs need curl + SDK examples.
  5. Verify everything — test quick start from clean environment. Check every link resolves. Confirm license badge matches LICENSE file. KB: test steps as an unfamiliar user.
  6. Cut the generic — remove default template comments. Strip "write unit tests" style advice. Every sentence must convey a specific convention or fact about this project.

Error Handling

CauseFix
Quick start commands fail from a clean environmentTest every command from scratch. Ensure no omitted imports, no assumed global state, no missing env vars.
API docs missing error response codesDocument all possible status codes for every endpoint: 400 (validation), 401 (auth), 403 (forbidden), 404 (not found), 500 (server error).
Changelog entry lacks migration notes for breaking changesEvery breaking change must include: what changed, why, and the exact migration path. Link to the PR.
KB article steps don't produce expected result when followedHave someone unfamiliar with the product walk through the steps. Fix any ambiguity or missing context.
Links in documentation resolve to 404 or redirectCheck every link. Prefer permalinks. Verify external links haven't moved. Use web archive as fallback for critical references.
README badges show incorrect or outdated statusVerify CI badge matches current pipeline. Version badge matches latest release. Coverage badge matches current report.
API docs example response doesn't match actual API outputGenerate response examples from actual API output, not from spec definitions. Update when the API changes.
Default README template published with unfilled sectionsRemove all template comments and TODO markers before publishing. If a section has no content, omit it rather than leaving a placeholder.

Anti-Patterns

Anti-PatternCorrect
Default README (template unfilled)Remove all template comments. Fill every section.
"Coming soon" featuresShip or hide. Never show unfinished.
Untested install instructionsTest from scratch in clean environment.
API docs without examplesEvery function needs a runnable example.
Changelog without migration notesAlways include migration path for breaking changes.
KB with no expected resultEnd every step with "You should see..."
Example code with secretsUse placeholder env vars. Never real values.

API Documentation Patterns

OpenAPI → Docs

npx @redocly/cli build-docs openapi.yaml -o docs.html
npx @scalar/api-reference openapi.yaml

README Template

  1. Title + one-liner, 2. Quick start (install + first command), 3. Features (bullets), 4. Architecture (diagram), 5. API (link), 6. Contributing (link), 7. License

Changelog Automation

# Generate from conventional commits
npx standard-version
npx changelogen --from v1.0.0 --to HEAD

# Keep a Changelog format
## [version] - YYYY-MM-DD
### Added | Changed | Deprecated | Removed | Fixed | Security

Sources

  • Standard Readme specification
  • Stripe API documentation standards
  • Keep a Changelog (keepachangelog.com)
  • Conventional Commits (conventionalcommits.org)
  • OpenAPI Specification (openapis.org)
  • Zendesk / Intercom — KB standards

Checklist

  • Skill loads without errors in the AI agent
  • YAML frontmatter is valid (description, compatibility, audience)
  • Workflow section provides clear step-by-step instructions
  • Error handling section covers common failure modes
  • All referenced files (references/, scripts/, assets/) exist
  • Skill triggers correctly for intended use cases
  • No broken links or missing resources
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 197kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 197kUpdated Claude CodeCodexVerifiedInstall