Documentation Engineer
- 652 installs
- 65 repo stars
- Updated June 21, 2026
- charon-fan/agent-playbook
documentation-engineer is a Claude Code skill that generates consistent READMEs, API references, architecture overviews, and code comments for developers who need clear project documentation without manual formatting dru
About
documentation-engineer is an agent-playbook skill for creating clear, comprehensive documentation across README overviews, API endpoint references, inline code comments, and architecture write-ups. The collection includes Python helpers such as scripts/generate_docs.py for scaffolding structures and validation scripts for doc quality checks. Developers invoke it with prompts like write documentation for this API, create a README, or document this code. Reach for documentation-engineer when onboarding docs lag behind implementation or when API surfaces need structured references before release.
- Generates four documentation types: README, API Docs, Code Comments, and Architecture docs
- Includes ready-to-use README and API Documentation templates
- Provides Python scripts for generating and validating documentation structure
- Follows Google Developer Documentation Style Guide and Diátaxis Framework
- Delivers structured output with parameters, responses, errors, and usage examples
Documentation Engineer by the numbers
- 652 all-time installs (skills.sh)
- Ranked #340 of 1,901 Documentation skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Jul 28, 2026 (Skillselion catalog sync)
npx skills add https://github.com/charon-fan/agent-playbook --skill documentation-engineerAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 652 |
|---|---|
| repo stars | ★ 65 |
| Security audit | 3 / 3 scanners passed |
| Last updated | June 21, 2026 |
| Repository | charon-fan/agent-playbook ↗ |
How do you generate API docs and READMEs from code?
Generate consistent, high-quality READMEs, API references, architecture overviews, and code comments without manual formatting.
Who is it for?
Developers who need fast, consistent docs for APIs or repos and already have code or endpoints to describe.
Skip if: Teams wanting automated doc site hosting, OpenAPI codegen from annotations only, or marketing landing copy instead of technical docs.
When should I use this skill?
User asks to write a README, document an API, add architecture overview, or explain code with comments.
What you get
Structured README, API reference sections, architecture overview, and validated inline comments aligned to project conventions.
- README.md
- API reference
- architecture document
Files
Documentation Engineer
Expert in creating clear, comprehensive, and maintainable technical documentation.
When This Skill Activates
Activates when you:
- Ask to write documentation
- Request README creation
- Mention "docs" or "document this"
- Need API documentation
Documentation Types
1. README
Every project should have a README with:
# Project Name
Brief description (what it does, why it exists)
## Quick Start
Installation and usage in 3 steps or less.
## Installation
Detailed installation instructions.
## Usage
Examples of common usage patterns.
## Configuration
Environment variables and configuration options.
## Development
How to run tests, build, and develop locally.
## Contributing
Guidelines for contributors.
## License
License information.2. API Documentation
For each endpoint/function:
- Description: What it does
- Parameters: Name, type, required/optional, description
- Return value: Type and structure
- Errors: Possible errors and conditions
- Examples: Usage examples
3. Code Comments
Comment why, not what:
// Bad: Sets the count to zero
count = 0;
// Good: Reset count for new measurement cycle
count = 0;
// Bad: Check if user is admin
if (user.role === 'admin') {
// Good: Only admins can bypass approval workflow
if (user.role === 'admin') {4. Architecture Documentation
- System overview
- Component relationships
- Data flow
- Design decisions
- Trade-offs considered
Documentation Principles
1. Be Clear: Use simple, direct language 2. Be Concise: Respect the reader's time 3. Be Accurate: Keep docs in sync with code 4. Be Complete: Cover all public interfaces 5. Be Current: Update docs when code changes
Writing Guidelines
Headings
- Use sentence case for headings
- Start with a verb or noun
- Be descriptive
Code Examples
- Show before/after when appropriate
- Include import statements
- Show expected output
- Handle edge cases
Links
- Use relative links for internal docs
- Include anchors for sections
- Test that links work
Diagrams
- Use Mermaid for flowcharts and sequences
- Keep diagrams simple
- Add a title and legend
Documentation Checklist
README
- [ ] Project description
- [ ] Quick start guide
- [ ] Installation instructions
- [ ] Usage examples
- [ ] Configuration guide
- [ ] Contributing guidelines
Code Docs
- [ ] All public functions documented
- [ ] Parameters and returns documented
- [ ] Examples provided for complex functions
- [ ] Edge cases documented
API Docs
- [ ] All endpoints documented
- [ ] Request/response schemas
- [ ] Authentication requirements
- [ ] Error responses documented
- [ ] Rate limits documented
Scripts
Generate documentation structure:
python scripts/generate_docs.pyValidate documentation:
python scripts/validate_docs.pyReferences
references/readme-template.md- README templatereferences/api-template.md- API documentation templatereferences/style-guide.md- Documentation style guide
Documentation Engineer
A Claude Code skill for creating clear, comprehensive documentation.
Installation
This skill is part of the agent-playbook collection.
Usage
You: Write documentation for this API
You: Create a README
You: Document this codeDocumentation Types
| Type | Description |
|---|---|
| README | Project overview and quick start |
| API Docs | Endpoint/function documentation |
| Code Comments | Inline explanations |
| Architecture | System design documentation |
Scripts
Generate documentation structure:
python scripts/generate_docs.pyValidate documentation:
python scripts/validate_docs.pyResources
API Documentation Template
Endpoint: /resource
Method: GET | POST | PUT | DELETE
Description: What the endpoint does.
Parameters
id(string, required) - Resource identifier
Response
{
"data": {}
}Errors
400Bad Request401Unauthorized404Not Found
README Template
Overview
Describe what the project does and why it exists.
Quick Start
1. Install dependencies 2. Configure environment 3. Run the main command
Installation
- Requirements
- Setup steps
Usage
Provide common usage examples.
Configuration
List environment variables and configuration options.
Development
How to lint, test, and build locally.
Contributing
Explain how to propose changes.
Documentation Style Guide
Headings
- Use sentence case
- Keep headings short and specific
Code Blocks
- Always specify a language
- Keep examples minimal and runnable
Links
- Use relative links for internal docs
- Prefer stable URLs for external references
#!/usr/bin/env python3
# Template generator for documentation scaffold.
from pathlib import Path
import argparse
import textwrap
def write_output(path: Path, content: str, force: bool) -> bool:
if path.exists() and not force:
print(f"{path} already exists (use --force to overwrite)")
return False
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(content, encoding="utf-8")
return True
def main() -> int:
parser = argparse.ArgumentParser(description="Generate documentation scaffold.")
parser.add_argument("--output", default="docs/README.md", help="Output file path")
parser.add_argument("--name", default="example", help="Product or service name")
parser.add_argument("--owner", default="team", help="Owning team")
parser.add_argument("--force", action="store_true", help="Overwrite existing file")
args = parser.parse_args()
content = textwrap.dedent(
f"""\
# Documentation
## Overview
Describe {args.name} and its purpose.
## Ownership
- Owner: {args.owner}
- Support channel: TBD
## Quickstart
1. Install dependencies
2. Configure environment
3. Run the service
## Configuration
- Required environment variables
- Feature flags
## Usage
Examples for {args.name}.
## API Reference
- Endpoints or SDK methods
## Troubleshooting
- Common errors and fixes
## Changelog
- Recent updates
"""
).strip() + "\n"
output = Path(args.output)
if not write_output(output, content, args.force):
return 1
print(f"Wrote {output}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
#!/usr/bin/env python3
# Template validator for documentation scaffold.
from pathlib import Path
import argparse
DEFAULT_REQUIRED = [
"## Overview",
"## Ownership",
"## Quickstart",
"## Configuration",
"## Usage",
"## Troubleshooting",
]
def main() -> int:
parser = argparse.ArgumentParser(description="Validate a generated artifact.")
parser.add_argument("--input", default="docs/README.md", help="Input file path")
parser.add_argument(
"--require",
action="append",
default=[],
help="Additional required section heading",
)
args = parser.parse_args()
path = Path(args.input)
if not path.exists():
print(f"Missing file: {path}")
return 1
text = path.read_text(encoding="utf-8", errors="ignore")
text_lower = text.lower()
required = DEFAULT_REQUIRED + args.require
missing = [section for section in required if section.lower() not in text_lower]
if missing:
print("Missing required sections: " + ", ".join(missing))
return 1
print(f"Validated {path}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
Lark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.451k
Lark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.391k15.9kLark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.387k15.9k
Opensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k72Readme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k72
Domain ModelingBuild and sharpen a project's domain model: pin down domain terminology in a glossary and record architectural decisions as ADRs.267k192kFAQ
What documentation types does documentation-engineer support?
documentation-engineer creates README overviews, API endpoint documentation, inline code comments, and architecture design write-ups using agent-playbook conventions and helper scripts.
Does documentation-engineer include automation scripts?
documentation-engineer references python scripts/generate_docs.py to scaffold documentation structure plus validation scripts to check doc completeness before sharing.
Is Documentation Engineer safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.