agentic-docs_skill

Overview

This skill produces clear, plain-spoken code comments and documentation that live alongside the code. It focuses on explaining why decisions were made, not restating what the code does, and is optimized for future developers, teammates, and AI assistants that read one file at a time. Use it to create file headers, function docs, inline notes, and architectural comments that stay accurate and actionable.

How this skill works

The skill inspects code context and generates targeted documentation at multiple levels: file headers describing responsibility and relationships; function/method contracts with edge cases and side effects; concise inline comments that explain tradeoffs; and architecture notes for important design decisions. It avoids redundant comments, references constants instead of duplicating values, and produces actionable TODOs with owners or issue links when appropriate.

When to use it

• When adding documentation to a new file or module
• When reviewing code and deciding which comments belong inline
• When writing function or method contracts that AI tools or reviewers will parse
• When documenting non-obvious tradeoffs or temporary workarounds
• When preparing code for handoff to another team or future maintainers

Best practices

• Start each file with a short header stating purpose, relationships, and non-obvious reasons it exists
• Document the contract of a function (what it does, edge cases, side effects), not the implementation steps
• Use inline comments sparingly to explain why choices were made, not to restate obvious code
• Write architecture notes where design tradeoffs matter and include tradeoffs, mitigation, and where to find related code
• Make TODOs actionable: include owner, blocking issue, and expected removal condition

Example use cases

• Add a file header explaining why a context provider exists instead of Redux and who consumes it
• Write a function doc that clarifies return value semantics and when callers must check canShipTo()
• Insert an inline comment explaining a safe force-unwrap or a debounce timing choice backed by user testing
• Create an architecture note describing why event sourcing is used and how caching mitigates read-costs
• Convert vague TODOs into traceable, actionable tasks with issue links and owners