By version: "1.0.0" name: learn description: > Extract non-obvious session learnings into scoped files. Activate after non-trivial tasks to capture fragile config, quirks, or breakthroughs. category: knowledge-management allowed-tools: Read Write Edit Grep Glob license: MIT
Learn
Extract non-obvious session learnings into scoped files to preserve knowledge across sessions.
When to Use
Activate after completing a non-trivial task to capture insights that would otherwise be lost.
Instructions
What to Capture (Non-Obvious Only)
- Hidden relationships between files or scripts not obvious from code.
- Execution paths that differ from what the code appears to do.
- Non-obvious config, env vars, or flags.
- Debugging breakthroughs where error messages were misleading.
- Files that must change together (e.g.,
AGENTS.md+ skill files when adding skills). - Build/test commands not documented in README.
- Architectural constraints discovered at runtime.
What NOT to Capture
- Obvious documentation or standard behavior.
- Duplicates of existing entries.
- Verbose explanations or session-specific notes.
Scoping Rules
Place learnings in the most specific location:
- Project-wide:
agents-docs/LEARNINGS.md. - Script-specific:
scripts/AGENTS.md. - Skill-specific:
.agents/skills/<name>/AGENTS.md.
Format
- 1–3 lines per insight.
- Bulleted list in the appropriate scoped file.
- No duplicates of existing entries.
Example
After debugging a Turso sync issue:
## Learnings (Project-Wide)
- **Turso Sync**: Database must be open in read mode during sync operations; write locks cause intermittent failures
Reference Files
AGENTS.md- Root agent guidance and constraints.agents-docs/LEARNINGS.md- Project-wide learnings.plans/- ADRs and phase plans.