Learn and Improve

Analyze friction in the current session and propose targeted improvements to Claude Code configuration.

Workflow

Step 1: Understand the Problem

Ask the user what went wrong. If they've already described the issue, confirm your understanding.

Use AskUserQuestion to clarify:

• What happened? (e.g., "skill X asked for permission to run Y")
• What should have happened? (e.g., "it should just run without asking")
• How often does this occur? (one-off vs recurring)

Step 2: Gather Diagnostic Context

Investigate the current configuration by reading these files (read only what exists):

Settings (permissions, hooks, env):

• ~/.claude/settings.json (user-level)
• .claude/settings.json (project-level, shared)
• .claude/settings.local.json (project-level, local)

Memory (CLAUDE.md hierarchy):

• ~/.claude/CLAUDE.md (user-level)
• ./CLAUDE.md or ./.claude/CLAUDE.md (project-level)
• ./CLAUDE.local.md (local overrides)
• ./.claude/rules/*.md (modular rules)

Auto memory:

• ~/.claude/projects/*/memory/MEMORY.md for the current project

Plugins & skills:

• .claude-plugin/marketplace.json (if in a plugin repo)
• Installed plugins: ~/.claude/plugins/cache/ (list directories)
• Installed marketplaces: ~/.claude/plugins/marketplaces/ (list directories)

MCP servers:

• .mcp.json (project)
• ~/.claude.json or ~/.claude/mcp.json (user)

Also review the conversation history for:

• Tool calls that were blocked or required permission prompts
• Skills that were invoked (or should have been but weren't)
• Agents that were spawned and their outcomes
• Error messages or unexpected behavior

Step 3: Identify the Root Cause

Common root causes and their fixes — see Improvement Types for full details.

Step 4: Propose Improvements

In addition to fixing the reported issue, review the session for commands that were prompted for permission but are read-only and side-effect free (e.g., ls, gh pr view, git log). Suggest permanently allowing these — at user level for read-only commands, project level for write commands. See Improvement Types for examples.

For each proposed improvement, present:

1. What to change — the specific file and content
2. Why — how this fixes the reported issue
3. Who benefits — see the table below to explain the reach of the improvement
4. Risk — any trade-offs (e.g., "this auto-allows all npm commands")

Explain the reach of each improvement type to help the user decide:

When an improvement could live at multiple scopes, present the options and explain the trade-off — broader scope means more reuse but also more risk if the change is wrong.

Step 5: Apply the Change

Apply the approved change to the correct file. After applying:

1. Verify the file is valid JSON (for settings files) or valid markdown (for CLAUDE.md)
2. Tell the user if a restart is needed (hooks require restart; skills/CLAUDE.md do not)
3. If the fix is to an external skill or plugin, propose opening a PR instead

Step 6: Record the Verified Improvement (ESSENTIAL)

Every user-approved improvement is a verified data point. This skill is self-improving — each fix makes it better for the next person.

After the user confirms the improvement works, append a summary to Verified Improvements using this format:

### [Short title]
- **Friction**: [What went wrong]
- **Fix**: [What was changed and where]
- **Scope**: [Who benefits — e.g., "all users of toolkit:research"]

Keep entries concise (3 lines max). This log serves two purposes:

1. Examples for future invocations — Claude reads these to pattern-match similar problems faster
2. Evidence for skill evolution — patterns in the log reveal common friction that should be addressed in the skill itself or its references

If the log grows beyond ~30 entries, consolidate repeated patterns into the root cause table in Step 3 and remove the individual entries.

Important Constraints

• Never modify managed/enterprise settings — those are IT-controlled
• Always confirm before writing — show the exact change first
• Consider the reach — explain who benefits from each improvement type so the user can choose the right scope
• Preserve existing content — merge into existing settings, don't overwrite
• Settings format: permission rules use Tool(pattern) syntax (e.g., Bash(npm run *))

Quick Reference

For the full catalog of improvement types and examples, see:

• Improvement Types — all configuration levers with examples
• Diagnostic Checklist — systematic investigation steps

References

• agents.md outperforms skills in agent evals — Vercel research showing that CLAUDE.md-style agent instructions outperform skill-based routing in evaluations