Code Documentationv1.1.0
Write or update docstrings, READMEs and API docs that match what the code actually does, verified by reading the implementation. Use when the user asks to document code, write a README, explain a module, or fix out-of-date docs.
- Author
- Velonx
- License
- MIT
- Updated
- Sep 25, 2026
Overview
Documentation that is accurate first and complete second. The agent reads the implementation, traces behaviour, and documents what the code does — including edge cases and errors — in the style already used by the project.
When to Use
- "Document this function / module / API", "write a README", "our docs are out of date"
- Before open-sourcing a project or handing it over.
Installation
velonx install code-documentationGet the skill folder
The skill isgit clone --depth 1 https://github.com/velonx/agent-skills.gitagent-skills/skills/code-documentation/. Or open it on GitHub and download the files.Give SKILL.md to your agent as instructions
Add it to the system prompt, custom instructions or rules file your agent reads. Keep the rest of the folder next to it if the skill refers to examples or scripts.Ask for the task in your own words
The agent follows the skill when your request matches it. You can also name it: “use code-documentation”.
Get the skill folder
The skill isgit clone --depth 1 https://github.com/velonx/agent-skills.gitagent-skills/skills/code-documentation/. Or open it on GitHub and download the files.Claude Code: copy it into a skills folder
Usecp -R agent-skills/skills/code-documentation ~/.claude/skills/.claude/skills/inside a project instead to share it with your team through git.Claude apps: upload it
Zip the folder and upload it under Settings → Capabilities → Skills.Ask for the task in your own words
The agent follows the skill when your request matches it. You can also name it: “use code-documentation”.
Get the skill folder
The skill isgit clone --depth 1 https://github.com/velonx/agent-skills.gitagent-skills/skills/code-documentation/. Or open it on GitHub and download the files.ChatGPT: add it to a GPT or project
PasteSKILL.mdinto the instructions, and upload files from the folder as knowledge if the skill uses them.API: send it as instructions
UseSKILL.mdas the system / developer message, or as agent instructions in your SDK.Ask for the task in your own words
The agent follows the skill when your request matches it. You can also name it: “use code-documentation”.
Get the skill folder
The skill isgit clone --depth 1 https://github.com/velonx/agent-skills.gitagent-skills/skills/code-documentation/. Or open it on GitHub and download the files.Gemini app: create a Gem
PasteSKILL.mdinto the Gem’s instructions.Gemini CLI or API
Add the contents to your project’sGEMINI.md, or pass it as thesystem_instructionin the API.Ask for the task in your own words
The agent follows the skill when your request matches it. You can also name it: “use code-documentation”.
Get the skill folder
The skill isgit clone --depth 1 https://github.com/velonx/agent-skills.gitagent-skills/skills/code-documentation/. Or open it on GitHub and download the files.Add it as a project rule
Create.cursor/rules/code-documentation.mdcand paste the body ofSKILL.md. Use the skill’s description as the rule description so the agent applies it when relevant.Keep the folder in your repo
Only needed if the skill refers to examples or scripts.Ask for the task in your own words
The agent follows the skill when your request matches it. You can also name it: “use code-documentation”.
Agents move these settings between versions — if a path doesn’t match, check your agent’s docs.
Usage
- Detect conventions. Find existing docstrings and docs; match their format (JSDoc, Google/NumPy docstrings, rustdoc…), tone and heading structure. If none exist, use the language's most common convention.
- Read the code path, not just the signature: inputs, outputs, side effects (I/O, network, mutation), thrown errors, defaults.
- Docstrings: one-line summary; parameters and return value only when not obvious from types; side effects; errors raised; a short example for public APIs. Don't restate the code.
- README in this order: what it is (one sentence) → install → minimal working example → configuration → common tasks → contributing/license. Test that every command and snippet you include actually matches the code (script names, flags, env vars).
- Mark uncertainty. If behaviour is ambiguous, leave a
TODO(docs):note rather than guessing. - Keep diffs limited to docs unless asked to change code.
Examples
Prompt: "Add docstrings to billing/invoice.py."
The agent notices the project uses Google-style docstrings, reads each function, documents that finalize() raises InvoiceLockedError if already sent, and skips trivial private helpers.
Requirements & compatibility
Your agent needs
- Read and write local files
Written for
Limitations
- Cannot document runtime behaviour it can't see (external services, env-specific config) — flags those.
- Does not generate API reference sites; it writes the source docs those tools consume.
Files
Changelog
- 1.1.0 — Verifies README commands against the code;
TODO(docs)for uncertain behaviour. - 1.0.0 — Initial release.
Contributing
This skill lives in velonx/agent-skills. Improvements go through a pull request, reviewed by maintainers.