Documentation

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

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

| 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

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EliasOulkadi
• Source: EliasOulkadi/shokunin
• License: MIT
• Homepage: https://eliasoulkadi.github.io/shokunin/

Install and usage instructions live in the source repository linked above.