docs-codebase
30
总安装量
30
周安装量
#6787
全站排名
安装命令
npx skills add https://github.com/vasilyu1983/ai-agents-public --skill docs-codebase
Agent 安装分布
claude-code
21
cursor
18
gemini-cli
17
opencode
17
codex
14
Skill 文档
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 |