Refine
Review this session. Identify patterns worth capturing as new skills, improvements to existing skills, or additions to CLAUDE.md.
Step 1: Scan the session
Identify what happened:
- Which skills were invoked (look for tags) or created?
- What corrections did the user make? These are the most valuable signals.
- What workflows were repeated?
- What preferences or conventions emerged?
Step 2: Evaluate the skills
If skills were created or edited this session, they're already in your context — no need to re-read them. Evaluate what you already have.
If skills were used but not edited, read the actual SKILL.md files to see their current state. Check these locations:
bash
ls -la ~/.claude/skills/ 2>/dev/null
ls -la .claude/skills/ 2>/dev/null
ls -la ~/.refined/ 2>/dev/null
For each skill, whether from context or from reading, evaluate:
- Is the description specific enough to trigger correctly?
- Are the instructions clear and complete based on how the skill was actually used?
- Did the session reveal gaps, edge cases, or missing steps?
- Are references to other files/skills correct?
Check ownership before editing:
- Symlink → : yours to refine
- Symlink → a plugin dir: read-only (updates would overwrite)
- Regular file in or : yours to refine
- Anything in : read-only (managed by )
Also read the project's CLAUDE.md (and
if relevant). Check whether what happened in this session — tool preferences, conventions, corrections — is reflected there or should be.
Step 3: Decide
After evaluating skills and CLAUDE.md, ask three questions:
Existing skills — for each one you read:
- Does the description match how it was actually used? If not, fix it.
- Did the session expose missing instructions, wrong assumptions, or incomplete steps?
- Did the user correct something the skill should have known?
New skills — for the session overall:
- Was there a repeated workflow that has no skill yet?
- Was there hard-won knowledge (debugging, research) worth preserving?
- Was there a correction that indicates a process worth capturing?
CLAUDE.md — for general preferences and behavioral instructions:
- Did the user correct a general behavior (not tied to a specific workflow)?
- Is there a tool preference, communication style, or project convention worth persisting?
- Examples: "always use uv", "don't ask before committing", "use rip instead of rm"
"Nothing to refine" is a valid conclusion — but only after genuine evaluation. The point is thoroughness, not volume. If skills are solid, say so. Just don't skip the thinking.
Constraints: max 2 skills touched per refine, max 1 new skill per refine.
Step 4: Edit
Skills
Refining an existing skill: first
to check if it's a symlink.
- Symlink to → edit the target file in
- Symlink to a plugin dir or → do NOT edit (read-only — managed externally)
- Regular file in or → edit in place
Creating a new skill: ask the user which scope:
- User skill — useful across all projects. Write to
~/.refined/<name>/SKILL.md
- Local/repo skill — specific to the current project. Write to
.claude/skills/<name>/SKILL.md
CLAUDE.md
Always ask before editing CLAUDE.md. Show the proposed addition and ask the user to confirm.
- Only append — never modify or remove existing entries
- Keep additions concise (1-3 lines per entry)
- Choose the right file:
- — global preferences (affect all projects)
- or in project root — project-specific
Why refine doesn't touch externally managed skills
Two categories of skills are read-only:
Plugin skills (invoked as
) — namespaced and versioned by their plugin.
- Editing in place breaks on update.
- Copying creates ambiguity — user skill names can't contain colons, so a copy of would need a different name. Two similar skills, agent doesn't know which to pick.
Skills installed via — managed by the
vercel-labs/skills CLI, typically symlinked from
.
- would overwrite your changes.
- These are designed to be shared across agents (Claude, Cursor, Cline, etc.).
The ideal future: everyone starts from base skills that get better for their personal use over time. That needs skill override support at the platform level.
For now, if an external skill needs improving: contribute upstream or fork.
Note:
is itself a valid source for
npx skills add ~/.refined
— so refined skills can be shared with other agents or users.
Step 5: Link, track, and commit
For each new or modified skill, ask the user whether to git track it (default: yes for user skills, no for local/repo skills).
User skills (written to
):
bash
# Symlink into ~/.claude/skills/ (-n flag handles directory symlinks correctly)
ln -sfn "$HOME/.refined/<name>" "$HOME/.claude/skills/<name>"
# Optional: also link into .agents/skills/ for cross-agent compatibility (Cursor, Cline, etc.)
# Only if the user uses npx skills / multi-agent setup
# mkdir -p .agents/skills && ln -sfn "$HOME/.refined/<name>" .agents/skills/<name>
# If git-tracked:
git -C "$HOME/.refined" add <name>/ && git -C "$HOME/.refined" commit -m "refine: <what changed and why>"
Local/repo skills (written to
in the project):
bash
# Commit in the project repo if the user wants
git -C <project-root> add .claude/skills/<name>/ && git -C <project-root> commit -m "refine: <what changed and why>"
Existing skills (edited in place): commit in whichever repo the file belongs to.
Skill file format
yaml
---
name: skill-name
description: >
What this skill does. Be specific — this description decides when
the skill triggers, so vague descriptions mean it never gets used.
allowed-tools:
- Read
- Edit
# only what the skill actually needs
---
The body is the prompt Claude receives when the skill is invoked. Write it as direct instructions.
Constraints
- Max 2 skills touched per refine. Max 1 new skill per refine.
- A skill should be under 200 lines. Longer means it's doing too much.
- Prefer refining an existing skill over creating a new one.
- Never edit externally managed skills (plugins, installs) — they get overwritten on update.
- Always check symlink targets before editing — don't follow symlinks into plugin dirs or .
- Don't create skills for one-off tasks that won't recur.
- Don't capture things obvious from reading code or CLAUDE.md.
- Always ask before editing CLAUDE.md. Only append, never modify existing entries.
Output
One-line summary of what you did (or "nothing to refine").