| name | documentation-updates |
| description | Update documentation based on lessons learned. Use after completing work to capture learnings and prevent future issues. |
Documentation Updates
Update documentation based on lessons learned from the conversation.
When to Use This Skill
Use this skill when:
- You made a mistake or misunderstanding that could have been prevented
- You discovered something that should be documented for future reference
- The user asks you to "reflect" on what happened
- After completing work where documentation gaps were discovered
Process
Momentarily pause any other actions to review the conversation and
reflect on any mistakes or misunderstandings. Update any/all of the
following as appropriate:
Files to Update
-
Project-level documentation:
AGENTS.md in the current projectCLAUDE.md in the current project- Any project-specific documentation
-
Global documentation:
- Global
AGENTS.md (~/.claude/AGENTS.md or similar)
- Global
CLAUDE.md
-
Agent settings:
- Per-project settings (
.claude/settings.json, opencode.json)
- Per-project agent skills in
.agents/skills
- Global settings (
~/.config/opencode/opencode.json, ~/.claude/settings.json)
- Global agent skills in
~/.agents/skills
-
Other project documentation:
- README.md
- Design documents
- Architecture guides
Bear in mind that many global files for agent config and skills are stowed
via GNU Stow using symlinks which point back to a git repo somewhere.
What to Document
- Common pitfalls encountered and how to avoid them
- Important constraints or requirements discovered
- Useful patterns or approaches found effective
- Mistakes made and what should have been done differently
- Configuration or setup nuances
Important Rule
Do NOT resume ANY previous actions until the user is satisfied that the
docs have been appropriately updated.
Output
After updating documentation:
- List the files that were modified
- Summarize the changes made
- Confirm with the user that the updates are adequate
