Self-Improve Skill Skill

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:

| Signal Type | Examples | |-------------|----------| | Correction | "No", "That's not right", "It's missing X", "Always do Y", user rewrites output | | Success | "Perfect", "Yes", "Exactly", user accepts without changes | | Edge case | User needed a workaround, skill couldn't handle the request |

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.

| Grade | Example | |-------|---------| | Pass | "Structure output as: Key Terms / Risk Areas / Suggested Revisions" | | Fail | "Use the standard format" (which format?) | | Fail | "Follow our firm's guidelines" (what guidelines?) |

2. PRECISE

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

| Grade | Example | |-------|---------| | Pass | "Flag non-compete clauses over 12 months as high risk" | | Fail | "Be more thorough in the analysis" | | Fail | "Make it more appropriate for clients" |

3. ATOMIC

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

| Grade | Example | |-------|---------| | Pass | "Check for governing law clause" | | Fail | "Check for governing law, jurisdiction, and arbitration clauses" (three checks - split them) |

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.

| Grade | Example | |-------|---------| | Pass | "Review the termination provisions under our internal policy [policy name and reference], dated December 12, 2024." | | Fail | "Follow latest market standards" (which standards? will change over time) |

Step 4: Grade the Signal

| Criteria Met | Action | |--------------|--------| | All 4 criteria pass | Add to skill directly | | Less than 4 criteria | Ask for clarification (see Step 5) |

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

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
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

Run:
```
rm -f ./.disabled
```
Reply: "Automatic mode enabled."

self-improve off

Run:
```
touch ./.disabled
```
Reply: "Automatic mode disabled."

self-improve status

Check .disabled file existence and report.

self-improve [skill-name] history

Display CHANGELOG.md content
Ask: "Would you like to revert to a previous version?"
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

Agent Skills: Self-Improve Skill

Install this agent skill to your local

Skill Files