| name | skill-improvement-suggestor |
| description | Retrospective analysis of skill effectiveness after completing a task. Use when user requests skill improvement analysis (e.g., "做skill改善分析", "skill improvement analysis", "analyze skill gaps"). Analyzes the conversation to identify where goals were missed or required excessive iteration, then produces generalized, actionable improvement proposals saved to a structured report. |
Skill Improvement Suggestor
Analyze the current conversation to identify skill gaps, inefficiencies, and improvement opportunities. Produce a structured report with actionable proposals.
When to Use
User explicitly requests skill improvement analysis. Typical triggers:
- "做skill改善分析" / "skill improvement analysis"
- "分析一下skill的问题" / "analyze skill gaps"
- "我们来回顾一下" / "let's do a retrospective"
Workflow
Step 1: Gather context
Step 2: Analyze conversation
Step 3: Survey existing skills
Step 4: Draft proposals
Step 5: Write report
Step 1: Gather Context
Collect:
- Scenario: What was the user trying to accomplish? (1-2 sentence summary)
- Available skills: List all skills in
skills/skills/ (read directory)
- Used skills: Which skills were actually consulted or triggered during the conversation?
- Tools/env: What external tools, MCPs, or CLI utilities were involved?
Step 2: Analyze Conversation
2a. Reconstruct timeline. Walk through the conversation chronologically. For each task/sub-task, record:
- What was attempted
- Whether it succeeded, and how many iterations it took
- Whether the user intervened to correct direction
2b. Classify outcomes. For each task, assign one outcome:
| Outcome | Definition |
|---|
| ✅ Smooth | Goal achieved in ≤2 iterations, no user correction needed |
| ⚠️ Struggled | Goal achieved, but required 3+ iterations or user correction |
| ❌ Missed | Goal not achieved, or user had to do it themselves |
Focus analysis on ⚠️ and ❌ items only — smooth tasks don't need improvement.
2c. Identify root causes. For each ⚠️/❌ item, determine why using these signals:
| Signal | Indicates |
|---|
| Multiple retry loops on same error | Missing knowledge base or inadequate error-handling guidance |
| Agent searched blindly without consulting existing skill | Cross-referencing gap — skill exists but wasn't discovered |
| User had to correct agent's approach | Workflow guidance insufficient or missing |
| Agent produced output user rejected | Quality criteria or constraints not captured in skill |
| Excessive back-and-forth on scope/format | Ambiguous skill instructions, missing templates |
| Manual steps that could be automated | Opportunity for scripts or MCP integration |
2d. Record each finding:
- What happened (factual, 1-2 sentences)
- Outcome: ⚠️ Struggled / ❌ Missed
- Iterations: how many attempts before resolution (or "unresolved")
- Impact (wasted tokens / time / wrong output)
- Category:
missing-skill | skill-gap | cross-ref-gap | automation-opportunity | quality-criteria
Step 3: Survey Existing Skills
Before drafting any proposal:
- List all skills in
skills/skills/ — read each SKILL.md's frontmatter description to understand scope
- For each finding from Step 2, identify which existing skills are potentially relevant (even if they weren't used during the conversation)
- Read the full SKILL.md of each potentially relevant skill to determine:
- Does it already address this problem? → Finding is a cross-ref gap, not a skill gap
- Does it partially address it? → Proposal should modify existing skill, not create new one
- No coverage at all? → New skill may be justified
- Check
skill-creator/SKILL.md for design principles that new/modified skills must follow
- Record which skills were checked and the conclusion for each — this goes into the proposal's
Overlaps checked field
Step 4: Draft Proposals
For each issue from Step 2, draft an improvement proposal following these principles:
P1: Generalize
- Abstract from the specific case to the class of problems it represents
- Ask: "What other scenarios would this same fix help with?"
- Never assume future environments/requirements match the current case exactly
P2: No Redundancy
- If an existing skill already covers >70% of the proposal → modify that skill, don't create a new one
- If two proposals overlap → merge them
P3: Consider Tooling
- Can the improvement be supported by MCP servers, CLI tools, or scripts?
- Prefer tool-assisted solutions over pure-text guidance when the task is repetitive or error-prone
P4: Architectural Extensibility
- New skills should have clear scope boundaries and extension points
- Use directory structures that accommodate growth (e.g.,
issues/, reference/, templates/)
- Separate stable guidelines from volatile case-specific knowledge
P5: Context Economy
- Every token in a skill competes with conversation context
- Proposals should specify: what to add, what to remove, estimated token delta
- Prefer
reference/ files (loaded on demand) over inline content for detailed knowledge
Step 5: Write Report
Save to: skill_improve_<YYYYMMDD>_<scenario_slug>.md in the workspace root.
scenario_slug rules: lowercase, underscores, ≤30 chars, describes the task domain (e.g., async_fifo_design, pdf_report_gen, frontend_dashboard).
Use this exact structure:
# Skill Improvement Report — <Scenario Name>
Date: <YYYY-MM-DD>
Scenario: <1-2 sentence description>
## Context
### Work Scenario
<What the user was trying to accomplish, what tools/environment were involved>
### Skill Inventory
| Skill | Used? | Relevance |
|-------|-------|-----------|
| <name> | ✅/❌ | <brief note on role or why unused> |
...
## Findings
### F1: <Short title>
- **What happened**: ...
- **Outcome**: ⚠️ Struggled / ❌ Missed
- **Iterations**: <N> (or "unresolved")
- **Impact**: ...
- **Category**: `<category>`
### F2: ...
(repeat for each finding)
## Proposals
### Proposal 1: <Action> — <Target Skill>
- **Type**: New Skill / Modify Existing / New Script / New MCP
- **Target**: `skills/skills/<name>/`
- **Addresses findings**: F1, F2, ... (link back to findings)
- **Problem class**: <What general category of problems this addresses>
- **Change summary**: <What to add/modify/remove, concisely>
- **Specific changes**:
- File: `<path>` — Section: `<section>` — Action: add/modify/remove — Content sketch: `<brief>`
- (repeat for each file/section affected)
- **Architecture notes**: <Extension points, growth path> (required for new skills)
- **Estimated context cost**: <+N / -N tokens in SKILL.md>
- **Overlaps checked**: <Which existing skills were verified, and conclusion for each>
### Proposal 2: ...
(repeat for each proposal)
## Priority
| # | Proposal | Impact | Effort | Priority |
|---|----------|--------|--------|----------|
| 1 | ... | High/Med/Low | High/Med/Low | P0/P1/P2 |
...
Quality Checklist
Before finalizing the report, verify:
