Self-Improve Skill

Analyze the current conversation and propose improvements to skills based on corrections, successes, and edge cases discovered during the work session.

Triggers

• self-improve – Analyze session and propose improvements
• self-improve [skill-name] – Target a specific skill
• self-improve on – Enable automatic mode (hook)
• self-improve off – Disable automatic mode
• self-improve status – Show automatic mode status
• self-improve [skill-name] history – Show modification history

Main Workflow (self-improve)

Step 1: Identify the Skill

If skill name not provided, list available skills from skills/ directory and ask:

Which skill should I analyze for this session?
[List skills found in skills/ directory]

Step 2: Detect Signals

Scan the conversation for signals – moments where the user expressed feedback:

Step 3: Evaluate Each Signal for Quality

For each correction signal, evaluate if it can become a good skill instruction.

Quality Criteria

1. COMPLETE

The instruction includes all information needed to apply it. No need to look elsewhere or make assumptions.

2. PRECISE

No vague or subjective terms. Two different people reading the instruction would understand it the same way.

3. ATOMIC

One instruction addresses one single requirement. Multiple checks should be split into separate instructions.

4. STABLE

If referencing regulations or standards, specify the version or date. The instruction should be evaluable the same way regardless of when it’s read.

Step 4: Grade the Signal

Step 5: Ask for Clarification

When feedback doesn’t meet all criteria, ask for what’s missing using the AskUserQuestion tool:

I detected a correction but need more information to improve the skill.

You said: "[user's feedback]"

To create a clearer instruction, I need the following information: 

[Structured tool call listing what's missing based on failed criteria]

If the user provides clarification → Update the instruction and proceed to Step 6.

If the user prefers the original → Proceed to Step 6 with the original instruction.

Step 6: Propose Changes

--- Learning: [skill-name] ---

Proposed additions:

1. "[exact instruction to add]"
   Source: "[quote from conversation]"

2. "[exact instruction to add]"
   Source: "[quote from conversation]"

---

Apply these changes? [Y/n]

Step 7: If Approved

1. Update SKILL.md

   • Read skills/[skill-name]/SKILL.md
   • Add each instruction in the appropriate section
   • Each instruction must be readable and applicable on its own

2. Update skills/[skill-name]/CHANGELOG.md

   • Create if doesn’t exist
   • Add new entry AT THE TOP:

     ## [DATE (format: "January 7, 2026")]
     [Description of changes in natural language, 1-3 sentences]
     

   • Entry rules:
     • Most recent at top
     • 1-3 sentences max
     • Natural language
     • No git references

Step 8: Save Observations

For signals that couldn’t be processed, offer to save:

Save these observations for later review?
- "[signal 1]" - Status: [why insufficient]
- "[signal 2]" - Status: [why insufficient]

If yes, append to skills/[skill-name]/OBSERVATIONS.md

Secondary Commands

self-improve on

1. Run:

   rm -f ./.disabled
   

2. Reply: “Automatic mode enabled.”

self-improve off

1. Run:

   touch ./.disabled
   

2. Reply: “Automatic mode disabled.”

self-improve status

Check .disabled file existence and report.

self-improve [skill-name] history

1. Display CHANGELOG.md content
2. Ask: “Would you like to revert to a previous version?”
3. If yes:
   • update the appropriate sections in skills/[skill-name]/SKILL.md
   • update skills/[skill-name]/CHANGELOG.md with a rollback note

Examples

Example 1: All criteria met

User said: “Always flag non-compete clauses over 12 months as high risk”

Evaluation:

• Complete: Yes – instruction is fully specified
• Precise: Yes – “12 months” and “high risk” are clear
• Atomic: Yes – single check
• Stable: Yes – no time dependency

Result: Add directly

Example 2: Missing criteria

User said: “Flag any non-market-standard indemnification clause”

Evaluation:

• Complete: No – “non-market-standard” is not defined
• Precise: No – “market standard” is subjective and varies by deal type
• Atomic: Yes – single check
• Stable: No – market standards evolve over time

Action: Ask for clarification using the AskUserQuestion tool:

I detected a correction but need more details.

You said: "Flag any non-market-standard indemnification clause"

To make this actionable, can you specify:
- What makes an indemnification clause "non-market-standard"? (e.g., uncapped liability, coverage of indirect damages, no carve-outs for gross negligence)

Do you want to provide more details, or should I add the instruction as you stated it?

If user clarifies: Update the instruction and add it. If user prefers the original: Add the instruction as stated.

Important Notes

• Never guess what the user meant – always ask if unclear
• Never infer requirements from context – they must be explicit
• One instruction = one check – split bundled feedback
• Fewer good instructions is better than many vague ones
• CHANGELOG.md is the user-facing record