Skill Auto Improver

Skill Auto-Improver

You are running an eval-driven improvement loop for a SKILL.md-based skill. The target skill must clear two gates in this order:

1. Skill-creator standard (must-pass floor) — python scripts/quick_validate.py is clean; the Frontmatter Audit passes; SKILL.md is under 500 lines; description has a negative-trigger clause; metadata.version and metadata.author are present; docs/README.md (if it exists) carries the AI-skip notice; bundled scripts print descriptive errors before exiting. 2. `asm eval` quality floor (supplementary) — overallScore > 85 AND every category score >= 8.

A skill that scores 92 on asm eval but fails quick_validate.py is not done. A skill that passes quick_validate.py but scores 70 on asm eval is not done. Both gates must clear, or the loop reports a blocker.

Repo Sync Before Edits (mandatory)

This skill mutates files in a git repo. Before any edit, sync the local branch with the remote:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is dirty, git stash, sync, then git stash pop. If origin is missing or git pull hits conflicts, stop and ask the user before continuing — do not skip or force the sync.

When to Use

• The user asks to "improve", "level up", "fix", "polish", or "bring up to standard" an existing skill
• A skill fails quick_validate.py or scores below the asm-eval 85/8 floor and must ship
• You are preparing a skill for asm publish or inclusion in a catalog
• You want to dogfood quality improvements on one of your own skills

If the user only wants a report without edits, run asm eval <path> and python scripts/quick_validate.py <path> directly — that is not this skill. If the user is authoring a brand-new skill from scratch, send them to /skill-creator instead — this skill assumes a SKILL.md already exists.

Prerequisites

Verify all of the following before touching any files. Stop and tell the user if any fails.

• asm is available on PATH (command -v asm or which asm)
• Python 3 is available, and ~/.claude/skills/skill-creator/scripts/quick_validate.py exists (skill-creator must be installed locally)
• The target skill path contains a SKILL.md file
• The working tree has no unrelated uncommitted edits (dirty files get mixed into diffs)
• You have write access to the skill directory

Resolve the path to skill-creator's validator once at the start and reuse it:

QV="$HOME/.claude/skills/skill-creator/scripts/quick_validate.py"
test -f "$QV" || { echo "skill-creator not installed at $QV"; exit 1; }

Inputs

The user provides one of:

• A local skill path: skills/foo or /abs/path/to/skill
• A direct SKILL.md file path (treated as its parent directory)
• A GitHub shorthand: github:owner/repo or github:owner/repo:path/to/skill

For GitHub inputs, ask the user to clone locally first or whether you should open a PR back to that repo. This skill's default path is local editing — remote editing is out of scope for v1.

The Two Gates

Gate 1 — Skill-creator standard (must-pass floor)

A skill passes this gate when all of these are true:

• python "$QV" "$SKILL_PATH" exits 0 (no unexpected keys, name is kebab-case ≤64 chars, description is single-line ≤1024 chars, etc.)
• The Frontmatter Audit (full checklist in references/frontmatter-audit.md) passes
• SKILL.md body is under 500 lines (split to references/ if not)
• Description includes a negative-trigger clause naming adjacent domains that should not trigger the skill (quick_validate.py warns when missing)
• metadata.version follows MAJOR.MINOR.PATCH; metadata.author is present
• If docs/README.md exists, it carries the AI-skip HTML comment at the top
• Any bundled scripts under scripts/ print descriptive errors on stderr before exiting

This gate is non-negotiable — asm publish and the catalog rely on it.

Gate 2 — asm-eval 85/8 quality floor (supplementary)

overallScore > 85   AND   min(categories[*].score) >= 8

Stricter than overall score alone — a skill at 86 with a 5 in testability still fails. This forces balanced quality instead of letting one strong area hide a weak one.

Workflow

Do these phases in order. Do not skip phases or change the order. Phase 4 is a continuous sidebar that runs throughout Phase 3 — not a standalone step, which is why it does not appear in the per-phase Step Completion Reports.

Phase 0 — Capture baseline against both gates

Save the starting state so the before/after diff is auditable:

mkdir -p .asm-improver
asm eval "$SKILL_PATH" --json > .asm-improver/baseline.json
python "$QV" "$SKILL_PATH" > .asm-improver/baseline-quickvalidate.txt 2>&1 || true

Then perform the Frontmatter Audit described in references/frontmatter-audit.md and save findings to .asm-improver/baseline-frontmatter-audit.md.

If the target skill lives inside a git repo, suggest adding .asm-improver/ to .gitignore so iteration artifacts stay out of version control.

Read the JSON and note:

• overallScore, grade
• Every categories[].score (7 categories, each out of 10)
• topSuggestions (the evaluator's own priorities)

If the baseline already passes both gates, stop immediately — print a one-line summary and skip to the final report. Do not "improve" a skill that already passes.

Phase 1 — Apply deterministic fixes, then normalize frontmatter

Run the evaluator's auto-fixer for free wins:

asm eval "$SKILL_PATH" --fix --dry-run   # preview the diff
asm eval "$SKILL_PATH" --fix              # write, creates SKILL.md.bak

This handles trailing whitespace, CRLF normalization, missing effort, and other mechanical issues. However, when authorship or version is missing, `asm eval --fix` writes a top-level `author:` (from `git config user.name`) and/or top-level `version: 0.1.0` — both of which `quick_validate.py` rejects as unexpected keys. Immediately follow with the normalization step below.

Frontmatter normalization (mandatory after --fix)

Read references/frontmatter-audit.md — section "Normalizing asm eval --fix output" — for the exact migration. In short:

• Move top-level author: <name> → metadata.author: <name> (keep the value). The current fixer writes author:; older skills may carry a top-level creator: instead — treat it the same way and migrate to metadata.author:.
• Move top-level version: <semver> → metadata.version: <semver> (keep the value)
• Drop any other top-level keys that aren't in the allowed set (name, description, license, allowed-tools, metadata, compatibility, effort) — e.g., legacy tags:. Surface non-trivial drops to the user before deleting.
• Quote any string value containing :, #, -, <, >, |, {, }, [, ], ,, &, *, ?, =, !, %, @, or ` `` per the YAML safety rule

After normalization, re-run both checks:

asm eval "$SKILL_PATH" --json > .asm-improver/iter-1.json
python "$QV" "$SKILL_PATH"

Many skills jump 5–15 points on asm eval here without touching the body, and quick_validate.py typically goes from fail to pass.

Phase 2 — Fix Gate 1 failures first

quick_validate.py and the Frontmatter Audit findings come first because they gate publish. Read references/skill-creator-checklist.md for the full retrofit playbook. Common fixes:

• Description missing a negative-trigger clause → append "Don't use for X, Y, Z." naming 2–3 adjacent domains
• Description over 250 chars → trim hedge words, collapse synonyms (1024 is the hard ceiling, 250 is the runtime-budget target)
• Body over 500 lines → split dense sections into references/<topic>.md and replace inline content with a one-line pointer
• Missing AI-skip notice in docs/README.md → prepend the HTML comment from references/skill-creator-checklist.md
• Bundled script exits silently → add echo "Error: ..." >&2 lines before each exit 1 / sys.exit(1)

Re-run python "$QV" "$SKILL_PATH" after every Gate 1 edit. Do not move to Phase 3 until Gate 1 is clean.

Phase 3 — Fix the lowest asm-eval categories

Sort the 7 categories by score ascending. Work on the lowest one first. Stop when all of them are >= 8.

For each category below 8:

1. Read references/category-playbook.md to find the fix patterns for that category 2. Apply them with Edit (small targeted changes) or Write (when restructuring a whole section) 3. Re-run asm eval "$SKILL_PATH" --json and python "$QV" "$SKILL_PATH" and check the deltas

Do not batch-edit multiple categories blindly. Fixes can interact — expanding the body for testability can tank context-efficiency or push the body over 500 lines (which fails Gate 1). One category at a time, re-eval after each change, keep the ones that help, revert the ones that regress either gate.

Phase 4 — Watch for cross-gate tradeoffs (sidebar — applies during Phase 3)

These principles apply continuously while doing Phase 3 category fixes, not as a separate sequential phase. Read them once before Phase 3 and keep them in mind on every edit.

The two gates pull in opposite directions on body length:

• asm eval's prompt-engineering rewards bodies up to 3000 words
• asm eval's context-efficiency rewards bodies under 1500 words
• Gate 1 caps SKILL.md at 500 lines (the hard skill-creator rule, ~ a few thousand words)

When you add content, default to linking out, not inlining:

• Long examples → references/examples.md with See references/examples.md for...
• Long scripts → scripts/foo.sh with Run scripts/foo.sh to...
• Long tables → references/rubric.md
• Long prerequisite lists → references/prerequisites.md

This pattern earns context-efficiency points (the words "reference" / "see" / "link" / "template" are scanned for), keeps SKILL.md under the 500-line Gate 1 cap, and reduces token cost on every invocation.

Concretely, if you would need more than ~80 lines to add a section, put it in references/ and link to it from SKILL.md in 2-3 lines.

Phase 5 — Bump the target skill's metadata.version

This phase runs as the last action inside each iteration of Phase 6's loop, not as a separate one-time pass after Phase 6. The number is sequential for narrative flow; the actual execution is per-iteration.

Per skill-creator's Version Management rule, every edit to a SKILL.md must bump metadata.version before saving:

• Patch (x.y.Z): typo fixes, frontmatter-only normalization, minor wording tweaks
• Minor (x.Y.0): new sections, new references, expanded triggers, added subagents
• Major (X.0.0): restructured workflow, breaking output-format changes

If the target SKILL.md has no metadata.version, add one starting at 1.0.0. Bump exactly once per loop iteration, not once per edit within an iteration — otherwise the version churns ahead of meaningful change.

Record the bump in the loop log so the final report can show baseline → final version.

Phase 6 — Loop with a cap

Re-run both checks after every iteration. The loop stops when any of these is true:

Mid-iteration Gate 1 regressions — a Phase 3 edit can push SKILL.md over the 500-line cap or otherwise break a Gate 1 check (the two gates pull in opposite directions on body length; see Phase 4). When this happens within an iteration, do not let it close the iteration as a regression: drop back into Phase 2, fix the Gate 1 break in the same iteration, then re-run both checks. Only count the iteration as a regression if both gates are still worse than the previous iteration after that fix lands. This prevents the loop from tripping the "2 consecutive regressions" stop condition on a churn that the agent could resolve in-place.

Save every iteration's JSON to .asm-improver/iter-N.json and a one-line gate summary to .asm-improver/iter-N-gates.txt so the final report can diff them.

Phase 7 — Write the final report

On pass, write .asm-improver/report.md with:

• Target skill path
• Baseline vs final for both gates: quick_validate.py status, Frontmatter Audit findings cleared, overallScore, grade, per-category before/after table
• Target skill's metadata.version: baseline → final
• Files changed (list every path under the skill directory that was edited or created)
• Iterations taken (N of 8)
• Key fixes applied (one line per category or audit item that moved)

On blocker, write the same report but add a "Blockers" section explaining why a gate was not cleared. Blocker entries must name the gate (Gate 1 or Gate 2), the specific failing check (e.g., quick_validate.py: unexpected key 'tags'), and what the loop was unable to resolve. Do not pretend a blocker is a pass.

Example blocker entry:

Gate 2 — testability (stuck at 6/10): The evaluator wants verifiable outputs and an "Acceptance Criteria" section. The skill's output is a subjective rewrite of prose, which is hard to express as a testable assertion. Author decision needed: accept a 6 here, or redefine scope so output is machine-checkable.

Step Completion Reports (mandatory)

After each phase, emit a compact status block so pass/fail is scannable:

◆ Phase N — [phase name]
··································································
  Frontmatter valid:   √ pass
  quick_validate:      √ pass
  asm overall:         86 → 91
  Min category:        7 → 8
  Target version:      1.2.0 → 1.3.0
  Result:              PASS | FAIL | PARTIAL

Use √ for pass, × for fail, — for context. Report per phase: Phase 0 (baseline captured), Phase 1 (deterministic + normalization), Phase 2 (Gate 1 fixes), Phase 3 (asm-eval category fixes), Phase 5 (version bump applied), Phase 6 (loop stop condition), Phase 7 (final report written).

Acceptance Criteria

• .asm-improver/baseline.json, .asm-improver/baseline-quickvalidate.txt, and .asm-improver/baseline-frontmatter-audit.md captured before any edits
• asm eval --fix applied, then frontmatter normalized so quick_validate.py accepts the result
• Each Gate 1 check addressed at least once before any Gate 2 work
• Each asm eval category below 8 addressed at least once
• Re-eval against both gates after every iteration, captured to .asm-improver/iter-N.json and .asm-improver/iter-N-gates.txt
• Target skill's metadata.version bumped exactly once per iteration that produced edits
• Loop stops on one of the 4 conditions in Phase 6 — never unbounded
• .asm-improver/report.md exists on exit, pass or blocker
• On PASS: python "$QV" "$SKILL_PATH" exits 0 AND final eval JSON shows overallScore > 85 AND min(categories[*].score) >= 8
• On BLOCKER: report names every Gate 1 check still failing and every category still below 8 with a one-line reason

Expected output

See references/report-template.md for the full PASS and BLOCKER report templates. On BLOCKER, include a ## Blockers section naming each failing gate check with a one-line reason.

Edge Cases

• Skill already passes both gates: stop at Phase 0, skip to report. Do not edit passing skills.
• SKILL.md has no frontmatter: asm eval --fix cannot add it. Ask the user whether to scaffold one (using the skill-creator template) or abort.
• Iterating regresses either gate: revert the last edit (cp SKILL.md.bak SKILL.md if available, or undo via git) and try a different fix pattern from the playbook.
• `asm eval --fix` writes a key `quick_validate.py` rejects: this is expected — Phase 1's normalization step handles it. Do not skip the normalization.
• Description over 250 chars after edits: trim. The 250-char target prevents tail-first truncation in Claude Code's /skills listing, which would chop your negative-trigger clause.
• SKILL.md body over 500 lines: split into references/ per the progressive-disclosure rule. SKILL.md must drop below 500 before exit.
• Loop caps out at 8 iterations: the skill has structural issues auto-improvement cannot solve. Write the blocker report and hand back to the user.
• GitHub shorthand input: for v1, ask the user to clone locally first. Remote editing is out of scope.
• Destructive action: never rm -rf the skill directory. asm eval --fix creates SKILL.md.bak — leave it in place until the user explicitly cleans up.

References

• references/skill-creator-checklist.md — Gate 1 retrofit playbook (frontmatter, README, scripts, body length)
• references/frontmatter-audit.md — full audit checklist plus the asm eval --fix normalization migration
• references/category-playbook.md — per-category fix patterns for asm eval Gate 2
• references/report-template.md — PASS and BLOCKER report layouts
• ~/.claude/skills/skill-creator/scripts/quick_validate.py — the Gate 1 mechanical validator
• ~/.claude/skills/skill-creator/references/frontmatter-rules.md — upstream source of the audit rules
• asm eval --help — flag reference for the evaluator
• src/evaluator.ts in the ASM repo — source of truth for how each Gate 2 category is scored

<!-- DO NOT READ THIS FILE — This README.md is for human catalog browsing only. It ships inside the .skill package but is NEVER auto-loaded into agent context. The runtime loader only reads SKILL.md + references/ + scripts/ + agents/ when the skill triggers. If you're an AI agent, read the SKILL.md file instead for skill instructions. -->

Skill Auto-Improver

Two-gate improvement loop for SKILL.md-based skills. Iterates until the target skill clears the skill-creator standard (mechanical validator + frontmatter audit + ≤500-line body + AI-skip README) AND the asm-eval 85/8 floor (overallScore > 85, every category ≥ 8) — or stops with a blocker report.

Highlights

• Two gates, both must pass. Gate 1 = skill-creator standard (publish-blocking). Gate 2 = asm-eval 85/8 quality floor.
• Deterministic fixes first (asm eval --fix), then frontmatter normalization to satisfy quick_validate.py, then content fixes by lowest category.
• One category at a time, re-eval against both gates after every edit.
• Hard loop cap (8 iterations) so it never runs unbounded.
• Bumps the target skill's metadata.version once per iteration per skill-creator's Version Management rule.
• Saves every iteration JSON and gate-summary line to .asm-improver/ for auditability.
• Writes a final before/after report on pass or blocker.

When to Use

Usage

/skill-auto-improver skills/my-skill

Or paste a skill path and the skill triggers automatically. GitHub shorthand inputs are accepted but v1 asks you to clone locally first — remote editing is out of scope.

How It Works

graph TD
    A["Phase 0: baseline both gates<br/>asm eval --json + quick_validate.py"] --> B{"Already passes<br/>both gates?"}
    B -- yes --> R["Write PASS report, exit"]
    B -- no --> C["Phase 1: asm eval --fix<br/>+ frontmatter normalize"]
    C --> D["Phase 2: clear Gate 1<br/>(skill-creator standard)"]
    D --> E["Phase 3: lowest asm-eval category"]
    E --> F["Apply fix from playbook"]
    F --> G["Phase 5: bump metadata.version"]
    G --> H["Re-run both gates"]
    H --> I{"Both cleared<br/>or cap hit?"}
    I -- no --> E
    I -- yes --> J["Phase 7: write report"]
    style A fill:#4CAF50,color:#fff
    style J fill:#2196F3,color:#fff

The Two Gates

Gate 1 — skill-creator standard (must-pass)

• quick_validate.py exits 0 with no warnings
• Frontmatter audit clean (allowed top-level keys only, metadata.version + metadata.author present, YAML safety, name matches directory)
• Description ≤250 chars (target) with a negative-trigger clause
• SKILL.md body under 500 lines
• docs/README.md (if present) carries the AI-skip notice
• Bundled scripts print descriptive errors before exiting

Gate 2 — asm-eval 85/8 quality floor

overallScore > 85   AND   min(categories[*].score) >= 8

Stricter than overall score alone — a skill at 86 with a 5 in testability still fails. Forces balanced quality across all 7 categories instead of letting one strong area hide a weak one.

Output

Stop Conditions

The loop stops on any of:

Resources

Category Playbook (Gate 2)

Per-category fix patterns for the asm-eval scoring used in Gate 2 of the skill-auto-improver workflow. Each section lists what the evaluator rewards, common failure modes, and concrete edits that move the score up.

For Gate 1 (the skill-creator standard — quick_validate.py, frontmatter audit, ≤500-line body, AI-skip README, etc.), see skill-creator-checklist.md. Always clear Gate 1 before working on Gate 2 — a Gate 1 failure blocks publish regardless of asm-eval score.

All scoring rules below mirror src/evaluator.ts in the ASM repo. Numbers change when the evaluator evolves — re-read that file if scores behave unexpectedly.

1. Structure & completeness (structure)

What it rewards (10 pts):

• YAML frontmatter block present (2 pts)
• name and description filled (3 pts)
• version (top-level or metadata.version) set and not default 0.0.0 (1 pt)
• author (or metadata.author; creator accepted as legacy alias) present (1 pt)
• license present (1 pt)
• Body has >=20 chars of content (1 pt)
• Body has at least one markdown heading (1 pt)

Fix patterns:

• Missing frontmatter fields: run asm eval --fix first — it adds version (0.1.0) and author (from git config user.name) automatically. Note that --fix writes them at the top level; Phase 1 normalization moves them under metadata:.
• Missing license: add license: MIT (or whatever the repo uses)
• Empty body: write at least a ## When to Use section
• No headings: add ## Instructions, ## Prerequisites, ## Example as appropriate

2. Description quality (description)

What it rewards (10 pts):

• Length between 8 and 40 words (4 pts)
• Starts with an action verb (see ACTION_VERBS in evaluator.ts) (3 pts)
• Contains a trigger phrase: "use when", "when", "for", "before", "after", "during", "trigger" (3 pts)

Fix patterns:

• Too short (<8 words): rewrite to name the action AND the trigger
• Too long (>40 words by asm-eval, but Gate 1 also caps at 250 chars target / 1024 hard): trim hedge words and collapse synonyms first; move detail to the body
• Doesn't start with a verb: rewrite so the first word is an imperative. Good first words: Analyze, Audit, Build, Check, Create, Debug, Deploy, Evaluate, Find, Fix, Generate, Improve, Index, Install, Migrate, Optimize, Plan, Publish, Refactor, Remove, Review, Run, Scan, Search, Summarize, Sync, Test, Update, Validate, Verify, Write
• No trigger phrase: append Use when... or ...for <situation> to the description
• No negative-trigger clause (Gate 1 finding via `quick_validate.py` warning): append Don't use for X, Y, Z. naming 2–3 adjacent domains. Example: a Tailwind skill should say "Don't use for Vue, Svelte, vanilla CSS, or plain HTML projects."

Example rewrite:

• Before: A minimal test skill that greets the user and demonstrates the ASM publish workflow.
• After: Generate a personalized greeting. Use when testing the ASM publish workflow or demoing skill scaffolding.

3. Prompt engineering (prompt-engineering)

What it rewards (10 pts):

• Progressive disclosure cues: "when to use", "quick start", "overview", "instructions", "steps", "workflow", "phases" (3 pts if >=2, 1 pt if 1)
• Uses lists or numbered steps (2 pts)
• Has code block AND mentions "example" (2 pts if both, 1 pt if one)
• Imperative voice cues: Do, Use, Run, Call, Check, Validate, Return, Emit, Write, Read, Ask, Confirm, Avoid, Never, Always — at least 3 occurrences (2 pts for >=3, 1 pt for 1-2)
• Body length between 80 and 3000 words (1 pt)

Fix patterns:

• Missing section structure: add ## When to Use and ## Instructions headings
• No lists: convert prose paragraphs to bulleted or numbered steps
• No examples: add ## Example section with a fenced code block (bash ... or similar)
• Passive voice: rewrite to imperative. "The user might want to run..." becomes "Run..."
• Body too short (<80 words): expand — underspecified skills give the agent too much freedom
• Body too long (>3000 words): split into references/*.md files and link

4. Context efficiency (context-efficiency)

What it rewards (10 pts):

• Body length between 120 and 1500 words (4 pts)
• References external files: "reference", "references", "see", "template", "templates", "script", "scripts", "helper", "helpers", "link" — at least 2 mentions (3 pts for >=2, 1 pt for 1)
• No code blocks longer than 60 lines (2 pts)
• Mentions "token", "budget", or "context window" (1 pt)

Fix patterns:

• Body too long: move large sections (>80 lines) into references/<topic>.md, replace with See references/<topic>.md for...
• No reference links: add phrases like See references/examples.md or Run scripts/foo.sh
• Code block >60 lines: save to scripts/<name>.sh or templates/<name>.md, link from SKILL.md
• Miss the token-bonus: add one sentence referencing "the agent's context budget" or similar

5. Safety & guardrails (safety)

What it rewards (10 pts):

• Safety keywords: "confirm", "error", "fail", "caution", "warning", "prerequisite", "requires", "rollback", "dry-run", "safety", "validate", "check", "backup" — at least 4 (4 pts), 2-3 (2 pts), 1 (1 pt)
• Destructive action paired with confirmation/dry-run/backup (3 pts if both mentioned, 1.5 pts if no destructive actions)
• Prerequisites section (3 pts for any of: "prerequisite", "require", "depend")

Fix patterns:

• Add ## Prerequisites listing tools, creds, env state
• Mention error-handling: "If X fails, do Y"
• Pair any destructive command with a confirmation or dry-run: "Run rm -rf X only after --dry-run confirms the path is correct"
• Add a "Validate" or "Check" step before committing

6. Testability (testability)

What it rewards (10 pts):

• Testability keywords: "acceptance criteria", "expected output", "expected result", "edge case", "test", "verify", "assert", "example input", "example output", "given", "then" — 4+ (5 pts), 2-3 (3 pts), 1 (1 pt)
• Describes expected output/result (3 pts for "expected output/result/response")
• Mentions edge cases, gotchas, pitfalls, limitations (2 pts)

Fix patterns:

• Add ## Acceptance Criteria with a checklist of verifiable outputs
• Include an Expected output: code block under the main example
• Add ## Edge Cases listing inputs the skill rejects or handles specially
• Use "verify" / "assert" / "check" in the instructions

Anti-pattern to avoid: do not pad the body with "acceptance criteria" filler just to hit the keyword. Write real, testable statements — "produces a JSON report with overallScore", "exits 0 on success", "creates .asm-improver/report.md".

7. Naming & conventions (naming)

What it rewards (10 pts):

• name is lowercase kebab-case, <=40 chars (4 pts)
• Body headings use action/imperative labels: ## When to Use, ## Instructions, ## Examples, ## Steps, ## Acceptance Criteria, etc. (3 pts if >=50% of headings match, 1 pt otherwise)
• Description has no TODO/FIXME/double-space/stray ?? (2 pts)
• Bonus: directory basename matches frontmatter name (+1 pt)

Fix patterns:

• Rename directory to match name (or vice versa)
• name: foo_bar → name: foo-bar (kebab-case)
• ## About this skill → ## When to Use
• ## Details → ## Instructions
• ## Notes → ## Edge Cases or ## Prerequisites
• Strip TODO/FIXME comments from the description field

Tradeoff awareness

Fixes in one category can regress another. The common collisions:

When in doubt, prefer *linking to `references/.md`** over inlining. The evaluator rewards references in two categories (context-efficiency, naming via action-oriented heading when the reference is named well) and doesn't penalize them anywhere.

Re-eval checklist

After every edit, check both gates:

1. Run python "$QV" "$SKILL_PATH" — Gate 1 mechanical check, must exit 0 with no warnings 2. Run asm eval "$SKILL_PATH" --json | jq '.overallScore, [.categories[].score] | add, [.categories[] | {id, score}]' (or read the full JSON) — Gate 2 scoring 3. Compare each category against the previous iteration 4. If anything regressed in either gate, revert that specific edit and try a different pattern from this playbook 5. If both Gate 1 is clean AND the 85/8 floor is cleared on Gate 2, stop — do not over-optimize

Frontmatter Audit

The full Gate 1 checklist for SKILL.md frontmatter, plus the migration that converts asm eval --fix output into a layout quick_validate.py accepts.

The upstream rule source is ~/.claude/skills/skill-creator/references/frontmatter-rules.md — re-check it when allowed-keys or YAML safety rules change.

Mandatory checks (every audit)

Run python ~/.claude/skills/skill-creator/scripts/quick_validate.py "$SKILL_PATH" first — it catches checks 1, 3, 4, 6, 9 mechanically and warns on 5. The remaining checks need a human / agent read.

YAML safety — the special characters

Quote any frontmatter string value that contains any of these:

:  #  -  <  >  |  {  }  [  ]  ,  &  *  ?  =  !  %  @  `

Safest default: quote every multi-word string value.

# BROKEN — colon after "workflow" starts a new YAML mapping in strict parsers
description: Follows a 5-step workflow: Analyze -> Design -> Plan -> Execute -> Summarize.

# FIXED
description: "Follows a 5-step workflow: Analyze -> Design -> Plan -> Execute -> Summarize."

# BROKEN
compatibility: Claude Code; requires asm on PATH

# FIXED
compatibility: "Claude Code; requires asm on PATH"

If the value contains literal double quotes, escape them with \".

Normalizing asm eval --fix output (mandatory after Phase 1)

asm eval --fix only writes top-level keys when authorship or version is missing entirely:

• No authorship anywhere (no author, metadata.author, creator, or metadata.creator) → --fix appends top-level author: <git user.name>.
• No version anywhere (no metadata.version or top-level version) → --fix appends top-level version: 0.1.0.

quick_validate.py rejects both top-level author: and top-level version: as unexpected keys. The fix migrates them under metadata:. Older skills authored before the author rename may also carry a top-level creator: — treat it the same way (migrate to metadata.author).

Before (post---fix, fails Gate 1)

---
name: my-skill
description: "..."
license: MIT
compatibility: Claude Code
allowed-tools: Bash Read Write
effort: high
author: alice # written by --fix when no authorship existed
version: 0.1.0 # written by --fix when no version existed
---

After (passes Gate 1)

---
name: my-skill
description: "..."
license: MIT
compatibility: "Claude Code"
allowed-tools: Bash Read Write
effort: high
metadata:
  version: 0.1.0
  author: alice
---

Migration rules

1. `author` → `metadata.author`. Value carries over verbatim. This is the primary case for skills processed by the current --fix. If a legacy top-level creator: is present instead (older fixer output), apply the same migration — both resolve to metadata.author. If metadata.author already exists, prefer the non-empty value; if both have values, prefer the top-level one (that's what --fix just wrote) and drop the duplicate. 2. `version` → `metadata.version`. Same value-carryover rule. If metadata.version already exists with a different semver, prefer the higher one (the auto-improver bumped it). 3. Other unexpected top-level keys. Drop anything outside the allowed set (name, description, license, allowed-tools, metadata, compatibility, effort). The current --fix does not write tags:, but legacy skills sometimes carry it — surface non-trivial drops to the user before deleting. 4. Quote any value with the special characters listed above. 5. Re-run `quick_validate.py` after migration to confirm clean.

Allowed-key drift

Sometimes a published skill carries fields invented by older tooling: architecture, model, category, dependencies. None are in the allowed set. Two options:

• If the field encodes information used at runtime (rare), move it under metadata: (any nested keys are accepted)
• Otherwise, drop it and surface to the user as a finding

Don't silently delete a non-trivial field — surface it first.

How to apply audit findings

1. Run quick_validate.py first. Mechanical pass means most checks 1, 3, 4, 6, 9 are clean. 2. For each remaining check:

• Fix mode (user asked to improve): apply the correction, bump `metadata.version` (patch for frontmatter-only).
• Review mode (user asked only for a report): write the before/after YAML in the report and let the user paste it.

3. Add a Frontmatter valid row to the Step Completion Report for the phase that ran the audit. 4. The audit is cheap — re-run after every loop iteration that touches frontmatter.

Report template

The final .asm-improver/report.md produced by this skill. PASS layout first, BLOCKER layout second. The report covers both gates — the skill-creator standard (Gate 1) and the asm-eval 85/8 floor (Gate 2).

PASS example

# Skill improvement report

Skill: skills/my-skill
Verdict: PASS
Gate 1 (skill-creator standard): √ pass
Gate 2 (asm-eval): overallScore 91, min category 8
Iterations: 3 of 8
Target version: 0.2.0 → 1.0.0

## Gate 1 — skill-creator standard

| Check                                | Baseline    | Final |
|--------------------------------------|-------------|-------|
| quick_validate.py exit code          | 1 (rejected)| 0     |
| Allowed top-level keys only          | ×           | √     |
| metadata.version present             | ×           | √     |
| metadata.author present              | ×           | √     |
| Description ≤250 chars               | √           | √     |
| Negative-trigger clause              | × (warning) | √     |
| SKILL.md body <500 lines             | √ (290)     | √ (290)|
| docs/README.md AI-skip notice        | √           | √     |
| Bundled scripts have descriptive errors | n/a      | n/a   |

## Gate 2 — asm-eval categories

| Category            | Baseline | Final | Delta   |
|---------------------|----------|-------|---------|
| structure           | 10       | 10    | 0       |
| description         | 4        | 9     | +5      |
| prompt-engineering  | 3        | 10    | +7      |
| context-efficiency  | 6        | 9     | +3      |
| safety              | 5        | 8     | +3      |
| testability         | 2        | 8     | +6      |
| naming              | 10       | 10    | 0       |
| **Overall**         | **57**   | **91**| **+34** |

## Files changed
- SKILL.md
- references/examples.md (new)
- references/prerequisites.md (new)
- docs/README.md (added AI-skip notice)

BLOCKER example

Same layout as PASS, plus a ## Blockers section listing every gate check still failing with a one-line reason:

## Blockers

- **Gate 1 — quick_validate.py**: still rejecting top-level key `architecture`. Field encodes no runtime info; author decision needed: drop it or move under metadata.
- **Gate 2 — testability** (stuck at 6/10): evaluator wants verifiable outputs; skill output is subjective prose. Author decision needed.
- **Gate 2 — safety** (stuck at 7/10): no destructive-action guardrail; add a dry-run or confirmation step.

The verdict line on a blocker reads:

Verdict: BLOCKER
Gate 1 (skill-creator standard): × failing 1 check
Gate 2 (asm-eval): overallScore 86, min category 6 (below floor)

Both gate states are reported even when only one is failing — so a reviewer can see at a glance which gate is the holdup.

Skill-creator Standard — Retrofit Checklist

The Gate 1 must-pass floor. Every item here mirrors a rule the skill-creator enforces (quick_validate.py, frontmatter rules, README template, writing guide). When the auto-improver retrofits a target skill, it walks this checklist top to bottom, fixing each item in place.

The upstream source of truth lives at ~/.claude/skills/skill-creator/references/frontmatter-rules.md, writing-guide.md, and readme-template.md. This file is the operational checklist — re-check upstream when scoring rules or formats change.

1. SKILL.md frontmatter

Use only these top-level keys. Anything else is rejected by quick_validate.py:

• name (required, kebab-case, ≤64 chars, must match parent directory)
• description (required, single line, ≤1024 chars hard, ≤250 chars target)
• license (optional)
• allowed-tools (optional)
• metadata (required when shipping; nest version, author here)
• compatibility (optional, ≤500 chars)
• effort (optional; one of low | medium | high | xhigh | max)

metadata: must contain at minimum version: MAJOR.MINOR.PATCH and author: <name>. If a published skill has neither, add both — start version at 1.0.0 if there was none.

If asm eval --fix wrote top-level creator:, version:, or tags:, normalize per frontmatter-audit.md immediately — those keys fail quick_validate.py.

2. Description quality

Two clauses, written as one or two back-to-back sentences:

• Positive: lead with an action verb, name what the skill does and when to invoke
• Negative: name 2–3 adjacent domains that should NOT trigger the skill

Example:

description: "Improve an existing SKILL.md so it passes the skill-creator standard AND clears the asm-eval 85/8 floor. Use when leveling up a skill before publish. Don't use for authoring from scratch, bulk evaluation, or rewriting prose style."

quick_validate.py warns (non-fatal) if the negative-trigger clause is missing — treat that warning as a Gate 1 failure and fix it.

Length budget:

• Hard ceiling: 1024 chars (API spec)
• Target: ≤250 chars (Claude Code's /skills truncates tail-first beyond this, chopping the negative-trigger clause)
• Below 250 is the only safe zone for production skills

3. SKILL.md body

• Under 500 lines. Hard rule. Longer files burn tokens on every invocation and bury important guidance.
• Use progressive disclosure: dense topics live in references/<topic>.md, SKILL.md links to them with one-line pointers like "Read references/foo.md when you need X".
• Imperative voice for instructions ("Run", "Read", "Write"), not narrative ("The agent might want to consider running...").
• A ## Step Completion Reports section that emits a status block after each major phase.
• A ## Repo Sync Before Edits (mandatory) section if the skill mutates a git repo.

4. docs/README.md (if present)

Every README.md must carry the AI-skip HTML comment at the very top, on its own block:

<!--
  DO NOT READ THIS FILE — This README.md is for human catalog browsing only.
  It ships inside the .skill package but is NEVER auto-loaded into agent context.
  The runtime loader only reads SKILL.md + references/ + scripts/ + agents/ when the skill triggers.
  If you're an AI agent, read the SKILL.md file instead for skill instructions.
-->

Required README sections (per ~/.claude/skills/skill-creator/references/readme-template.md):

• Title (human display name)
• Tagline (one-sentence blockquote)
• Highlights (3–5 bullets)
• When to Use (table of trigger phrases → action)
• How It Works (mermaid graph TD diagram, first node green #4CAF50, last node blue #2196F3)
• Usage (slash-command code block)
• Output (what files / artifacts the skill produces)

5. Bundled scripts

If the skill ships scripts under scripts/, every error path must print a descriptive message before exiting, on stderr. Three things every error message says: what went wrong, which input caused it, how to fix it.

# BAD
[ -z "$NAME" ] && exit 1

# GOOD
if [ -z "$NAME" ]; then
  echo "Error: missing required field 'name' in SKILL.md frontmatter." >&2
  echo "Expected format: name: my-skill-name" >&2
  exit 1
fi

# BAD
if not data.get('version'):
    sys.exit(1)

# GOOD
if not data.get('version'):
    print(
        "Error: metadata.version missing from SKILL.md frontmatter. "
        "Add `metadata:\\n  version: 1.0.0` and re-run.",
        file=sys.stderr,
    )
    sys.exit(1)

The agent that just ran the script should be able to self-correct without the user intervening.

6. References directory

If SKILL.md references files in references/, every referenced path must exist. Broken links waste a tool call. Use one-level deep references (references/foo.md) — don't nest references/sub/foo.md unless the skill genuinely needs that hierarchy.

7. Version bump

Every iteration that edits the SKILL.md body or frontmatter must bump metadata.version exactly once:

• Patch (x.y.Z) — typo, wording, frontmatter normalization
• Minor (x.Y.0) — new sections, new triggers, new references
• Major (X.0.0) — restructured workflow, breaking output format

Bump once per loop iteration, not once per individual edit — otherwise the version churns ahead of meaningful change.

8. Final mechanical check

Before declaring Gate 1 cleared, run:

python ~/.claude/skills/skill-creator/scripts/quick_validate.py "$SKILL_PATH"

Exit code 0 with no WARNING lines on stderr = Gate 1 clean. WARNING lines (e.g., missing negative-trigger, description over 250 chars) are findings that must be cleared before exit.