ReddRadar
Agent skill
docs-codebase
Technical writing patterns for README files, API documentation, architecture decision records (ADRs), changelogs, contributing guides, code comments, and docs-as-code workflows. Covers documentation structure, style guides, Markdown best practices, and documentation testing.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/docs-codebase
SKILL.md
Technical Documentation
Execution-ready patterns for clear, maintainable technical documentation.
Modern best practices (January 2026): docs-as-code, ownership + review cadence, documentation QA gates (links/style/spelling), AI-assisted drafting + review, OpenAPI 3.2.0 where streaming schemas matter, and GEO (Generative Engine Optimization) for AI search.
Quick Reference
| Documentation Type | Template | When to Use |
|---|---|---|
| Project README | readme-template.md | New project, onboarding |
| Architecture Decision | adr-template.md | Technical decisions |
| API Reference | api-docs-template.md | REST/GraphQL APIs |
| Changelog | changelog-template.md | Version history |
| Contributing Guide | contributing-template.md | Open source, teams |
Workflow
- Identify the documentation type and audience.
- Find existing patterns in the repo; follow local conventions.
- Start from the closest template in
assets/and adapt. - Add ownership + review cadence for critical docs (runbooks, onboarding, API reference).
- Run documentation QA (links, formatting, spelling, examples) before merging.
Decision Tree
User needs: [Documentation Task]
├─ New project? → **README.md**
├─ Technical decision? → **ADR**
├─ Building API? → **OpenAPI spec** + api-docs-template
├─ New version? → **CHANGELOG.md**
├─ Team collaboration? → **CONTRIBUTING.md**
├─ Documenting code? → **Docstrings** (JSDoc, Python)
└─ Building docs site? → **MkDocs** (Python) or **Docusaurus** (JS)
Cross-Platform AI Documentation
AGENTS.md Standard
Prefer AGENTS.md as the cross-tool source of truth. If a specific tool requires a different filename (example: Claude Code uses CLAUDE.md), keep it aligned via a symlink only when you want identical content across tools.
# If `CLAUDE.md` does not exist and you want identical content:
ln -s AGENTS.md CLAUDE.md
Do / Avoid
Do
- Assign owners and review cadences to critical docs
- Add CI checks for links, style, and staleness
- Prefer small, task-oriented docs over big wiki pages
- Use Keep a Changelog format with semantic versioning
Avoid
- Docs without owners (guaranteed to rot)
- Stale runbooks (dangerous during incidents)
- Copy/paste docs that drift from code
Resources
| Resource | Purpose |
|---|---|
| references/readme-best-practices.md | README structure, badges |
| references/adr-writing-guide.md | ADR lifecycle, examples |
| references/changelog-best-practices.md | Keep a Changelog format |
| references/api-documentation-standards.md | REST, GraphQL, gRPC docs |
| references/code-commenting-guide.md | Docstrings, inline comments |
| references/contributing-guide-standards.md | CONTRIBUTING.md structure |
| references/docs-as-code-setup.md | MkDocs, Docusaurus, CI/CD |
| references/writing-best-practices.md | Clear communication |
| references/markdown-style-guide.md | Markdown formatting |
| references/documentation-testing.md | Vale, markdownlint, cspell |
| references/ai-documentation-tools.md | Mintlify, DocuWriter, GEO |
| references/production-gotchas-guide.md | Documenting platform issues |
Templates
| Category | Templates |
|---|---|
| Architecture | adr-template.md |
| API Reference | api-docs-template.md |
| Project Management | readme-template.md, changelog-template.md, contributing-template.md |
| Docs-as-Code | docs-structure-template.md, ownership-model.md |
Related Skills
| Skill | Purpose |
|---|---|
| qa-docs-coverage | Documentation gap audit |
| dev-api-design | REST API patterns |
| git-workflow | Conventional Commits |
| docs-ai-prd | PRD templates |
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?