SuperAPI AI Directory

skill-improvement-plan

General & other

View repository

Updated 11-05 17:17

About this skill

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.