skill-improver skill
✓ OfficialRuns an autonomous review-and-fix loop to iteratively refine Claude Code skills until they pass a quality review.
- GitHub stars
- 8,136
- Files
- 1
- Last commit
- Nov 11, 2026
- License
- CC-BY-SA-4.0
- Allowed tools
- 6
What does the skill-improver skill do?
skill-improver runs an autonomous review-and-fix loop to iteratively refine Claude Code skills until they pass a quality review.
Summary generated from the skill's SKILL.md.
About the skill-improver skill
Developers looking to polish Claude Code skills can use this tool to run an autonomous review and fix loop. It automates the process of iteratively refining a skill by connecting a fixer subagent with the plugin-dev:skill-reviewer agent. The process continues until the skill passes a quality review with zero critical or major findings, ensuring that frontmatter, descriptions, and referenced files meet required standards.
An agent should load this skill when a developer needs to fix quality issues or improve a skill until it passes a formal review. It relies on the Workflow tool to execute an improve.js script and requires the plugin-dev plugin to be installed from the official marketplace. The system includes a mechanical scope guard to prevent out-of-scope changes and a findings ledger to track progress across multiple rounds. All changes are kept within the working tree and are never committed automatically.
What an agent can do with it
- 1Iterative skill refinementRun an automated loop to improve a Claude Code skill until it passes a quality review.
- 2Enforce strict development scopeEnsure that the automated fixing process does not modify files outside of the intended plugin directory.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the skill-improver skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the skill-improver skill in Plugin
/plugin marketplace add trailofbits/skills /plugin install code-improver@trailofbits
Install the skill-improver skill in Claude Code
~/.claude/skills/skill-improver/SKILL.md
$ npx degit trailofbits/skills/plugins/code-improver/skills/skill-improver ~/.claude/skills/skill-improverInstall the skill-improver skill in Claude Code (project)
.claude/skills/skill-improver/SKILL.md
$ npx degit trailofbits/skills/plugins/code-improver/skills/skill-improver .claude/skills/skill-improverInstall the skill-improver skill in Codex
~/.agents/skills/skill-improver/SKILL.md
$ npx degit trailofbits/skills/plugins/code-improver/skills/skill-improver ~/.agents/skills/skill-improverInstall the skill-improver skill in Gemini CLI
~/.gemini/skills/skill-improver/SKILL.md
$ npx degit trailofbits/skills/plugins/code-improver/skills/skill-improver ~/.gemini/skills/skill-improverInstall the skill-improver skill in Claude.ai
npx degit trailofbits/skills/plugins/code-improver/skills/skill-improver skill-improver && zip -r skill-improver.zip skill-improver # claude.ai → Customize → Skills → + → Create skill → Upload a skill → skill-improver.zip
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletrailofbits/skills/plugins/code-improver/skills/skill-improver is public and reachablegithub.com/trailofbits/skills/tree/HEAD/plugins/code-improve ↗Pass
- Open source license (OSI)CC-BY-SA-4.0 is not OSI-approvedspdx.org/licenses/CC-BY-SA-4.0.html ↗Finding
- Commit or release in the last yearLast commit 2026-11-11github.com/trailofbits/skills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/trailofbits/skills/blob/HEAD/plugins/code-improve ↗Pass
- Pre-approved tools are scopedBash lets the agent run any shell command without askinggithub.com/trailofbits/skills/blob/HEAD/plugins/code-improve ↗Finding
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 139 linesgithub.com/trailofbits/skills/blob/HEAD/plugins/code-improve ↗Pass
SKILL.md
View on GitHubSkill Improver
Improve a Claude Code skill by running /code-improver:improve — a dynamic workflow
that loops a reviewer and a fixer subagent until a review reports zero critical/major
findings, then strips its own residue. This entry point wires the loop to the
plugin-dev:skill-reviewer agent, so the plugin-dev plugin must be installed
(marketplace claude-plugins-official). The loop, its ledger, and its guards live in
the workflow; this skill resolves the target and relays the outcome.
Starting the loop
The user provided: $ARGUMENTS (if empty, take the target skill from the conversation).
1. Resolve the skill path
- If the input ends with
/SKILL.mdand the file exists, use its directory - If the input is a directory containing
SKILL.md, use that path - Otherwise
Glob(pattern="**/SKILL.md")and filter by skill name or path substring:- Multiple matches: ask the user to choose
- No matches: report the available skills
- Single match: proceed
2. Resolve the loop script
Resolve improve.js from this SKILL.md's installed location
to an absolute path and confirm the file exists. Its plugin directory is pluginRoot.
Use this exact plugin copy; if the file is missing, stop.
3. Invoke the workflow
Run it with the Workflow tool, {scriptPath: "<the path from step 2>", args: {...}}:
{
"target": "<resolved absolute path>",
"reviewer": {
"kind": "agent",
"name": "plugin-dev:skill-reviewer",
"notes": "The target is a Claude Code skill directory; review it as a skill (frontmatter, triggering description, progressive disclosure, referenced files)."
},
"pluginRoot": "<the plugin directory from step 2>",
"maxRounds": 5
}
maxRoundsonly if the user asked for a different cap (--max-rounds N).pluginRootis the resolved plugin directory from step 2, for the metrics collector.scope(repo-relative globs) only if the user restricted or widened what the loop may touch; by default the workflow scopes to the skill's plugin directory.decisiononly on continuation (below).
The workflow runs in the background and needs no babysitting: it reviews, fixes, re-reviews, checks scope after every fix round, and can only complete on a clean review. It never commits; all changes stay in the working tree.
If the Workflow tool is unavailable or denied, stop and say so. Do not improvise the loop inline with direct edits — the ledger, scope guard, and escalation guarantees live in the workflow, and an inline imitation has none of them (observed failure: an inline fallback "fixed" a finding by weakening the documented guarantee, exactly what the loop exists to prevent).
If the result is halted: "reviewer-unavailable", relay it and stop. The reviewer
this skill names is not installed; tell the user to install the plugin-dev plugin from
the claude-plugins-official marketplace and re-run. Do not review the skill yourself.
Do not end your turn while the loop is running. The Workflow tool returns a task id immediately; the result comes later. In an interactive session the completion notification re-invokes you — wait for it. In a non-interactive run (scripted, CI, eval) there is no later turn: stopping abandons the loop mid-round, so after launching, poll the task (TaskOutput with the returned task id, or sleep-and-recheck) until it completes, then relay the result. A session that answers "the loop is running, I'll report later" has lost the run.
Relaying the result
The workflow returns a structured result. Report it honestly — the distinctions matter:
converged: true— the last action was a review with zero critical/major findings. Report rounds used, remaining minor findings (open_minor_count), and the artifact paths (ledger_path,metrics).capped: true— the fix budget ran out and the FINAL review still found blocking issues. Say plainly: capped, NOT converged, and listopen_blocking. Do not present this as success.escalation— the loop detected it was not converging (recurring findings, non-decreasing counts, or a fix relocating a problem). Relay the escalation message and finding ids to the user: this needs a design decision, not more rounds.halted— a guard fired (scope violation, unregistered new files, a dead or unavailable reviewer, or a finalize pass whose own edits failed the check that follows it). Relay the paths inviolations/new_untracked_files, the sites infinalize_regressions, and the notes.notesalways travel with the result — surface them; they include loud warnings such as "a git repository was initialized".
Continuing after an escalation
The loop stops on escalation by design. When the user decides (e.g. "keep the blocklist
and document the limitation"), start a fresh run with the same target plus:
{ "decision": "<the user's ruling, verbatim>" }
The new run reloads the on-disk ledger, so every finding, rejection, and verdict carries over — rounds restart, re-derivation does not.
To stop a running loop, stop the workflow task (TaskStop); the ledger on disk is current to the last round and a re-run resumes from it.
What the loop enforces (so you do not have to)
- Fix verification — the next review verifies every fix; fixes to executable behavior carry pins that fail against the pre-fix code.
- Scope — a mechanical git-diff check after every fix round, and after the finalize pass, halts on any out-of-scope change; out-of-scope files git does not track are guarded by content hash, since no diff would show them; completion also requires no unregistered new files in scope.
- Report everything — reviewers report all findings with severity; filtering happens once, at the ledger verdict, and rejections are not re-litigated without new evidence.
- Finalize — before completion the loop strips narration comments, collapses version
churn to exactly one bump (in
plugin.jsonand the marketplace entry that repeats it), and runs a docs-match-code pass. Those edits land after the last review, so a check reads them: an over-eager narration strip or a false docs claim halts withfinalize-regressioninstead of passing as done.
When NOT to use
- One-time review: dispatch the
plugin-dev:skill-revieweragent directly - Quick single fixes: edit the file directly
- Non-skill targets: use the
code-improverskill with a reviewer that fits the target, orpr-improverfor a branch - Exploratory drafting: manual iteration gives more control while the shape is fluid
Files in this skill
1skill-improver skill questions
How do I install the skill-improver skill in Claude Code?
Run npx degit trailofbits/skills/plugins/code-improver/skills/skill-improver ~/.claude/skills/skill-improver. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the skill-improver skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is the purpose of the skill-improver loop?
It runs an autonomous review-and-fix improvement loop over a Claude Code skill until a review comes back clean, using a findings ledger and scope guards.
Can I use this for a one-time review?
No, for a one-time review you should use the plugin-dev skill-reviewer agent directly.
What happens if the loop stops converging?
The loop will trigger an escalation, which requires a design decision from the user rather than more rounds.