improve-skill

Improve Skill

Skills get better through real use. Edge cases surface, templates need tweaking, instructions turn out ambiguous, tool conventions shift. This skill makes those updates carefully — without losing the design intent that's already encoded in the skill.

The user is the one giving feedback, and they may not be the person who wrote the skill. Often they don't know why a skill is structured the way it is. Your central job is to give them that context — concisely, without arguing — so they make the change with their eyes open. The skill becomes more useful when they're empowered, less useful when they're confused.

Workflow

1. Identify the target skill
2. Classify the change          → references/change-types.md
3. Restate the request
4. Explain current behavior     → references/explain-framework.md
   (skip for typos; keep light for wording)
5. Propose the specific edit
6. Apply on confirmation + update CHANGELOG.md

Read both reference files at the start of every run. They're short and load-bearing.

Step 1: Identify the target skill

Two ways the target can be specified:

• Explicit name in the user's request: "improve the send-prospect-confirms skill"
• Just-ran default: if no name was given, the target is the skill that most recently executed in this chat. Look back through the conversation for the latest skill invocation. If you can't unambiguously identify one, ask — don't guess.

Locate the folder. In Claude Code, skills typically live under .claude/skills/<name>/ and may be symlinks. Resolve with ls -la .claude/skills/<name> to see the real source path. In Claude Desktop, skills live in the user's Desktop skills directory. Read SKILL.md and every file in references/ so you have full context on the current behavior. If the folder doesn't exist, ask for the correct path. Don't fuzzy-match aggressively.

Step 2: Classify the change

Different changes need different rigor. Read references/change-types.md and pick the lane:

Type	Example	What changes from default workflow
Wording / typo	"fix the typo in step 3"	Skip Step 4 (no explanation needed). Show the edit, apply on confirm.
Template tweak	"use pt instead of pacific in the tz word"	Light Step 4: one sentence on why the current convention exists.
Logic change	"stop checking HubSpot, calendar always has the phone"	Full Step 4 with design intent + tradeoffs.
Architectural	"split this into two skills" / "restructure the workflow"	Out of scope for this skill. Recommend skill-creator instead. Decline politely and summarize what they'd want to do there.

When in doubt, default to one lane heavier. The cost of a sentence of context is small; the cost of an unintended change is large.

Step 3: Restate the request

Restate the change in your own words, with this template:

Change requested: [verb] [target] [scope]
Source: [explicit user statement / flagged from recent run / inferred from feedback]
Classification: [wording / template / logic / architectural]

Wait for confirmation on the restatement before going further. This catches misunderstandings cheaply, before any explanation or proposed edit.

If the user simply says "yes" or nods, proceed. If they correct you, re-state and re-confirm.

Step 4: Explain current behavior — and why

Read references/explain-framework.md and follow the template. Tailor depth to the classification:

• Typo: skip entirely.
• Wording / template tweak: one or two sentences. Name the rule, cite the line, state the design intent in one phrase.
• Logic change: 3-5 sentences. Name the rule, cite the line, explain the design intent, surface what changes if you flip it.

Be plain about uncertainty. If the design intent isn't documented and you can't infer it confidently, say so: "I don't see a documented reason for this — looks like an editorial choice. Happy to change it." Inventing a justification to defend the status quo erodes the user's trust faster than admitting you don't know.

Never argue. Explain once, then let the user decide.

Step 5: Propose the specific edit

Show:

File: <path within the skill folder>
Section: <heading or location>

Current:
<verbatim quote from the file>

Proposed:
<exact replacement text>

Then ask: Apply this change? Wait for an explicit yes.

For multi-line or multi-file edits, show each block separately. If a related edit is needed (e.g., changing a template means updating the example that uses it), surface it as a follow-up question after applying the primary change — don't batch.

Step 6: Apply + update CHANGELOG.md

On confirmation, make the edit surgically. Change exactly the text you proposed, nothing else. Don't reformat surrounding lines, don't tidy unrelated sections, don't "improve" things you weren't asked about. The user's mental model is built on the skill's current shape — preserve everything that wasn't part of the request.

After editing, append a one-line entry to CHANGELOG.md in the target skill folder. If the file doesn't exist, create it with a brief header. Format:

# Changelog

## YYYY-MM-DD
- [type] Brief description. (file:section)

Example entries:

# Changelog

## 2026-05-15
- [wording] Fixed typo in Step 3 "fallback" spelling. (SKILL.md)
- [template] Switched Arizona tz word from `arizona` to `pacific` during DST months. (references/template.md)
- [logic] Removed HubSpot phone fallback; calendar always has it. (SKILL.md:Step 3)

Confirm in one line: Updated [file]. Changelog entry added.

The changelog gives the user a way to ask "what changed recently?" or "undo the last change" without needing git history. Keep entries short — one sentence each. Don't re-explain reasoning in the changelog; the explanation already happened in the conversation.

Worked example

This is the shape of a good improve-skill interaction. Match this pattern.

User: the timezone format was wrong in the confirms — Arizona prospects in summer
      should see "pacific" not "arizona"

Agent: Change requested: update the [tz-word] rule so Arizona maps to `pacific`
       during DST months (June–October) instead of always `arizona`.
       Source: user feedback on recent run.
       Classification: template tweak.

       Is that right?

User: yes

Agent: The current rule lives in references/template.md, in the "Format rules" 
       section, line: 
       > US: `eastern`, `central`, `mountain`, `pacific`, `arizona`, `hawaii`, `alaska`

       It was set up to keep Arizona explicitly labeled because most of the state 
       doesn't observe DST — the explicit label distinguishes Arizona prospects 
       from California ones even though their clocks match in summer.

       If we map Arizona to `pacific` in summer, prospects in Arizona will see 
       the same wording as California prospects half the year. That's fine if 
       you're optimizing for "matches their actual clock" — slightly less fine 
       if you want the message to read distinctly per state.

       Want to proceed?

User: yeah, matches their clock matters more

Agent: File: references/template.md
       Section: Format rules → [tz-word] → Edge notes

       Current:
       - Arizona: most of Arizona doesn't observe DST, so it aligns with pacific 
         in summer. The tz word stays `arizona`.

       Proposed:
       - Arizona: most of Arizona doesn't observe DST. During DST months 
         (Mar–Nov), render as `pacific` to match the clock. Outside DST, 
         render as `mountain`.

       Apply this change?

User: yes

Agent: Updated references/template.md. Changelog entry added.

What not to do

• Don't propose changes the user didn't ask for. Stay in the scope they named.
• Don't rewrite a section when a one-line edit covers the request. Skills accumulate context; full rewrites lose it.
• Don't argue with the user about whether the change is a good idea. State the tradeoff once, let them decide.
• Don't apply an edit without explicit confirmation in chat. Even small edits compound — gating each one keeps the skill auditable.
• Don't fabricate the "why" behind current behavior. If you don't know, say so.
• Don't touch files outside the target skill's folder. If the user asks to change another skill, ask them to invoke improve-skill again with that one as the target.
• Don't update CHANGELOG.md unless an edit was actually applied. No "considered change but didn't make it" entries.

Edge cases

• Undo / revert request ("undo the last change you made"): read CHANGELOG.md, identify the most recent entry, re-derive the original text from the user's recall + git history if available, and propose reverting. Treat it as a normal change request — restate, propose, confirm, apply, log it.
• The user wants to know what changed recently ("what did we change last week?"): read CHANGELOG.md and summarize the relevant entries. Don't re-derive from file content — trust the log.
• No CHANGELOG.md exists yet: this is the first change being logged. Create the file with the header and the first entry as part of the apply step.
• Skill folder doesn't exist: ask for the correct path. Don't try to fuzzy-match three different names.
• Change request is ambiguous and one clarifying question doesn't resolve it: stop. Ask the user to articulate the change in concrete terms.
• Change spans multiple skills: decline to edit the others. Tell the user which other skills they'd need, and offer to invoke improve-skill against each in turn.
• A references/ file and the SKILL.md disagree after a change: surface this in one sentence. Ask whether to update the second location to match.
• Architectural change in disguise (the user describes a small change that actually requires restructuring): name the architectural nature in Step 2, recommend skill-creator, and offer a smaller scoped alternative if one exists.
• File write fails or permission denied: surface the error, don't retry silently. Let the user resolve it.

When the user says "just do it"

If the user explicitly skips the explanation ("don't explain, just change it"), honor that. The "explain why" step is the default because it usually adds value, not because it's a rule. When they want speed, give them speed.

Still write a CHANGELOG.md entry — that's the floor. If something goes wrong later, the log is how anyone (including the user) reconstructs what happened.