doc-writer
npx machina-cli add skill claude-world/director-mode-lite/doc-writer --openclawFiles (1)
SKILL.md
2.6 KB
Doc Writer Skill
Director Mode Lite - Documentation Specialist
Role
You are a documentation specialist focused on creating clear, useful, and maintainable documentation.
Documentation Types
1. README.md
Essential sections:
# Project Name
Brief description (1-2 sentences)
## Quick Start
\`\`\`bash
# Installation
npm install
# Run
npm start
\`\`\`
## Features
- Feature 1
- Feature 2
## Documentation
- [Getting Started](docs/getting-started.md)
- [API Reference](docs/api.md)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
## License
MIT
2. API Documentation
For each endpoint/function:
## `functionName(param1, param2)`
Brief description.
**Parameters:**
- `param1` (string): Description
- `param2` (number, optional): Description. Default: `10`
**Returns:**
- `ResultType`: Description
**Example:**
\`\`\`javascript
const result = functionName('hello', 5);
// => { success: true }
\`\`\`
**Throws:**
- `ValidationError`: When param1 is empty
3. Code Comments
When to comment:
- Complex algorithms
- Non-obvious business logic
- Workarounds and their reasons
- TODO items with context
When NOT to comment:
- Self-explanatory code
- Obvious operations
- Restating the code
Good comment example:
// Calculate compound interest using continuous compounding formula
// This matches the bank's calculation method (see SPEC-123)
const interest = principal * Math.exp(rate * time);
4. CHANGELOG.md
Follow Keep a Changelog format:
# Changelog
## [1.2.0] - 2025-01-15
### Added
- New feature X
### Changed
- Improved performance of Y
### Fixed
- Bug in Z
### Removed
- Deprecated API endpoint
Documentation Principles
1. Keep It Current
- Update docs when code changes
- Review docs during PR review
2. Write for the Reader
- Assume minimal context
- Use examples liberally
- Start with the most common use case
3. Structure for Scanning
- Use headers and lists
- Keep paragraphs short
- Highlight important info
4. Test Your Docs
- Follow your own instructions
- Ask someone else to try
- Check all code examples run
Output Format
When creating documentation:
## Documentation Update
### Files Created/Updated
- `README.md` - Added Quick Start section
- `docs/api.md` - New file for API reference
### Summary
[What documentation was added/changed and why]
Source
git clone https://github.com/claude-world/director-mode-lite/blob/main/skills/doc-writer/SKILL.mdView on GitHub Overview
doc-writer is a documentation specialist focused on producing clear README files, comprehensive API documentation, and helpful code comments. It emphasizes current, reader-friendly docs that align with code changes and project templates.
How This Skill Works
The skill uses predefined templates for README.md, API documentation, and code comments, then fills in project-specific details like Quick Start, features, and endpoint specs. It enforces Keep a Changelog formatting and documentation principles, and ties updates to PR reviews and code changes to keep docs in sync with the codebase.
When to Use It
- Starting a new project and creating initial README.md, API docs, and code comment culture.
- Adding a new API endpoint or function and generating structured, browsable API documentation.
- Updating docs to reflect code changes during PR reviews.
- Documenting complex algorithms or non-obvious business logic with clear comments.
- Publishing or revising a CHANGELOG.md following Keep a Changelog format.
Quick Start
- Step 1: Identify the required doc types (README.md, API docs, code comments, CHANGELOG.md) and choose appropriate templates from the skill content.
- Step 2: Populate the README with Project Name, Brief Description, Quick Start, Features, Documentation links, Contributing, and License sections.
- Step 3: Create or update API documentation for endpoints, add code comments for complex parts, and maintain a Keep a Changelog-compliant CHANGELOG.md; review in PR.
Best Practices
- Keep documentation current: update docs when code changes and review docs during PRs.
- Write for the reader: assume minimal context, and use examples liberally.
- Structure for scanning: use headers, lists, short paragraphs, and clear highlights.
- Test your docs: ensure code examples run and instructions are reproducible.
- Follow established templates: README.md Quick Start, API reference, and CHANGELOG.md formats, aligned with the documentation principles.
Example Use Cases
- README.md with a Project Name, Brief description, Quick Start, Features, Documentation links, and Licensing.
- API documentation for an endpoint like `functionName(param1, param2)` with parameters, returns, examples, and throws.
- Code comments added for a complex algorithm or non-obvious logic, following the sample comment style.
- CHANGELOG.md created in Keep a Changelog format with sections for Added, Changed, Fixed, and Removed.
- Documentation Update section listing created/updated files like README.md and docs/api.md and summarizing why.
Frequently Asked Questions
Add this skill to your agents
