| name | exp-book |
| description | Use when starting debug tasks, fixing bugs, building new features, performance optimization, dependency migration, or automated testing. Also use after completing significant problem-solving sessions involving undocumented behavior, repeated failed attempts, or multi-step debugging. |
Exp-book
A searchable library of reusable team development experience.
When to Use
Before a task: Search for past solutions to avoid repeating known pitfalls.
After a task: Create a scroll only when the experience has reuse value — meaning a team member in a similar scenario would save significant time by reading it.
Write if any apply:
- Took wrong turns or multiple attempts before finding the correct approach
- Involved undocumented behavior, traps, or counter-intuitive decisions
- Established a reusable automation workflow or standard operating procedure
Do NOT write if:
- The solution is standard and well-documented (official docs cover it clearly)
- The experience is one-off project configuration with no transferable insight
- The insight is already captured in an existing scroll — update or supplement that scroll instead of creating a new one
Steps
Entry point:
- Triggered by CLAUDE.md (task just completed) → go directly to Write mode
- Triggered by user or task description (before task begins) → run Recall mode
Recall Mode (before task)
Step 1 - Locate the scrolls directory
Scrolls live in the references/ directory next to this SKILL.md.
If the directory is missing or empty, silently begin the task.
Step 2 - Extract search keywords
Extract 3–5 keywords from the task description, prioritized by:
- Error messages or error codes (most precise)
- Specific tech names: library, API, tool, framework names
- Problem patterns: e.g. "reconnect", "timeout", "CORS", "migration"
Avoid generic words like "fix", "bug", "error", "issue".
Step 3 - grep search
Resolve the references/ directory to its absolute path (sibling of this SKILL.md).
Use the Grep tool to search. Run one search per keyword. Deduplicate and merge results. Show at most 3 files, ranked by number of keyword hits; break ties by filename relevance to the task.
If zero hits on all keywords, try one broader synonym round before giving up.
Step 4 - Present results
On hits, read each file and output:
📚 Exp-book matches (N)
📖 {filename}
💡 Suggestion: {specific, actionable advice for the current task}
Keep the suggestion concise — extract only the parts relevant to the current task, not the full scroll content.
On no hits: silently begin the task, no message.
Write Mode (after task)
Step 1 - Generate filename
Lowercase English, hyphen-separated, describing the core problem:
- Good:
react-hooks-dependency-trap.md
- Good:
nextjs-image-cdn-cors.md
- Bad:
bug-fix.md (too vague)
Step 2 - Distill content
Write it as a note for the next Claude session that hits the same scenario. Optimize for machine readability in context — the scroll will be injected into a future conversation as reference.
Length target: 30–80 lines. If longer, cut background and keep conclusions.
Principles:
- Lead with the conclusion — what to do, how to do it. Background is secondary.
- Minimize "why" — only include enough context to know when this scroll applies. Skip the debugging journey.
- Be specific — exact commands, exact code patterns, exact config. Vague advice has no reuse value.
- Include anti-patterns — "don't do X" is as valuable as "do Y".
No fixed structure. A scroll might be a bug fix, a workflow, a code pattern, a process, or a correction to a bad habit.
Step 3 - Check for existing scrolls
Before writing, grep references/ for the core topic. If a related scroll already exists, update it (add new insights, anti-patterns, or scenarios) rather than creating a duplicate.
Step 4 - Write the file
Use the Glob tool to find the absolute path of this SKILL.md. Write the scroll to the sibling references/{filename}.md.
Then notify the user:
✅ Scroll saved: references/{filename}.md
Or if updating:
✅ Scroll updated: references/{filename}.md
