Guide · Agent skill
How to use the Skill Improver agent skill (skill-improver)
Updated · written with AI from the project's own documentation and checked against our catalogue data
Skill Improver is an agent skill that reviews existing SKILL.md instruction files and checks them against an LLM-first style guide. It reports problems such as missing metadata, unclear triggers and tangled branching logic, and can apply fixes only when you explicitly ask. This guide explains what it does, how to install it, how to trigger it and how to use its output safely.
Skill ImproverGentleman-Programming/gentle-ai · MIT Download the skill Quick start
- 1Download the ZIP. Download the skill-improver ZIP from this page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one repository.
- 3Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 4Make sure skill files are present. Confirm the agent can read the SKILL.md files you want reviewed in your workspace.
- 5Ask for an audit. Use a plain request such as 'audit the skills in .claude/skills'. You get a report with no edits by default.
- 6Review the report. Read the issues grouped by severity and the exact proposed changes, and note any ambiguities.
- 7Apply only if you ask. If you are satisfied, explicitly ask the agent to apply improvements, then check the changed files.
What is an agent skill and what does Skill Improver do?
An agent skill is a folder built around a SKILL.md file that teaches an AI agent how to handle a specific capability. The file contains metadata, the situations that should load it, rules, decision logic and the output format the agent should return.
Once installed, Skill Improver lets the agent audit other SKILL.md files. It checks metadata, trigger clarity, section order, body budget, actionability, decision gates, output contract and local references against a style guide. The skill's own description lists the triggers as: improve skills, audit skills, refactor skills, skill quality.
- Checks frontmatter: name, quoted one-line description, license and metadata.
- Flags triggers that are vague or missing.
- Looks for branching logic hidden in prose that should be a decision table.
- Finds rules that conflict or are unclear and marks them for human review.
- Returns an audit report grouped by skill, with severity and exact proposed changes.
Install the skill-improver skill from the ZIP
Download the ZIP for skill-improver from this page. Unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only inside one repository.
Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills. The source material does not describe other install methods, so use these two.
- Personal (all projects): ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Check the requirements before you start
Skill Improver needs an agent runtime that loads SKILL.md skills and access to the skill files in your workspace. Without existing skill files to read, there is nothing for it to act on.
Two files are optional. If your repository has docs/skill-style-guide.md, the skill treats it as the normative style contract. If not, it falls back to its bundled references/skill-style-guide.md. If you keep an index at .atl/skill-registry.md, the skill uses it to find skill names, triggers and paths.
- Required: an agent runtime that loads SKILL.md skills
- Required: access to the skill files in the workspace
- Optional: docs/skill-style-guide.md, or the bundled references/skill-style-guide.md as fallback
- Optional: .atl/skill-registry.md as an index
- Optional: the gentle-ai skill-registry refresh command, used to update the registry
How to trigger Skill Improver with natural requests
You do not need a special command. Ask in plain language using the trigger phrases the skill is listed under. Name the skill or folder you want reviewed so the agent knows which files to read.
Ask for an audit first. The default behaviour is audit-only, so a request to review files produces a report and changes nothing. Only ask for changes when you are ready for them to be made.
- "Audit the skills in .claude/skills and tell me what needs fixing."
- "Improve the skill at ~/.claude/skills/my-review-skill, audit only."
- "Refactor the SKILL.md for my deploy skill to match the style guide."
- "Check skill quality across the skills in this repo."
Read the audit report and apply changes safely
The audit report groups issues by severity and lists exact proposed changes for each skill. Read it before anything is edited. The skill is designed to keep existing content: long explanations, examples and templates are moved into local references/ or assets/ folders rather than deleted.
When you ask for applied changes, the skill edits only issues it considers safe, creates supporting files when needed, and then recommends rerunning the audit or running gentle-ai skill-registry refresh if metadata or paths changed. Anything with conflicting rules or unclear intent is reported, not rewritten.
- Review severity groups and proposed changes first.
- Ask for apply mode only on skills you have reviewed.
- Check the 'Files changed' section of the output.
- Read the 'Ambiguities that need human review' list and decide those yourself.
- Use version control, if you have it, so you can compare before and after.
Safety notes: scripts and network
According to the skill's listing, Skill Improver does not run scripts and does not use the network. Its work consists of reading and, when asked, editing Markdown skill files in your workspace.
Its rules still do not guarantee the output is right. The listing warns that rewrites can alter author intent even though the rules try to prevent it, so keep a human in the loop for important skills.
- Runs scripts: no
- Uses network: no
- Hard rule: treat SKILL.md as the source of truth and preserve author intent
- Hard rule: do not invent triggers, policies or domain rules
What people use it for
- Standardizing the frontmatter and section order across a personal library of custom skills.
- Cleaning up a shared skills folder in a repository before the team publishes it.
- Finding out why a skill does not trigger reliably by checking its description and activation contract.
- Converting a skill written like a tutorial into runtime instructions with background moved to references/.
Frequently asked questions
How do I install the skill-improver agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
Is skill-improver free to use?
The listing states the licence is MIT. It does not describe pricing, so check the repository's licence file for the terms that apply to you.
What are the requirements for skill-improver?
You need an agent runtime that loads SKILL.md skills and access to the skill files in your workspace. A docs/skill-style-guide.md file and a .atl/skill-registry.md index are optional.
Does skill-improver change my files automatically?
No. It defaults to audit-only and modifies files only when you explicitly ask it to apply improvements. Even then it aims to keep existing content rather than delete it.
Should I use skill-improver or skill-creator?
Use skill-improver to audit and upgrade existing SKILL.md files. Use skill-creator when you want to create a brand-new skill from a reusable pattern, since the skill itself directs you there.
Why does my agent skill not trigger reliably?
Skill Improver can review your skill's metadata, description and activation contract and report unclear or missing triggers. Ask it to audit that skill and read the trigger-clarity findings.
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
Skill Improver suits developers and teams who maintain several custom SKILL.md files and want consistent structure, or who want a second opinion on a skill that does not trigger. It is not the right tool for writing a new skill from scratch, for people with no skill files, or for auto-applying rewrites to important skills without reviewing the audit first.
Download the skill