doc-update
Use when code has changed and documentation may be out of date — identifies stale docs, finds gaps between implementation and docs, and applies targeted updates.
Install
npx skills add https://github.com/drvoss/everything-copilot-cli/tree/main/skills/documentation/doc-update
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install drvoss-everything-copilot-cli@llmmart
git clone https://github.com/drvoss/everything-copilot-cli.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole drvoss/everything-copilot-cli collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Documentation Update
When to Use
- After making code changes that affect documented behavior
- During periodic documentation maintenance
- When onboarding reveals gaps or inaccuracies in docs
- Before a release to ensure docs match the current state
- When users report confusing or incorrect documentation
Prerequisites
- Access to the project's documentation files (README, docs/, wiki)
- Understanding of recent code changes or current behavior
- Ability to run the project to verify documented examples
Workflow
1. Inventory Existing Documentation
# Find all documentation files
# (Copilot glob tool) pattern="**/*.md"
# Find inline documentation (JSDoc, docstrings)
grep -rn "/\*\*" src/ --include="*.ts" | Measure-Object -Line
grep -rn '"""' src/ --include="*.py" | Measure-Object -Line
# List docs by last modified date
Get-ChildItem -Recurse -Include *.md | Sort-Object LastWriteTime | Select-Object LastWriteTime, FullName
2. Identify Stale Documentation
# Find docs that reference renamed or deleted files
grep -rn "import.*from\|require(" docs/ --include="*.md" 2>$null
# Find docs referencing old function names or APIs
grep -rn "function_name\|ClassName\|/api/v1" docs/ --include="*.md"
# Compare documented CLI flags with actual implementation
grep -rn "\-\-[a-z]" README.md | Select-Object -First 20
Use the explore agent for deeper analysis:
task agent_type: "explore"
prompt: "Compare the README.md setup instructions with the actual package.json scripts and config files. Identify any mismatches."
3. Update Content
For each stale section:
- Read the current code to understand actual behavior
- Update the doc to match reality using
edit - Test any code examples to verify they work
# Verify a documented command still works
npm run documented-command 2>&1 | Select-Object -First 5
4. Check Links
# Find all markdown links
grep -rn "\[.*\](.*)" docs/ --include="*.md" | Select-String "http"
# Find internal links and verify targets exist
grep -rn "\[.*\](\./\|\.\./" docs/ --include="*.md"
5. Improve Structure
- Add a table of contents for long documents
- Break monolithic docs into focused pages
- Add "Last updated" dates to critical docs
- Ensure consistent formatting and heading levels
6. Validate the Update
# Check for broken markdown syntax
grep -rn "]\s*$" docs/ --include="*.md" # Unclosed links
# Verify code blocks have language tags
grep -n '```$' docs/**/*.md # Code blocks without language specifier
# Run any doc-specific tests or linters
npx markdownlint docs/ 2>&1 | Select-Object -First 20
Examples
Update README After API Change
# 1. Find what changed
git --no-pager log --oneline -10 -- src/api/
# 2. Check if README references the changed API
grep -n "api\|endpoint\|route" README.md
# 3. Update the relevant section
# Use edit tool to modify the specific outdated section
Sync JSDoc with Implementation
# Find functions where JSDoc params don't match actual params
grep -B 5 "function " src/utils.ts | Select-String "@param|function"
# Update JSDoc to match the current signature
Bulk Fix Renamed References
# If a module was renamed from 'utils' to 'helpers'
grep -rn "utils" docs/ --include="*.md"
# Use edit tool on each file to update references
Common Rationalizations
| Rationalization | Reality |
|---|---|
| "The code is the documentation" | Code explains what. Documentation explains why. They're complementary, not interchangeable. |
| "Too busy, I'll update docs later" | Context is lost by the next PR. Update docs alongside the change. |
| "It's an internal API, no docs needed" | Your future self in 3 months is also an internal API consumer. |
| "The README is already up to date" | Compare the last README update timestamp to the last code change. |
Red Flags
- Code change PRs with no documentation update
- README examples that don't match the current API
- Breaking changes not recorded in the CHANGELOG
- Removed features still present in the documentation
Verification
- Documentation update exists for every changed public API
- README code examples run successfully on the current version
- Breaking changes are recorded in the CHANGELOG
- New environment variables or configuration options are documented
Tips
- Update docs in the same PR as code changes — don't defer it
- Write docs for your audience: READMEs for users, inline docs for developers
- Include working code examples — broken examples are worse than no examples
- Use
taskagent to run documented commands and verify they produce expected output - Keep a CHANGELOG.md updated with each release
- If a doc is consistently wrong, consider generating it from code (e.g., API docs from schemas)
Files (everything-copilot-cli)
-
SKILL.md 5.1 KB
--- name: doc-update license: MIT description: Use when code has changed and documentation may be out of date — identifies stale docs, finds gaps between implementation and docs, and applies targeted updates. metadata: category: documentation agent_type: general-purpose --- # Documentation Update ## When to Use - After making code changes that affect documented behavior - During periodic documentation maintenance - When onboarding reveals gaps or inaccuracies in docs - Before a release to ensure docs match the current state - When users report confusing or incorrect documentation ## Prerequisites - Access to the project's documentation files (README, docs/, wiki) - Understanding of recent code changes or current behavior - Ability to run the project to verify documented examples ## Workflow ### 1. Inventory Existing Documentation ```powershell # Find all documentation files # (Copilot glob tool) pattern="**/*.md" # Find inline documentation (JSDoc, docstrings) grep -rn "/\*\*" src/ --include="*.ts" | Measure-Object -Line grep -rn '"""' src/ --include="*.py" | Measure-Object -Line # List docs by last modified date Get-ChildItem -Recurse -Include *.md | Sort-Object LastWriteTime | Select-Object LastWriteTime, FullName ``` ### 2. Identify Stale Documentation ```powershell # Find docs that reference renamed or deleted files grep -rn "import.*from\|require(" docs/ --include="*.md" 2>$null # Find docs referencing old function names or APIs grep -rn "function_name\|ClassName\|/api/v1" docs/ --include="*.md" # Compare documented CLI flags with actual implementation grep -rn "\-\-[a-z]" README.md | Select-Object -First 20 ``` Use the `explore` agent for deeper analysis: ```text task agent_type: "explore" prompt: "Compare the README.md setup instructions with the actual package.json scripts and config files. Identify any mismatches." ``` ### 3. Update Content For each stale section: 1. **Read the current code** to understand actual behavior 2. **Update the doc** to match reality using `edit` 3. **Test any code examples** to verify they work ```powershell # Verify a documented command still works npm run documented-command 2>&1 | Select-Object -First 5 ``` ### 4. Check Links ```powershell # Find all markdown links grep -rn "\[.*\](.*)" docs/ --include="*.md" | Select-String "http" # Find internal links and verify targets exist grep -rn "\[.*\](\./\|\.\./" docs/ --include="*.md" ``` ### 5. Improve Structure - Add a table of contents for long documents - Break monolithic docs into focused pages - Add "Last updated" dates to critical docs - Ensure consistent formatting and heading levels ### 6. Validate the Update ```powershell # Check for broken markdown syntax grep -rn "]\s*$" docs/ --include="*.md" # Unclosed links # Verify code blocks have language tags grep -n '```$' docs/**/*.md # Code blocks without language specifier # Run any doc-specific tests or linters npx markdownlint docs/ 2>&1 | Select-Object -First 20 ``` ## Examples ### Update README After API Change ```powershell # 1. Find what changed git --no-pager log --oneline -10 -- src/api/ # 2. Check if README references the changed API grep -n "api\|endpoint\|route" README.md # 3. Update the relevant section # Use edit tool to modify the specific outdated section ``` ### Sync JSDoc with Implementation ```powershell # Find functions where JSDoc params don't match actual params grep -B 5 "function " src/utils.ts | Select-String "@param|function" # Update JSDoc to match the current signature ``` ### Bulk Fix Renamed References ```powershell # If a module was renamed from 'utils' to 'helpers' grep -rn "utils" docs/ --include="*.md" # Use edit tool on each file to update references ``` ## Common Rationalizations | Rationalization | Reality | |----------------|---------| | "The code is the documentation" | Code explains *what*. Documentation explains *why*. They're complementary, not interchangeable. | | "Too busy, I'll update docs later" | Context is lost by the next PR. Update docs alongside the change. | | "It's an internal API, no docs needed" | Your future self in 3 months is also an internal API consumer. | | "The README is already up to date" | Compare the last README update timestamp to the last code change. | ## Red Flags - Code change PRs with no documentation update - README examples that don't match the current API - Breaking changes not recorded in the CHANGELOG - Removed features still present in the documentation ## Verification - [ ] Documentation update exists for every changed public API - [ ] README code examples run successfully on the current version - [ ] Breaking changes are recorded in the CHANGELOG - [ ] New environment variables or configuration options are documented ## Tips - Update docs **in the same PR** as code changes — don't defer it - Write docs for your audience: READMEs for users, inline docs for developers - Include **working** code examples — broken examples are worse than no examples - Use `task` agent to run documented commands and verify they produce expected output - Keep a CHANGELOG.md updated with each release - If a doc is consistently wrong, consider generating it from code (e.g., API docs from schemas)
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.