| name | api-doc-writer |
| description | Creates comprehensive API reference documentation following Diátaxis Reference pattern. Reads source code to verify every method signature, creates structured API docs with zero fabrication tolerance. Use when documenting APIs, packages, or public interfaces. |
| version | 1.0.0 |
API Documentation Writer Skill
Purpose
Create comprehensive, accurate API reference documentation by reading source code and extracting exact method signatures. Follows the Diátaxis Reference pattern for information-oriented documentation with zero tolerance for fabricated methods or incorrect signatures.
Diátaxis Framework: Reference Documentation
Reference Type Characteristics:
- Information-oriented - Describes the machinery, not how to use it
- Technical descriptions - Facts about APIs, parameters, return types
- Complete coverage - Every public method and type documented
- Structured consistently - Same format for all entries
- Exact signatures - Verified against source code
- Minimal examples - Usage demonstrations, not step-by-step tutorials
What NOT to Include:
- ❌ Tutorials (learning-oriented) - Use tutorial-writer skill
- ❌ How-To guides (problem-oriented) - Use migration-guide-writer skill
- ❌ Explanations (understanding-oriented) - Link to separate explanation docs
- ❌ Marketing language - Technical descriptions only
Critical Rules (Zero Tolerance)
P0 - CRITICAL Violations (Must Fix)
- Fabricated Methods - Methods that don't exist in source code
- Wrong Signatures - Parameter types, names, or order don't match source
- Invalid Examples - Code that won't compile or uses fake imports
- Unverified Performance Claims - Numbers without benchmark evidence
P1 - HIGH Violations (Should Fix)
- Missing Source References - Not citing which file/method documented
- Incomplete Coverage - Missing public methods
- Marketing Language - Buzzwords instead of technical descriptions
P2 - MEDIUM Violations
- Structural Issues - Not following template consistently
- Redundancy - Repeating information unnecessarily
Workflow (Quick Summary)
Core Steps
- Discovery: Identify language, locate public API surface using grep/glob patterns, create checklist
- Extraction: Read source files, copy EXACT signatures (no paraphrasing), extract comments and error conditions
- Documentation: Use standardized templates (types, functions, constants), follow Diátaxis Reference pattern
- Examples: Write complete, runnable examples with imports and proper error handling
- Verification: Verify signatures match source exactly, check completeness, eliminate marketing language
- Organization: Structure logically (Overview → Types → Functions → Constants → Examples)
For detailed step-by-step workflow with bash commands, templates, and verification checklists:
Read `~/.claude/skills/api-doc-writer/references/WORKFLOW-STEPS.md`
For API documentation templates (types, functions, constants):
Read `~/.claude/skills/api-doc-writer/references/TEMPLATE-EXAMPLES.md`
Use when: Performing API documentation, need specific templates, or understanding each step
Common Pitfalls (Quick Summary)
Critical Issues to Avoid
- Paraphrasing Signatures: Copy exact signature from source (include receiver types, pointer symbols)
- Fabricating Methods: ONLY document methods that exist in source code (verify first)
- Wrong Parameter Types: Match types exactly (string vs TaskId, pointer vs value)
- Missing Error Conditions: Document specific error conditions from code logic
- Non-Runnable Examples: Include all imports, use correct syntax and real APIs
- Line Number References: Use method names, not line numbers (they change)
- Marketing Language: Use technical descriptions ("provides CRUD operations" not "blazing-fast")
For detailed pitfall examples with bad/good comparisons:
Read `~/.claude/skills/api-doc-writer/references/PITFALLS.md`
Use when: Need concrete examples of common mistakes to avoid
Integration with Other Skills
Works With:
- api-documentation-verify - Verify reference docs for accuracy
- migration-guide-writer - Reference docs show new API signatures
- tutorial-writer - Tutorials link to reference for detailed API info
Invokes:
- None (standalone skill, but uses Read tool extensively)
Invoked By:
- User (manual invocation)
- As part of documentation workflow
Output Format
Primary Output: Markdown file with structured API reference
File Location:
docs/api/[package-name].md for package documentationAPI.md in project root for main APIdocs/reference/[module-name].md for module documentation
Include at end of document:
---
## Documentation Metadata
**Last Updated**: [Date]
**Source Code Version**: [Commit SHA or version]
**Verification Status**: ✅ All APIs verified against source code
**Source Files**:
- `path/to/file1.go`
- `path/to/file2.go`
## Verification Checklist Completed:
- ✅ All methods verified against source
- ✅ All signatures exactly match
- ✅ All examples use real imports
- ✅ No fabricated methods
- ✅ No marketing language
- ✅ Source references included
Time Estimates
Small API (< 10 public methods): 30-45 minutes
Medium API (10-30 public methods): 1-2 hours
Large API (30+ public methods): 2-4 hours
Complex API with types (many types and methods): 4-8 hours
Example Usage
/skill api-doc-writer
/skill api-doc-writer pkg/services/task
User: "Document the TaskService API"
Assistant: "I'll use the api-doc-writer skill to create comprehensive API documentation"
Success Criteria
Documentation is complete when:
- ✅ All public APIs discovered and documented
- ✅ All signatures verified against source code
- ✅ All examples use real imports and verified APIs
- ✅ No fabricated methods or wrong signatures
- ✅ Source references included for all entries
- ✅ Error conditions documented from code
- ✅ Verification checklist completed
- ✅ No marketing language or buzzwords
- ✅ Structured consistently using template
References
Related Agent
For comprehensive documentation guidance that coordinates this and other documentation skills, use the documentation-coordinator agent.
