Guide · Agent skill
How to use the Skill Improve Loop agent skill (skill-improve)
Updated · written with AI from the project's own documentation and checked against our catalogue data
Skill Improve is an agent skill from the Donchitos/Claude-Code-Game-Studios repository, released under the MIT licence. It makes Claude Code act as a reviewer for another agent skill: you give it a skill name, it scores the skill's SKILL.md file, proposes targeted edits, and keeps a change only if the number of failed checks goes down. This guide explains what it does, how to install it, how to trigger it, and what it needs before you rely on it.
Skill Improve LoopDonchitos/Claude-Code-Game-Studios · MIT Download the skill Quick start
- 1Install the skill. Download the ZIP from the directory page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it in the Claude apps under Settings → Capabilities → Skills.
- 2Confirm the framework is present. Check that your repository has the /skill-test command, studio-tests/ with catalog.yaml, hooks/yaml-helper.sh, and .claude/docs/automation-modes.md.
- 3Pick a skill to improve. Choose the folder name of a skill that has a SKILL.md at .claude/skills/[name]/SKILL.md.
- 4Run the loop. Invoke /skill-improve with that name. Read the baseline and the list of failing checks it reports.
- 5Review the proposed changes. Read each before/after block carefully. Answer yes only to changes you understand.
- 6Check the retest result. Compare the before and after counts. Keep the change if the verdict says it improved, or accept the restore offer if it did not.
- 7Test the skill on real requests. Because the score only reads the file, run the improved skill on a real request and compare its behaviour with the earlier version.
What an agent skill is and what skill-improve does
An agent skill is a folder containing a SKILL.md file. The file has a short header (frontmatter) with fields such as name and description, followed by instructions that Claude Code follows when the skill is invoked.
skill-improve works on one existing skill at a time. It runs the studio's static checks and, if the skill has a category, its category checks, then lists what fails. It proposes edits to the skill's instruction file, rewrites the file after you approve, reruns the checks, and compares the before and after counts.
- Reads the skill's SKILL.md and any references/ files it has
- Reports failing and warning checks, for example missing ask-before-write language or a missing handoff section
- Asks before writing any change to the skill
- Keeps the change only if the combined failure count drops; otherwise offers to restore the previous text
What it measures, and what it does not
The score comes from reading the skill file, not from running it. A better score means a better-written skill. It does not prove the skill behaves better in practice. The skill itself says to test real requests before and after a change to check behaviour.
Plan for that gap: use skill-improve to tidy the file, then try the skill on a real task yourself.
Install skill-improve
Download the ZIP from the directory page and unzip it into one of two locations. For a personal install available across projects, use ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder.
In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into your project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload
Check the requirements before you run it
skill-improve depends on the CCGS test framework. It will not work on an ordinary project without these pieces. The source lists the following requirements.
If your repository has the CCGS Skill Testing Framework folder, the skill tells you to move any specs into studio-tests/, because only studio-tests/ is read.
- Claude Code, working in a repository with the Donchitos/Claude-Code-Game-Studios structure
- The /skill-test command and its studio-tests/ framework, including catalog.yaml and the category rubrics
- hooks/yaml-helper.sh and .claude/docs/automation-modes.md present in the repo
- No API keys or external accounts required
- Uses no network access; it does run scripts
Trigger the skill with a request
The skill takes one argument: the name of the skill folder to improve. Invoke it with the slash command and that name. If you omit the name, the skill prints its usage line and stops.
The skill then checks that .claude/skills/[name]/SKILL.md exists. If the file is missing, it stops with a 'not found' message.
- Give the skill folder name exactly, for example tech-debt
- If the skill has no category field in catalog.yaml, category checks are skipped and only static checks run
- If there are no failures or warnings at all, it reports that no improvements are needed and stops
Usage: /skill-improve [skill-name]
Example: /skill-improve tech-debtWalk through a typical run
A run goes through numbered phases. It records a baseline, diagnoses gaps, proposes a fix, asks permission, writes, retests, and then either keeps or offers to revert the change.
Before any file is written, you see a clear before-and-after block for each proposed change, and the skill asks whether it may write the improved version. Answer no and it stops with nothing changed.
- Baseline: counts of FAILs and WARNs from the static run, with the failing check names
- Diagnosis: each gap is tied to a named file
- Proposal: marked before/after blocks, changing only failing parts
- Retest: the score is measured by rerunning the checks, not estimated from the edit
- Verdict: keep if the combined count drops, otherwise offer to restore
Review the diffs and handle the restore step carefully
Edits are written to SKILL.md and to any references files the fix touches. The restore step relies on the agent keeping the prior text in the conversation. Because of that, the skill does not use git checkout to revert, since that would return the last committed version and discard uncommitted work.
Review each diff before you approve it, and keep your own copy of important skills under version control if you can.
- Do not run it unattended on important skills
- Read the proposed before/after blocks before answering yes
- If a restore is offered, confirm the file list it names
What people use it for
- Cleaning up frontmatter fields in a library of game-studio skills so they match the shared rubric
- Adding ask-before-write language to a skill that writes files without asking first
- Adding a handoff or next-step section to a skill that ends without guidance
- Checking a new SKILL.md you wrote against static checks before sharing it with a team
- Bringing several skills to a common standard, one name at a time, using the next-step commands in the skill
Frequently asked questions
Is skill-improve free to use?
The source is MIT licensed, so you can use it under that licence. The source does not mention prices or paid tiers, and it requires no API keys or external accounts.
What do I need to run skill-improve?
You need Claude Code working in a repository with the Donchitos/Claude-Code-Game-Studios structure. It also needs the /skill-test command, the studio-tests/ framework with catalog.yaml and category rubrics, and hooks/yaml-helper.sh plus .claude/docs/automation-modes.md present in the repo.
Where do I install skill-improve?
Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. In the Claude apps, upload it under Settings → Capabilities → Skills.
Does skill-improve test whether a skill works?
No. Its score comes from reading the SKILL.md file with static and category checks. A better score means a better-written skill, not proof of better behaviour, so you should run the skill on real requests yourself.
Why does it say my skill is not assessed or the framework was renamed?
A NOT ASSESSED result means the file could not be read or parsed, or a rubric section could not be found, so there is no score to improve. If you have a CCGS Skill Testing Framework folder, the skill reads only studio-tests/, and the source points to UPGRADING.md for moving specs.
How does skill-improve compare with editing a skill by hand?
Manual editing relies on your own judgement about what to change. skill-improve checks the file against a fixed set of rules, proposes edits for the failing items, and reruns the checks so you can see whether the failure count dropped. It only measures how well the file is written, so it does not replace testing behaviour.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use skill-improve if you maintain a Claude Code game-studio skill library or write SKILL.md files and want structured feedback against a shared rubric. Skip it if you are not using the CCGS test framework, if you want proof that a skill works in practice, or if you plan to run it unattended on important skills.
Download the skill