skill-improver
Improve skills and workflows by analyzing run artifacts and execution logs (events.jsonl/state.json) under runs/ (or OpenSpec changes/). Use when you want to iterate on skills based on real runs: find failure modes, bottlenecks, unclear prompts, missing I/O contracts, and propose concrete edits.
Best use case
skill-improver is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Improve skills and workflows by analyzing run artifacts and execution logs (events.jsonl/state.json) under runs/ (or OpenSpec changes/). Use when you want to iterate on skills based on real runs: find failure modes, bottlenecks, unclear prompts, missing I/O contracts, and propose concrete edits.
Teams using skill-improver should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/skill-improver/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How skill-improver Compares
| Feature / Agent | skill-improver | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Improve skills and workflows by analyzing run artifacts and execution logs (events.jsonl/state.json) under runs/ (or OpenSpec changes/). Use when you want to iterate on skills based on real runs: find failure modes, bottlenecks, unclear prompts, missing I/O contracts, and propose concrete edits.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Skill Improver Retrospect and improve Skills/Workflows based on real execution artifacts, making the skill chain more stable with use. ## Input (pass path only) - `run_dir`: `runs/<workflow>/active/<run_id>/` (or `openspec/changes/<change-id>/`) ## Output - `improvements.md`: Improvement suggestions (can be directly converted to change tasks) - Optional: Minimal patch to relevant `SKILL.md` (only change what's necessary) ## Process 1. Read `logs/state.json` and `logs/events.jsonl`, extract: - Failure points (error types, frequency, missing context) - Time bottlenecks (repetitive steps, ineffective searches, excessive context) - Manual confirmation points (whether too early/too late/missing) 2. Check artifact contracts: - Whether each step has persisted output - Whether only paths are passed instead of content - Whether there are inconsistent naming/paths 3. Output improvement suggestions (sorted by benefit): - Prompt/trigger word optimization - I/O contract completion (add required fields, fix artifact file names) - Error handling and rejection strategies - Suggest new deterministic scripts (only when necessary) ## Output Template (recommended) - Overview: Core issues from this run - Top Issues (high → low): Each includes "symptom/root cause/fix suggestion/related skill/suggested change point" - Suggested Minimal Change List: Listed by file