Buff Docs

buff-docs

The docs skill generates modern, minimal, GitHub-standard documentation. Smart by default — scales scope to project size. Infers style from existing docs. Produces docs that are clean for humans and token-efficient for AI consumers.

Scope detection (smart default)

Determine output scope before writing anything:

Count source files:

find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.rs" -o -name "*.go" \) | grep -v node_modules | grep -v dist | wc -l

Style inference

Before writing, check for existing docs:

1. Read existing README.md — match heading hierarchy, tone, section order
2. Read docs/ folder structure — match naming conventions
3. Check package.json "description" and "homepage" fields — use for project summary
4. Read .buff/plan.md — use architecture section for technical overview

If nothing exists, apply the buff minimal template (see below).

README structure (buff default)

# [project name]

> [one-line tagline from package.json description or plan summary]

## What it does

[2-4 sentences. What problem does it solve? Who is it for?]

## Installation

\`\`\`bash
[install command — npm install / pip install / cargo add / etc.]
\`\`\`

## Quick start

\`\`\`[language]
[minimal working example — the smallest possible complete usage]
\`\`\`

## Usage

[Core usage patterns — not exhaustive, just the 80% cases]

## API

[Only if the project exports a public API — otherwise omit]

## Configuration

[Only if there are config options — list with defaults]

## Contributing

[1-3 sentences max. Link to CONTRIBUTING.md if it exists.]

## License

[License type and link]

Rules:

• No empty sections — omit a section if there's nothing real to put in it
• No boilerplate filler ("this project uses best practices") — every sentence earns its place
• Code examples run on copy-paste — test them mentally before writing
• Use backtick fences with language tags — always
• Headings: H1 for project name only, H2 for sections, H3 for subsections

Full docs folder structure (docs/)

docs/
├── README.md          → same as project README (or link to it)
├── getting-started.md → installation + first real task walkthrough
├── api-reference.md   → all public exports, signatures, parameters
└── changelog.md       → version history (only if --changelog flag)

getting-started.md

Walk through the smallest complete task from zero:

1. Install
2. Configure (if needed)
3. First real usage (not "hello world" — something that demonstrates actual value)

api-reference.md

For each exported function, class, or type:

### functionName(param: Type): ReturnType

[One sentence description]

**Parameters**
- `param` — [description, valid values if constrained]

**Returns** — [what it returns, and when it returns different things]

**Example**
\`\`\`typescript
[minimal working example]
\`\`\`

Generate from source by reading exported symbols. Do not invent API docs — read the actual signatures.

changelog.md

Generate from git log if --changelog is set:

git log --oneline --no-merges --pretty=format:"- %s (%h)" v[last-tag]..HEAD

Group by type (feat, fix, refactor, docs) from conventional commit prefixes.

Flags

Doc quality standards

A good buff doc:

• Can be understood in a single read without prior context
• Has a working code example in the first 30 lines
• Contains zero marketing language ("powerful", "seamless", "robust")
• Uses active voice ("Run the server" not "The server can be run")
• Is scannable — headings and code blocks visible on scroll
• Renders correctly on GitHub (test Mermaid, tables, fenced code)

AI readability

Docs are written for both humans and AI consumers (LLMs reading the project):

• Keep section headings descriptive and consistent — they become semantic anchors
• Put the most important information first in each section
• Use tables for structured data — they parse cleanly
• Avoid nested bullet lists > 2 levels — they're ambiguous to parse

Counterfeit integration

Read from .buff/memory/preferences.json:

• communication.verbosity → controls detail level in docs
• communication.language → target language for docs content

Additional Resources

• references/templates.md — Full buff docs templates for README, API reference, getting-started