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 improvementsself-improve [skill-name]- Target a specific skillself-improve on- Enable automatic mode (hook)self-improve off- Disable automatic modeself-improve status- Show automatic mode statusself-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