learn-and-improve

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.

Symptom	Likely Cause	Fix Location
Permission prompt for a bash command	Missing allow rule	settings.json permissions.allow
Permission prompt for file read/write	Missing path pattern	settings.json permissions.allow
Skill not triggering	Bad description triggers	Skill SKILL.md frontmatter
Skill triggering on wrong tasks	Description too broad	Skill SKILL.md frontmatter
Repeated instructions ignored	Not in CLAUDE.md	CLAUDE.md (appropriate level)
Convention not followed per-filetype	No path-scoped rule	.claude/rules/ with paths frontmatter
Agent hitting permission walls	Agent lacks permissionMode	Agent frontmatter
MCP tool requiring permission	Missing MCP allow rule	settings.json permissions.allow
Hook not firing	Wrong matcher or event	settings.json hooks

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:

Improvement Type	Best For	Who Benefits
Skill fix (external plugin)	Fixing behavior everyone hits — opens a PR upstream	All users of the skill
Skill fix (personal skill)	Your custom workflows across all projects	You, all projects
Agent fix (external plugin)	Agents that hit permission walls or use wrong model	All users of the agent
User-level settings	Permission rules and preferences that apply everywhere	You, all projects
User-level CLAUDE.md	Coding conventions and instructions you always want	You, all projects
Project-shared settings	Team permissions and conventions	Your team, one project
Project-shared CLAUDE.md	Architecture notes, project-specific patterns	Your team, one project
Project-local settings	Personal overrides for one project	Just you, one project
Hook	Automating repetitive steps (formatting, tests, safety) — delegate to toolkit:claude-code-hook-development skill for non-trivial hooks	Depends on scope
Project rules (.claude/rules/)	File-type-scoped conventions (API rules, test rules, frontend rules) — delegate to toolkit:claude-code-memory-and-rules skill for setup	Your team, one project
User rules (~/.claude/rules/)	Personal conventions across all projects	Just you, all projects
Auto memory	Session learnings that don't belong in CLAUDE.md — delegate to toolkit:claude-code-memory-and-rules skill for setup	You, one project

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