Skill Improvement Plan
Take feedback from skill-deep-review, skill-audit, or manual observations and produce a structured, prioritized plan of specific changes to make.
When to Use
- After a deep review report identifies issues in a skill
- After an audit report surfaces ecosystem-wide problems
- When you have scattered feedback notes and need to organize them into an actionable plan
- When deciding what order to fix things in
Inputs
- Review source — one or more of:
- A deep-review report (markdown from skill-deep-review)
- An audit report (markdown from skill-audit)
- Manual feedback (user-provided notes, conversation context)
- Constraints (optional) — time budget, which skills are off-limits, what to prioritize
Process
Step 1: Parse the Feedback
Read all review/audit reports provided. Extract:
- Every issue with its severity, affected skill, and dimension
- Every recommendation
- Trigger testing results (if from deep-review)
- Coverage gaps (if from audit)
Step 2: Deduplicate and Categorize
Group issues by type:
| Category |
Examples |
| Frontmatter fixes |
Missing fields, wrong types, bad version |
| Description rewrites |
Vague triggers, missing keywords, too long/short |
| Content restructuring |
Body too long, needs reference extraction, missing sections |
| Instruction improvements |
Ambiguous steps, missing rationale, wrong voice |
| Ownership fixes |
Overlaps, missing declarations, stale composes_with |
| New content |
Missing reference files, missing examples, missing checklists |
| Deletions |
Duplicate content, orphan files, dead links |
Merge duplicates — if the audit and a deep review both flag the same issue, combine them.
Step 3: Prioritize
Score each change on two axes:
- Impact (1–3): How much does fixing this improve the skill ecosystem?
- 3 = Skill doesn't trigger or produces wrong output without this fix
- 2 = Skill works but quality or consistency suffers
- 1 = Polish, nice-to-have
- Effort (1–3): How hard is the change?
- 1 = Quick edit (fix a field, add a line)
- 2 = Moderate rewrite (restructure a section, write a new reference file)
- 3 = Major rework (rewrite a skill from scratch, resolve complex ownership conflicts)
Sort by: Impact DESC, then Effort ASC (high-impact easy wins first).
Step 4: Generate the Plan
Produce a structured markdown plan:
# Skill Improvement Plan
Generated: [timestamp]
Source: [which reports/feedback were consumed]
Total changes: [count]
## Priority Matrix
| Priority | Impact | Effort | Changes |
|----------|--------|--------|---------|
| P0 (do first) | 3 | 1 | X |
| P1 (do next) | 3 | 2–3, or 2 | 1 | X |
| P2 (do later) | 2 | 2–3, or 1 | 1 | X |
| P3 (backlog) | 1 | any | X |
## Changes
### P0: [Title]
- **Skill:** [name]
- **File:** [path]
- **Category:** [from step 2]
- **What:** [specific change to make]
- **Why:** [from the review — what issue this fixes]
- **How:** [brief description of the edit — enough for skill-updater to execute]
### P0: [Title]
...
### P1: [Title]
...
## Execution Notes
- [Any ordering dependencies between changes]
- [Skills that should be reviewed again after changes]
- [Changes that might affect other skills]
## Post-Implementation
- [ ] Run skill-audit on affected skills to verify fixes
- [ ] Run skill-deep-review on any skill with P0 changes
- [ ] Sync repo → global locations
Step 5: Present and Confirm
Show the plan to the user. Ask:
"Here's the improvement plan with [X] changes across [Y] skills. The P0 items are [brief summary]. Want me to proceed with skill-updater to implement these, or would you like to adjust priorities first?"
Guidelines
- Be specific in the "How" field — vague instructions like "improve the description" aren't helpful. Say exactly what to change: "Rewrite description to: '[new description text]'"
- For description rewrites, draft the new description text in the plan so the updater can apply it directly
- Don't generate a plan for issues that are actually just style preferences — focus on functional improvements
- If a change would affect multiple skills (e.g., fixing an ownership overlap), note the dependency explicitly
- Keep the plan actionable — every item should be something skill-updater can execute without further research
Output
The plan is designed to feed directly into skill-updater, which reads the plan and executes the changes. The user can also use it as a manual TODO list.
1---2name: skill-improvement-plan3version: 1.1.04description: |5 Consume review reports from skill-deep-review or skill-audit and produce a prioritized, actionable improvement plan with specific edits per skill. Use this skill when you have review feedback to act on, need to plan skill improvements, want to turn audit results into a fix plan, or when someone says "plan the fixes", "what should we improve", "make a plan from this review", "improvement plan", or "prioritize the changes". Also trigger when a deep-review or audit report exists and the user wants next steps.6requires_agent_teams: false7requires_claude_code: true8min_plan: starter9owns:10 directories: []11 patterns: []12 shared_read: ["skills/"]13allowed_tools: ["Read", "Grep", "Glob", "Write"]14composes_with: ["skill-deep-review", "skill-audit", "skill-updater"]15spawned_by: []16metadata:17 source: https://skillmd.com/skills/ivy00johns/skill-improvement-plan18---1920# Skill Improvement Plan2122Take feedback from skill-deep-review, skill-audit, or manual observations and produce a structured, prioritized plan of specific changes to make.2324## When to Use2526- After a deep review report identifies issues in a skill27- After an audit report surfaces ecosystem-wide problems28- When you have scattered feedback notes and need to organize them into an actionable plan29- When deciding what order to fix things in3031## Inputs3233- **Review source** — one or more of:34 - A deep-review report (markdown from skill-deep-review)35 - An audit report (markdown from skill-audit)36 - Manual feedback (user-provided notes, conversation context)37- **Constraints (optional)** — time budget, which skills are off-limits, what to prioritize3839## Process4041### Step 1: Parse the Feedback4243Read all review/audit reports provided. Extract:4445- Every issue with its severity, affected skill, and dimension46- Every recommendation47- Trigger testing results (if from deep-review)48- Coverage gaps (if from audit)4950### Step 2: Deduplicate and Categorize5152Group issues by type:5354| Category | Examples |55|----------|----------|56| **Frontmatter fixes** | Missing fields, wrong types, bad version |57| **Description rewrites** | Vague triggers, missing keywords, too long/short |58| **Content restructuring** | Body too long, needs reference extraction, missing sections |59| **Instruction improvements** | Ambiguous steps, missing rationale, wrong voice |60| **Ownership fixes** | Overlaps, missing declarations, stale composes_with |61| **New content** | Missing reference files, missing examples, missing checklists |62| **Deletions** | Duplicate content, orphan files, dead links |6364Merge duplicates — if the audit and a deep review both flag the same issue, combine them.6566### Step 3: Prioritize6768Score each change on two axes:6970- **Impact** (1–3): How much does fixing this improve the skill ecosystem?71 - 3 = Skill doesn't trigger or produces wrong output without this fix72 - 2 = Skill works but quality or consistency suffers73 - 1 = Polish, nice-to-have74- **Effort** (1–3): How hard is the change?75 - 1 = Quick edit (fix a field, add a line)76 - 2 = Moderate rewrite (restructure a section, write a new reference file)77 - 3 = Major rework (rewrite a skill from scratch, resolve complex ownership conflicts)7879Sort by: Impact DESC, then Effort ASC (high-impact easy wins first).8081### Step 4: Generate the Plan8283Produce a structured markdown plan:8485```markdown86# Skill Improvement Plan87Generated: [timestamp]88Source: [which reports/feedback were consumed]89Total changes: [count]9091## Priority Matrix9293| Priority | Impact | Effort | Changes |94|----------|--------|--------|---------|95| P0 (do first) | 3 | 1 | X |96| P1 (do next) | 3 | 2–3, or 2 | 1 | X |97| P2 (do later) | 2 | 2–3, or 1 | 1 | X |98| P3 (backlog) | 1 | any | X |99100## Changes101102### P0: [Title]103- **Skill:** [name]104- **File:** [path]105- **Category:** [from step 2]106- **What:** [specific change to make]107- **Why:** [from the review — what issue this fixes]108- **How:** [brief description of the edit — enough for skill-updater to execute]109110### P0: [Title]111...112113### P1: [Title]114...115116## Execution Notes117- [Any ordering dependencies between changes]118- [Skills that should be reviewed again after changes]119- [Changes that might affect other skills]120121## Post-Implementation122- [ ] Run skill-audit on affected skills to verify fixes123- [ ] Run skill-deep-review on any skill with P0 changes124- [ ] Sync repo → global locations125```126127### Step 5: Present and Confirm128129Show the plan to the user. Ask:130131> "Here's the improvement plan with [X] changes across [Y] skills. The P0 items are [brief summary]. Want me to proceed with skill-updater to implement these, or would you like to adjust priorities first?"132133## Guidelines134135- Be specific in the "How" field — vague instructions like "improve the description" aren't helpful. Say exactly what to change: "Rewrite description to: '[new description text]'"136- For description rewrites, draft the new description text in the plan so the updater can apply it directly137- Don't generate a plan for issues that are actually just style preferences — focus on functional improvements138- If a change would affect multiple skills (e.g., fixing an ownership overlap), note the dependency explicitly139- Keep the plan actionable — every item should be something skill-updater can execute without further research140141## Output142143The plan is designed to feed directly into **skill-updater**, which reads the plan and executes the changes. The user can also use it as a manual TODO list.