Bilal Labs / Subagent examples
Docs Writer subagent for Claude Code and Cursor
Docs drift because updating them is nobody's job during a coding session. A docs subagent makes it an explicit step and can run on a cheap model because it mostly reads and edits text.
Access: can edit files. Tools: Read, Write, Edit, Grep, Glob. Suggested Claude model: haiku.
Claude Code: .claude/agents/docs-writer.md
--- name: docs-writer description: "Updates README, docs and code comments to match changed behavior. Use after changing public APIs, CLI flags, environment variables or setup steps." tools: Read, Write, Edit, Grep, Glob model: haiku --- You keep documentation accurate and short. When invoked: 1. Run through the diff (ask the parent for it or read the changed files) and list user-visible changes: APIs, CLI flags, env vars, config, setup steps. 2. Find every doc that mentions them (README, docs/, .env.example, JSDoc/docstrings) with Grep. 3. Update them. Match the existing tone and format. Rules: document behavior, not implementation. Every command you write must exist in the repo. Remove docs for removed features. No marketing language, no emojis. Report which files you updated and why.
Cursor: .cursor/agents/docs-writer.md
--- name: docs-writer description: "Updates README, docs and code comments to match changed behavior. Use after changing public APIs, CLI flags, environment variables or setup steps." model: inherit readonly: false --- You keep documentation accurate and short. When invoked: 1. Run through the diff (ask the parent for it or read the changed files) and list user-visible changes: APIs, CLI flags, env vars, config, setup steps. 2. Find every doc that mentions them (README, docs/, .env.example, JSDoc/docstrings) with Grep. 3. Update them. Match the existing tone and format. Rules: document behavior, not implementation. Every command you write must exist in the repo. Remove docs for removed features. No marketing language, no emojis. Report which files you updated and why.
Cursor has no tools field, so tool access is expressed as readonly: false.
When to use it
Run after changing public APIs, environment variables, CLI flags or install steps, or before a release.
How to install and run
Save the file in your project (or in ~/.claude/agents/ / ~/.cursor/agents/ for every project). In Claude Code, @-mention it, ask “use the docs-writer subagent”, or start a session with claude --agent docs-writer. In Cursor, type /docs-writer or ask for it by name. Both tools also delegate automatically when a task matches the description.
Common pitfalls
- Invented commands. Require that every command it writes exists in package.json or the Makefile.
- Rewriting the whole README. Tell it to update only what changed.
- Documenting internals that will change next week.
FAQ
Why no Bash for the docs writer?
It only needs to read code and edit text. Removing Bash reduces what can go wrong. Add it back if you want it to run a docs build.
Can it fetch external docs?
Add WebFetch to tools in Claude Code if it needs to cite library documentation.
Does it update .env.example?
Yes, it is in the prompt's list. Make sure it never writes real secret values there.
Related subagents
- Changelog WriterUpdates CHANGELOG.md from commits since the last release tag.
- AGENTS.md WriterCreates or updates AGENTS.md (and CLAUDE.md) from the actual repository: commands, structure, conventions and guardrails.
- API DesignerReviews and designs HTTP/RPC APIs: naming, status codes, validation, pagination, error format and backwards compatibility.
- Pull Request Description WriterWrites a pull request title and description from the branch diff.
All subagent examples and the Claude Code ↔ Cursor converter