ulises-jeremias/agent-toolkit/docs-generator

Docs Generator (WHAT)

Generate or refresh documentation from the actual code, schema, and git history. Never invent — always derive from evidence in the repo.

When to use

• README is missing, stale, or doesn't reflect the current stack
• CHANGELOG needs to be generated from merged PRs or git log
• API spec (OpenAPI/GraphQL) exists but human-readable docs don't
• New repo needs an AGENTS.md to onboard AI assistants

Out of scope

• Does NOT write code — documentation only
• Does NOT commit or push — delegate to `github-cli-workflow`
• Does NOT update external systems (Confluence, Notion) — use their respective skills

Workflow

README.md generation

1. Inspect repo: package.json / pyproject.toml / Cargo.toml for name, description, stack
2. Read Makefile / justfile / package.json scripts for commands
3. Read .github/workflows/ for CI structure
4. Draft README with: Purpose, Stack, Prerequisites, Quick Start, Development, Testing, Contributing
5. Apply `output-handshake` before writing

CHANGELOG.md generation

# Conventional commits format
git log --oneline --no-merges --pretty="format:%h %s" $(git describe --tags --abbrev=0)..HEAD
 
# Group by type: feat / fix / docs / chore / refactor / perf / test
# Format: ## [Unreleased] with subsections per type

Draft changelog section and ask user to confirm version before finalizing.

API reference generation

• OpenAPI spec → readable endpoint table with params, responses, auth
• GraphQL schema → type reference with fields and descriptions
• Always note the spec version and date in the generated doc

AGENTS.md starter

Use the template from ~/.local/share//skills-catalog.yaml patterns:

• Purpose and stack
• Repository inspection order
• What AI assistants may and must not do
• Key commands (build, test, lint)
• Links to key docs

Inline Documentation (why, not what) — per addyosmani/agent-skills documentation-and-adrs 2026-08-12 diff docs/research/diff-394-documentation-and-adrs.md

Comment the why, not the what:

// BAD: Restates the code
// Increment counter by 1
counter += 1;
// GOOD: Explains non-obvious intent
// Rate limit uses a sliding window — reset counter at window boundary,
// not on a fixed schedule, to prevent burst attacks at window edges
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

• When NOT to comment: self-explanatory code (calculateTotal reduce), week-old TODOs (do it now), commented-out code (delete — git has history).
• Document Known Gotchas inline where they matter:

/**
 * IMPORTANT: Must be called before first render — after hydration causes FOUC
 * (theme context not available during SSR). See ADR-003.
 */
export function initializeTheme(theme: Theme): void { ... }

Do not invent docs from thin air — derive from code/specs/git history (this skill) vs ADR why (via adr skill). personas/ (HOW agent thinks) vs skills/ (HOW task executes) preserved — see docs/CONCEPTS.md.

Verification (after documenting)

• [ ] ADRs exist for all significant decisions, README covers quick start/commands/architecture (link ADRs), API docs have types, gotchas inline, no commented-out code, CLAUDE.md/AGENTS.md current.
• Rationalizations table — "code is self-documenting" (reality: code shows what, not why/alternatives), "docs when API stabilizes" (doc is first test of design), "ADRs are overhead" (10-min ADR prevents 2-hour debate).

Anti-patterns

• Do not guess stack or commands — read from actual config files
• Do not generate CHANGELOG from unstaged changes
• Do not overwrite existing README without showing diff first

Delegates to