documentation_skill

Overview

This skill focuses on communicating intended behavior and context of code through clear documentation and comments, and on sharing knowledge across the team. It emphasizes making codebases easier to understand, maintain, and extend by documenting rationale, usage, and system-level decisions. Good documentation reduces onboarding time and preserves institutional knowledge in collaborative, agent-assisted workflows.

How this skill works

Inspect code to find areas where intent, trade-offs, or non-obvious behavior are not documented and add concise comments or higher-level docs. Create or update README, architecture notes, API docs, and contributor guidance so they reflect current behavior and setup. Mark deprecated areas, add maintainers lists, and ensure inline comments explain workarounds or complex algorithms.

When to use it

• When a new module, API, or service is added and setup or usage isn’t obvious
• When code contains non-obvious algorithms, workarounds, or platform-specific behavior
• Before merging a pull request that changes public interfaces or contracts
• When onboarding new team members or handing off components
• When documentation is stale after a refactor or behavior change

Best practices

• Comment for clarity, not restatement—explain why, not what the code does
• Treat docs as code: update documentation in the same PR as related code changes
• Document public interfaces, expected inputs/outputs, and error behaviors
• Keep README and architecture summaries concise and link to deeper design docs
• Use consistent project-level conventions for doc locations and maintainers

Example use cases

• Add README and runbook for a new microservice so operators can deploy and debug it
• Annotate a performance workaround with benchmarks and the reason it’s required
• Update API docs and changelog when endpoints or response shapes change
• Create an onboarding guide that highlights architecture, key repos, and contacts
• Tag deprecated functions with migration steps and timeline for removal