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 project

• CLAUDE.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