EliasOulkadi/shokunin / .pack/skills/documentation
documentation
VerifiedGenerate 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
| Command | Description |
|---|---|
readme | Generate a README from project files |
api | Generate API docs from OpenAPI spec or route handlers |
changelog | Generate changelog from conventional commits |
kb | Write 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
| Badge | Required? |
|---|---|
| CI (build status) | Yes |
| Package version | Yes |
| License | Yes |
| Coverage | Recommended |
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
- Identify document type — README, API docs, changelog, or knowledge base article. Each has a distinct structure and rule set.
- 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.
- Apply the template — README: hook → features → quick start → API → examples → config → contributing → license. API: method → path → description → auth → request → response → errors.
- 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.
- 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.
- 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
| Cause | Fix |
|---|---|
| Quick start commands fail from a clean environment | Test every command from scratch. Ensure no omitted imports, no assumed global state, no missing env vars. |
| API docs missing error response codes | Document 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 changes | Every 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 followed | Have someone unfamiliar with the product walk through the steps. Fix any ambiguity or missing context. |
| Links in documentation resolve to 404 or redirect | Check every link. Prefer permalinks. Verify external links haven't moved. Use web archive as fallback for critical references. |
| README badges show incorrect or outdated status | Verify CI badge matches current pipeline. Version badge matches latest release. Coverage badge matches current report. |
| API docs example response doesn't match actual API output | Generate response examples from actual API output, not from spec definitions. Update when the API changes. |
| Default README template published with unfilled sections | Remove all template comments and TODO markers before publishing. If a section has no content, omit it rather than leaving a placeholder. |
Anti-Patterns
| Anti-Pattern | Correct |
|---|---|
| Default README (template unfilled) | Remove all template comments. Fill every section. |
| "Coming soon" features | Ship or hide. Never show unfinished. |
| Untested install instructions | Test from scratch in clean environment. |
| API docs without examples | Every function needs a runnable example. |
| Changelog without migration notes | Always include migration path for breaking changes. |
| KB with no expected result | End every step with "You should see..." |
| Example code with secrets | Use 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
- 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 470k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |