Tune Skill — Development skill for Claude Code

tune-skill

An agent skill that audits and fine-tunes a skill that **already exists**. Give it a `SKILL.md` and its siblings, and it checks the description that does the triggering, finds where two skills claim the same request, catches stale names and counts, fixes handoff contracts and command routing, makes the smallest evidenced edits, and validates them with a script rather than by eye.

It is explicitly not a rewrite. Every finding has to carry the quoted line, a severity, and the smallest fix — and the skill is required to say which checks ran, which test cases were only written, and which files it never got to see.

Install

npx skills add arm-pz/tune-skill --skill tune-skill

Or copy the `tune-skill/` folder into `~/.qoder/skills/` (Qoder) or `~/.claude/skills/` (Claude Code), then start a new session.

The validator is plain Python 3 and needs PyYAML:

pip install pyyaml
python scripts/check_skill.py /path/to/any-skill-folder

You can use `check_skill.py` on its own, without the skill, as a structural linter for any `SKILL.md`.

Ask it things like

• "This skill fires on the wrong requests — what's wrong with its description?"
• "I have two skills that both claim SEO audits. Split them cleanly."
• "Review this SKILL.md I just pasted and fix it minimally."
• "Make sure this skill hands off to its sibling instead of duplicating it."

What the validator checks

Check	Level
name is lowercase-hyphen and 64 characters or fewer	FAIL
Description within 1024 characters	FAIL
Description has trigger wording and a boundary clause	WARN
Folder name, frontmatter name and H1 agree	WARN
Every backticked references/, scripts/, examples/, assets/ path exists	WARN
Body under about 500 lines	WARN
A stated count ("three steps") matches what follows	WARN

Exit code 1 on any FAIL. Description is reported in characters and the body in lines, so a run is reproducible.

Layout

``