Repair Skill

Skill Repair

Audit and improve an existing skill against a gold standard. Unlike create-skill (which generates from scratch), this skill diagnoses violations and identifies gaps — what is broken, what is missing, and what would raise quality. The output is a structured improvement plan covering all dimensions.

Phase 1: Load the Skill

Read $ARGUMENTS as the path to a skill directory or SKILL.md file.

• If a directory: read SKILL.md, then list and note which of references/, examples/,

scripts/, assets/ exist and which are referenced from SKILL.md

• If a file: read it directly, then discover sibling resource directories

If the path is missing or ambiguous, use AskUserQuestion to resolve before proceeding.

Load all three reference files before Phase 2:

1. ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/skill-anatomy.md — gold standard for correct anatomy, three-level loading model, directory type definitions, degrees of freedom, naming conventions, body conventions. Required for Dimensions 5, 6, and 7. 2. ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/frontmatter-options.md — complete frontmatter field catalog, valid values, tool list, tool selection framework. Required for Dimensions 1 and 2. 3. ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/audit-calibration.md — known false-positive patterns that look like violations but are not. Prevents over-flagging on D2 (allowed-tools absent), D4 (Task/Skill prose), and D5 (orientation vs routing).

Proceed to Phase 2 when: SKILL.md is read, sibling directories are cataloged, and all three reference files are loaded.

Phase 2: Audit

Run each dimension independently. For each finding record: the dimension code, what is wrong or missing, which principle it violates or which gold standard it falls short of, and the specific change required. Proceed to Phase 3 when all 7 dimensions are evaluated.

Finding types:

• Violation — something present that contradicts a rule
• Gap — something absent that would improve the skill against the gold standard
• Improvement — something that works but could be meaningfully tightened

Severity:

• critical — breaks triggering or wastes significant context on every invocation
• major — degrades generalization, reliability, or workflow correctness
• minor — polish; the skill works but isn't as good as it could be

---

Dimension 1 — Frontmatter Quality

The description is the only part of a skill that is always in context. Every token here costs budget across every session. Audit for violations and gaps:

Violations:

• Person and framing: Is the description third-person ("This skill should be used

when...")? First-person or imperative framing reads as an instruction to execute, not a triggering condition to evaluate. Critical if wrong.

• Scalar type: Does the description use > (folded scalar)? The | literal scalar

preserves newlines and can produce unexpected whitespace when parsed. Minor.

• Trigger phrase authenticity: Are quoted phrases verbatim user speech — the exact

tokens a user would type? Paraphrases ("hook creation tasks") have lower routing match rates than natural language ("create a hook"). Major if paraphrased.

• Token density: Does the description restate the skill name, explain what skills are,

or include meta-commentary? Every such token is budget waste. Minor per instance, major if systemic.

Gaps:

• Trigger phrase coverage: Are there 3–5+ varied phrases? Single-phrase descriptions

miss synonym space. Does coverage include the naive phrasing a user would use who has never heard of this skill? Major if sparse.

• Missing `argument-hint`: Does the skill read $ARGUMENTS or $1/$$2 without an

argument-hint field? The hint is shown in autocomplete — its absence means users don't know what to pass. Minor.

• Name validity: Is the skill name lowercase, hyphens only, max 64 chars? Verb-led for

commands? Namespaced when it aids routing clarity? These constraints ensure filesystem compatibility, command-line ergonomics, and unambiguous routing. Minor if wrong.

• Trigger accuracy: Mentally generate 3 prompts that should trigger this skill and 3

that should NOT (from adjacent domains). Does the description cover the should-triggers and exclude the shouldn't-triggers? Sparse coverage or broad false-trigger surface is a routing quality gap. Major if coverage is sparse.

• Token budget: Is the description over 100 tokens? Per-session cost scales with

description length across all installed skills. Over 150 tokens is a violation (major); 100–150 is a gap (minor) — tighten by prioritizing trigger phrases over prose.

• Negative triggers absent: For skills in crowded domains (multiple skills with

overlapping concerns), does the description include explicit "Not for X" exclusions? Negative triggers sharpen the routing decision boundary. Minor.

---

Dimension 2 — Execution Modifiers

Modifiers left at their defaults are not errors — omitting them is correct when defaults apply. Audit for mismatches (violations) and missing configuration (gaps).

Refer to frontmatter-options.md for the complete field catalog, model selection table, and tool selection framework.

Violations:

• Does the skill have unrestricted Bash when a scoped pattern (Bash(git:*)) would work?
• Does the skill have tools in allowed-tools it never uses? Dead entries add noise.

Gaps:

• Does the skill invoke other skills or spawn agents without Skill or Task in allowed-tools?
• Does the skill require user decisions mid-workflow but lacks AskUserQuestion in allowed-tools?
• Does the skill read a file path from $1 but uses a Read tool call instead of @$1

inline injection? A tool round-trip is being wasted. Minor.

• Could real-time data (git status, env vars, file tree) be injected using dynamic content

syntax (bang + backtick-wrapped command) instead of a tool call? Major when the skill's workflow begins with infallible probes (git branch, file tree, env vars) that never need error handling; Minor for commands that may fail or need exit-code branching.

Before (wastes tool round-trips):

  1. Run `git log --oneline -5` using Bash
  2. Run `git diff --name-only` using Bash
  3. Analyze the results...

After (injected at invocation, zero tool calls). Replace those Bash calls with:

• Recent commits: !\git log --oneline -5\
• Changed files: !\git diff --name-only\

Then continue with prose like "Analyze the results..."

Note: The backslashes escape the backticks so this documentation

doesn't execute — in a real skill, write !\cmd\ without the backslashes.

---

Dimension 3 — Intensional vs Extensional Instruction

A rule stated with its reasoning generalizes to every input. An example that implies a rule requires the reading model to reverse-engineer the rule — two reasoning hops instead of one, covering only the shape of that example.

Violations:

• Does it show a good/bad contrast and leave the principle implicit? The principle should

be stated first; the contrast confirms it, not carries it.

• Is a "Common Mistakes" or "Bad/Good examples" section doing the work that a single

principle sentence could do more efficiently? Major.

• Would removing the examples leave the rule intact and still actionable? If yes, the

examples are redundant. If no, the rule hasn't been stated yet — state it.

Gaps:

• Are there instruction blocks that tell Claude what to do but not why? Adding the

reasoning makes the instruction generalize to edge cases not covered by the current examples. Major per uncovered block.

---

Dimension 4 — Agentic vs Deterministic Split

Load `${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md` before auditing this dimension. It contains the five signal patterns for recognizing a script candidate, CLI design conventions, common archetypes (init, validate, transform, package, query), and the delegation pattern for using create-cli to design the interface.

Skills mix LLM-guided reasoning (agentic) and script execution (deterministic). The split should be deliberate — see the Degrees of Freedom table in skill-anatomy.md.

Violations:

• Code blocks that are repeated or identical across invocations — these are

deterministic operations being re-generated each time. They belong in scripts/. Inlining costs context tokens on every run; scripts execute without being loaded.

• Prose that describes a deterministic sequence — if the steps are always the same

regardless of input, a script is more reliable than asking the model to reproduce them.

• Scripts that exist but aren't referenced in SKILL.md — Claude won't use them.

A script without a reference in SKILL.md specifying when and how to invoke it is invisible to the skill workflow. Major.

• Vague script references — "run the validation script if needed" is not actionable.

References must state the trigger condition, the exact invocation, and how to interpret the output. Minor.

Gaps — apply the five signal patterns from `script-patterns.md` to each workflow step:

• Signal 1 (Repeated Generation): Does any step produce the same structure with

different parameters across invocations? → Parameterized script candidate. Major.

• Signal 2 (Unclear Tool Choice): Does any step require combining multiple standard

tools in a fragile sequence to accomplish something naturally expressible as a single function? → Script the procedure. Major.

• Signal 3 (Rigid Contract): Does any step have an input/output shape clear enough

to write --help text for right now? → CLI candidate; delegate design to create-cli.

• Signal 4 (Dual-Use Potential): Would any step be useful to run independently from

the terminal, outside the skill workflow? → Design as proper CLI from the start.

• Signal 5 (Consistency Critical): Does any step need to produce identical output

for identical inputs — not "similar" but reproducible? → Script, not LLM generation.

• Judgment steps with no criteria — "analyze the situation" is agentic but unanchored.

Agentic steps need explicit criteria for what to consider and what constitutes a good outcome. Major per uncovered step.

---

Dimension 5 — Verbosity and Context Efficiency

Every token in SKILL.md is loaded into context when the skill triggers. Audit for tokens that consume budget without improving outcomes, and for content that belongs in references/ instead.

Refer to the size invariants table in skill-anatomy.md to calibrate severity.

Violations:

• Prose that restates the section header — "## Validation" followed by "In this

section we will validate..." is pure redundancy. Minor per instance.

• Hedging language — "you might want to consider", "it could be useful to",

"generally speaking". Replace with direct imperatives or remove. Minor per instance.

• Code blocks illustrating a principle stateable in one sentence — a good/bad YAML

contrast often collapses to one intensional rule. Major if pattern is frequent.

• Code blocks collapsed to prose that lose variable bindings — a code block that

assigns workflow variables (BASE=..., BRANCH=...) used by later steps serves two purposes: illustrating the operation AND establishing state. Collapsing it to prose without preserving the bindings leaves downstream $VAR references unbound. When collapsing, add a "derive working variables" preamble that explicitly binds each variable in prose. Major per lost binding.

• Repeated guidance across sections — the same rule in a "Best Practices" section and

a "Common Mistakes" section. Consolidate to one location. Minor.

• "When to Use This Skill" section in the body — body loads only after triggering;

routing guidance here is never read by the routing decision. Dead tokens every invocation. Major.

• Headers deeper than H3 — signals content that belongs in references/. Minor.
• SKILL.md over ~500 lines — requires references/ deferral. Major.
• Extraneous documentation files (README.md, CHANGELOG.md, INSTALLATION.md) in

the skill directory — never loaded into context, add noise to the package. Minor per file.

Gaps:

• Would a `references/` file reduce SKILL.md size? Identify sections only needed for

specific sub-tasks and flag them as deferral candidates. Major if SKILL.md > 300 lines.

• Would a `references/` file for domain-specific data help? Lookup tables, option

catalogs, field definitions — these are reference data, not instructions. Major.

---

Dimension 6 — Workflow Clarity

A skill's process should be sequential, complete, and have explicit exit conditions at each phase. Audit for broken workflow and for missing structure that would help.

Violations:

• Is the process structured as numbered phases with clear names? Without explicit phases

the model can't track progress or know which step it's in. Major if unstructured.

• Does each phase have an explicit exit condition? Without one, the model doesn't know

when to stop iterating on a phase and may loop or skip prematurely. Major if missing.

• Are there half-thought steps — phases that describe intent without specifying what to

do or how to evaluate the result? Major per uncovered phase.

• Does the skill handle missing, ambiguous, or malformed input?

Gaps:

• Variable continuity: Does every $VAR referenced in a step have an explicit binding

in an earlier step or a pre-flight/preamble section? Scan all $VARNAME tokens in the skill body and trace each back to its origin. An unbound variable is a workflow break — the agent either halts on an invalid command or silently substitutes an empty string. Major per unbound variable.

• Is there a delivery phase that tells Claude what to produce and in what format? Many

skills describe the process clearly but leave the output format implicit. Major if absent.

• Would a validation checklist at the end of the workflow catch errors that prose

instructions miss? Minor.

• Would an examples/ directory help users understand what the expected output looks

like? Minor.

---

Dimension 7 — Anatomy Completeness

Refer to skill-anatomy.md for the gold standard directory anatomy and the Gap Analysis Checklist. This dimension asks: does the skill's structure match its complexity tier, and what is absent that would raise it?

Use the Gap Analysis Checklist from `skill-anatomy.md` directly. For each "yes" answer, record a gap at the appropriate severity.

Violations:

• Does the skill have a scripts/ directory with scripts not referenced in SKILL.md?

Major — referenced or delete.

• Does the skill have a references/ directory with files not pointed to from SKILL.md?

Major — referenced or delete.

• Does the naming violate conventions (uppercase, underscores, over 64 chars)? Minor.

Gaps — ask for each absent directory:

• Missing `scripts/`: Is there a deterministic operation that would be more reliable

scripted? Does the same code block appear or would it appear in multiple invocations?

• Missing `references/`: Does SKILL.md exceed 300 lines? Are there sections only

needed for specific sub-tasks? Is there domain-specific reference data?

• Missing `examples/`: Does the skill produce output users adapt? Are there ambiguous

instructions a working example would clarify better than prose?

• Missing resource pointers in SKILL.md: Are there directories present but not

referenced — invisible to Claude unless it guesses to look?

---

Phase 3: Improvement Report

Present findings as a structured report. Split violations from gaps — a violation is something wrong, a gap is something missing that would improve the skill.

SKILL IMPROVEMENT REPORT: <skill-name>
Current tier: [simple / standard / complex] — [lines] lines, [directories present]

VIOLATIONS
──────────
CRITICAL
  [D1] Description uses first-person — routing model reads as instruction, not trigger.
       Fix: rewrite as "This skill should be used when the user asks to..."

MAJOR
  [D3] Body teaches frontmatter quality by bad/good contrast; principle never stated.
       Fix: state the rule ("quoted phrases must be verbatim user speech because routing
       matches on literal tokens") then keep the contrast as confirmation.
  [D5] "When to Use This Skill" section in body — dead tokens every invocation.
       Fix: move routing guidance to frontmatter description, delete body section.

MINOR
  [D1] Description uses | scalar instead of >.
       Fix: change to >.

GAPS (what would improve this skill)
─────────────────────────────────────
MAJOR
  [D7] SKILL.md is 420 lines with no references/ directory. Three sections (option catalog,
       field definitions, examples table) are only needed for specific sub-tasks.
       Improvement: extract to references/; add load pointer in SKILL.md for each.
  [D4] File-path validation logic is inlined but must produce consistent output.
       Improvement: move to scripts/validate-input.py; reference from Phase 2.

MINOR
  [D2] Skill reads $1 as a file path but uses Read tool — @$1 injection would save a
       tool round-trip.
       Improvement: replace Read call with @$1 inline injection.
  [D7] No examples/ directory; skill produces config output users adapt.
       Improvement: add examples/ with one representative output file.

Group violations by severity, then gaps by severity. For each: dimension code, what is wrong or missing, the principle or gold standard it falls short of, the exact fix.

Ask: "Apply all critical and major items? Or select specific ones?"

---

Phase 4: Apply Improvements

Apply confirmed items in order: critical violations → major violations → major gaps → minor violations → minor gaps.

For each item:

• State what is being changed or added and why (principle reference, not just "you asked")
• Make the edit or create the file
• Confirm the change is consistent with surrounding content

Explain Your Choices

After applying improvements, briefly explain:

• What was changed and why — reference the principle: "Rewrote description as

third-person because first-person framing is parsed as an instruction to execute, not a triggering condition to evaluate"

• What was added and why — "Created references/options.md and deferred the option

catalog because SKILL.md was 420 lines and the catalog is only needed for the configuration sub-task"

• What was left unchanged and why — "hooks left unset — no lifecycle validation needed"
• What remains for the user to address — "The examples/ gap requires domain knowledge

to fill; a placeholder directory was created"

Phase 4 is complete when all confirmed items are applied, the explanation is delivered, and the validation checklist passes.

---

Validation

After applying all improvements, load ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/quality-checklist.md and run the quality standards check followed by the item-by-item validation checklist. Report any failing items before delivering final results.

Audit Calibration — Known False-Positive Patterns

Load before running the 7-dimension structural audit. Each entry describes a rule that is correct in principle but frequently misapplied to look-alike situations that should not trigger the rule.

---

D2 / allowed-tools absent

allowed-tools absent entirely means unrestricted by default — this is NOT a violation at any severity. The field is an optional restriction mechanism, not a required declaration. Only flag when a skill has an existing allowed-tools list that omits a tool the skill actively uses — a partial restriction creates the problem; absent restriction does not.

Flag this: Skill has allowed-tools: [Read, Write] but calls AskUserQuestion → major violation (restricted list is incomplete).

Do not flag this: Skill has no allowed-tools field but calls AskUserQuestion → no violation; the tool is available by default.

---

D5 / Orientation content vs routing guidance

Flag as a routing-guidance violation only when the body contains a "When to Use This Skill" section or explicit language telling the user when to trigger the skill. Content that explains domain concepts needed during execution — so the skill can make accurate decisions — is functional orientation, not routing guidance.

Rate functional orientation as verbosity (minor) only if it exceeds 4–5 lines without adding decision value that the skill body requires.

Flag this: Body has ## When to Use This Skill — use this when you want to create a new skill → major violation (routing guidance in always-loaded body, never read by the routing decision).

Do not flag this: Body has Agents vs Skills — know the difference before generating: Agents run in isolated context, Skills inject inline → functional orientation that helps the skill produce accurate output; not routing guidance.

---

D4 / Task/Skill invocation prose

Natural language inside a fenced block describing how to call Claude's own tools is the idiomatic skill instruction format — Use Task tool with subagent_type=X: "..." is how skills correctly instruct Claude. Do not flag this as a vague script reference.

Only flag D4 prose as a violation when it refers to user-facing scripts or deterministic CLI operations (validate.py, init.sh, etc.) without specifying which file, the trigger condition, and the exact invocation command.

Flag this: Body says "run the validation script if needed" with no path, trigger, or invocation → major violation (deterministic script reference is vague).

Do not flag this: Body has a code block: Use Task tool with subagent_type=claude-code-guide: "List current frontmatter options" → idiomatic instruction to Claude to use a built-in tool; not a script reference.

---

D5 / Code blocks that assign workflow variables

Code blocks that assign variables (BASE=..., BRANCH=$(...)) used by later steps are NOT purely illustrative — they establish workflow state. Do not flag these as "code blocks collapsible to prose" under D5. Collapsing them without preserving the bindings introduces unbound-variable bugs in downstream steps.

Flag this: Code block assigns BRANCH=$(git rev-parse ...) and is collapsed to "Check the current branch" without binding $BRANCH anywhere → major D5 violation (prose collapse lost variable binding).

Do not flag this: Code block assigns BRANCH=$(git rev-parse ...) and a later prose preamble says "Derive: BRANCH = current branch from pre-flight injection" → the binding is preserved; the collapse is valid.

Frontmatter Options Reference

Complete reference for auditing skill and command frontmatter. Load this before running Dimension 2 audits. Every field listed here is the full set of valid options — anything not on this list is not a valid frontmatter key.

Fields

name (string)

Lowercase letters, digits, and hyphens only. Max 64 characters. Omit to use the directory name as the identifier. Prefer short, verb-led names for commands. Namespace by tool when it aids routing clarity: gh-address-comments, linear-close-issue.

description (string)

The primary triggering mechanism. Always in context — costs tokens on every session regardless of whether the skill is active. Use > folded scalar (not | literal). Must be third-person for skills ("This skill should be used when..."), verb-first under 60 chars for commands.

Audit rules for description quality:

• Token budget: Under 150 tokens for most skills, 200 absolute max. Anthropic's hard limit is 1024 characters (~250 tokens); descriptions over 250 characters are truncated in the skill listing. Prioritize trigger phrases over explanatory prose.
• Trigger phrase derivation: Phrases should be verbatim user speech — the exact words someone would type, not formalized paraphrases. "fix my skill" triggers better than "skill remediation workflow."
• Negative triggers: In crowded domains (multiple skills with overlapping concerns), include "Not for X" or "Don't use for Y" to sharpen the routing decision boundary.
• 3–5 varied trigger phrases minimum. Single-phrase descriptions have high miss rates. Include naive phrasing from a user who has never heard of this skill.
• Overtriggering check: Claude tends to undertrigger skills. If the description has no routing directive ("Make sure to use this skill whenever the user mentions [X, Y, Z] — even if they don't explicitly say '[skill name]'"), flag it for the author to consider adding one. The routing suffix uses intent categories and concept words (broad, generalizable), not verbatim query phrases (which overfit). The core uses verbatim phrases (optimized for recall); the suffix uses category words (broad, anti-overfit). These two layers are not interchangeable.

allowed-tools (list)

Restricts which tools the skill can use. Default is unrestricted. Specifying this list is a security and scope constraint — use it to limit blast radius for sensitive skills.

YAML format constraint: allowed-tools must be a YAML list — either a block sequence (- Tool) or a flow sequence ([Tool, Tool]). A comma-separated string on one line (allowed-tools: Read, Glob, Edit) parses as the scalar string "Read, Glob, Edit", not a 3-element list. Tools may not be recognized by the runtime. Critical if wrong.

Complete tool list:

Audit rule: Bash unrestricted is almost always wrong — scope it. AskUserQuestion must be present if the skill asks the user anything. Skill must be present if the skill invokes another skill by name.

Tool Selection Framework

The core principle: restrict tools that have destructive or side-effect potential, not tools that are read-only or purely generative. Over-restriction breaks the skill; under- restriction is a security and scope risk.

Gap audit questions:

• Does the skill need user decisions but lacks AskUserQuestion? → add it
• Does the skill invoke another skill but lacks Skill? → add it
• Does the skill write files but has no Edit or Write? → add them
• Does the skill have unrestricted Bash when a scoped pattern would work? → scope it
• Does the skill have Bash(git:*) but never uses git? → remove it (dead scope)

hooks (object)

Scoped to this skill's lifetime — runs only when the skill is active, cleaned up when it finishes.

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "scripts/validate-input.sh"
          timeout: 10
          statusMessage: "Validating..."
  PostToolUse:
    - hooks:
        - type: command
          command: "scripts/cleanup.sh"
  Stop:
    - hooks:
        - type: command
          command: "scripts/on-complete.sh"
          once: true

All hook events are supported (PreToolUse, PostToolUse, Stop, SessionStart, etc.). Each entry can have a matcher (filter by tool name) and a hooks array with handlers. Handler fields: type (command, http, prompt, agent), command, timeout (seconds), statusMessage (custom spinner text), once (skills only — run once then auto-remove).

Audit rule: hooks with no matcher fire on every tool call — verify this is intentional. Hooks using once: true outside of skills are invalid (agents don't support it).

user-invocable (boolean)

Use false for background-knowledge skills that should activate automatically but shouldn't clutter the command menu.

disable-model-invocation (boolean)

Commands only. Prevents Claude from auto-loading this skill based on its description. Forces manual invocation only. Default: false.

argument-hint (string)

Shown in autocomplete when the user types the command. Documents expected argument syntax. Examples: "[issue-number]", <path-to-skill>, "[skill|command] [name]".

Quoting rule: values that contain [...] must be quoted ("[arg]"), because YAML treats unquoted [ as the start of a flow sequence. Values using only <...> do not need quoting.

Audit rule: any skill that reads $ARGUMENTS or $1/$2 should have argument-hint set so users know what to pass.

context (string)

Set to fork to run the skill in an isolated subagent. The skill content becomes the subagent's prompt; it won't have access to conversation history. Use for task-type skills where isolation prevents accidental side effects. Pair with agent.

agent (string)

Which subagent type to use when context: fork is set. Options: built-in agents (Explore, Plan, general-purpose) or custom agents from .claude/agents/. If omitted, uses general-purpose.

Audit rule: agent without context: fork is dead config — flag it.

effort (string)

Override session effort level: low, medium, high, max (max is Opus 4.6 only). Use high/max for skills requiring deep reasoning; low for simple lookup skills.

paths (string or list)

Glob patterns limiting auto-activation. When set, Claude loads the skill automatically only when working with files matching the patterns. Accepts comma-separated string or YAML list. Uses the same format as path-specific rules in CLAUDE.md.

Audit rule: skills with paths set should not also have broad descriptions — the path filter narrows scope, so the description should match that narrowed scope.

shell (string)

Shell for inline !\cmd\ blocks and `! fenced blocks: bash (default) or powershell. Only relevant for skills using inline shell execution.

---

Skill Content Lifecycle

When invoked, the rendered SKILL.md enters the conversation as a single message and stays for the rest of the session. Claude Code does not re-read the file on later turns — write guidance as standing instructions, not one-time steps.

Auto-compaction carries invoked skills forward within a token budget: the first 5,000 tokens of each skill are retained after compaction, and all recently invoked skills share a combined 25,000-token budget (filled most-recent-first). Skills exceeding 5,000 tokens lose their tail after compaction. Skills invoked long ago may be dropped entirely if the budget is exhausted.

Audit relevance: if a skill's critical instructions appear after the first ~5,000 tokens, they will be lost after compaction. Flag this as a structural issue — front-load critical content or move reference material to separate files.

---

Dynamic Content Syntax

These substitutions are processed before the skill body reaches Claude.

Audit rule: skills that accept a file path as input should use @$1 to load it inline rather than requiring a separate Read tool call — the injection happens before the model sees the skill, saving a tool round-trip. The bang-backtick pattern is underused: real-time data like git branch, file tree, or env vars can be injected without tool calls.

Quality Standards & Validation Checklist

Load this after Phase 4 improvements are applied. Use the quality standards to verify the overall repair meets the bar, then run the checklist item by item.

---

Quality Standards

A fully improved skill satisfies all of the following:

Anatomy:

• Directory structure matches complexity tier (see skill-anatomy.md)
• Every resource file in scripts/, references/, examples/ is referenced in SKILL.md
• No extraneous documentation files in the skill directory

Format Economy:

• Simple instruction → single imperative, no surrounding prose
• Repeated operation → script in scripts/, not inlined code block
• Invocation-selective detail → deferred to references/

Intensional Instruction:

• Every rule states the why alongside the what
• Examples confirm stated principles; they do not carry the instructional weight alone
• Degrees of freedom match task fragility (see skill-anatomy.md)

Balance Flexibility with Precision:

• Agentic steps are loose enough for judgment with explicit outcome criteria
• Deterministic steps are scripted, not reproduced by the model each time

Remove ruthlessly: Filler phrases, headers that restate their content, hedging language, routing guidance in the body, extraneous documentation files.

---

Validation Checklist

Run after all improvements are applied:

Structure:

• [ ] SKILL.md exists with valid YAML frontmatter
• [ ] Frontmatter has name and description fields
• [ ] Markdown body is present and substantial
• [ ] Directory structure matches skill complexity tier
• [ ] Every resource file is referenced from SKILL.md

Frontmatter Quality:

• [ ] Description uses third-person ("This skill should be used when...")
• [ ] 3–5+ varied trigger phrases; includes naive user phrasing
• [ ] Description under 100 tokens (150 absolute max)
• [ ] Trigger phrases derived from natural user language, not formalized paraphrases
• [ ] Negative triggers present if skill operates in a crowded domain with adjacent skills
• [ ] Uses > scalar, not |
• [ ] argument-hint present if skill reads $ARGUMENTS/$1; value quoted if it contains [...]

Content Quality:

• [ ] Body uses imperative voice; no first-person, no second-person
• [ ] No "When to Use This Skill" section in the body
• [ ] No headers deeper than H3
• [ ] No extraneous files (README.md, CHANGELOG.md, etc.)
• [ ] Instructions are intensional (rule + reasoning), not purely extensional
• [ ] Agentic steps have explicit outcome criteria
• [ ] Deterministic operations are scripted, not inlined
• [ ] Variables referenced in later steps ($VAR) are bound in an earlier step or pre-flight section

Progressive Disclosure:

• [ ] SKILL.md under 500 lines; invocation-selective detail in references/
• [ ] scripts/ contains deterministic operations for low-freedom steps
• [ ] examples/ exists if skill produces user-adaptable output
• [ ] references/ defers topic-specific detail not needed every invocation

Tool Selection:

• [ ] AskUserQuestion present if skill needs user decisions mid-workflow
• [ ] Skill present if skill invokes other skills
• [ ] Bash scoped or absent; unrestricted Bash is flagged
• [ ] No dead tool entries (tools listed but never used)

Script Opportunities:

• [ ] No code blocks that would be re-generated identically across invocations
• [ ] Scripts in scripts/ are referenced with trigger condition and invocation
• [ ] No vague script references ("run if needed" without specifying when/how)
• [ ] Deterministic steps with consistency requirements are scripted, not LLM-generated

Skill Anatomy Reference

Gold standard for what a well-formed skill looks like at each tier. Load this before running any audit dimension — it is the rubric every dimension evaluates against.

---

The Three-Level Loading Model

This model governs every progressive disclosure and verbosity decision in a skill.

Why this matters for every audit decision:

• Anything in the description costs tokens on every session — justify every word
• Anything in SKILL.md costs tokens on every invocation — content that isn't needed for most runs belongs in references/
• Anything in references/ or scripts/ is free until needed — defer detail here aggressively

---

Gold Standard Directory Anatomy

Simple skill (no subdirectories needed)

skill-name/
└── SKILL.md    # Single file; body under 200 lines

Use when: the skill has one clear workflow, no reusable code, no domain-specific reference data.

Standard skill

skill-name/
├── SKILL.md          # Core instructions; 200–400 lines
└── references/
    └── topic.md      # Detail deferred from SKILL.md

Use when: SKILL.md would exceed ~300 lines without deferral, or when the skill has sections only needed for specific sub-tasks (e.g., advanced options, domain-specific lookup tables).

Complex skill

skill-name/
├── SKILL.md          # Navigation + core flow; under 500 lines
├── scripts/          # Deterministic operations
├── references/       # Documentation Claude reads while working
├── examples/         # Complete, runnable artifacts users can copy
└── assets/           # Output-only files (templates, images, fonts)

Use when: skill has reusable deterministic operations, domain-specific reference material, or produces output users will copy and adapt.

---

Directory Type Definitions

scripts/

Executable code (Python, Bash). The defining characteristic: scripts can run without being loaded into context — they are invoked by path, not read into the conversation. Use when:

• The same code block appears more than once across invocations (inline = re-generated each time)
• The operation is fragile or must produce identical output consistently
• A utility would benefit multiple phases of the workflow

Scripts that exist but are not referenced in SKILL.md are dead code — Claude cannot use them without a pointer. Every script must have an explicit reference with a description of when and how to invoke it.

references/

Documentation Claude reads while working. The defining characteristic: loaded only when Claude decides it needs them — kept out of SKILL.md to reduce base context cost. Use when:

• A section of SKILL.md would exceed ~100 lines for a single topic
• The information is only needed for specific sub-tasks, not every invocation
• Domain-specific data (lookup tables, option catalogs, field definitions) is needed
• The skill has multiple variants (e.g., AWS vs GCP vs Azure) and each needs its own file

Include a table of contents at the top of any reference file over 100 lines.

examples/

Complete, runnable artifacts. The defining characteristic: users copy these directly without modification. Distinct from references (docs you read) and scripts (utilities you invoke). Use when:

• The skill produces output users will adapt (config files, template code, structured prompts)
• Working examples would disambiguate ambiguous instructions more efficiently than prose
• The skill teaches by demonstration and the demo needs to be intact and executable

assets/

Files used in output but never loaded into Claude's context. The defining characteristic: consumed by other tools or included in deliverables, not read by the model. Use for: templates, images, fonts, boilerplate files, starter projects.

---

Degrees of Freedom

Match instruction specificity to the task's fragility and variability. Over-constraining flexible tasks breaks generalization; under-constraining fragile tasks breaks reliability.

Audit application: for each agentic step, ask whether the freedom level matches the task's actual variability. A step described vaguely that must produce consistent output is under-constrained (needs to move toward low freedom). A step with exact scripts for a judgment-heavy task is over-constrained (model's generalization is being wasted).

---

Naming Conventions

---

Body Structure Conventions

Voice and framing

• Imperative voice throughout: "Analyze", "Generate", "Identify" — not "You should analyze"
• No first-person narrative: Never "I will", "I am", "I'll then check" — the skill is instructions, not a plan
• No second-person: Avoid "you" entirely — second-person reads as addressing the user, not Claude
• No hedging language: Remove "you might want to", "consider possibly", "generally speaking"

Header depth

• H2 (##) for major phases or top-level sections
• H3 (###) for sub-topics within a phase
• No H4+ (####) — content this granular belongs in references/, not SKILL.md

Routing guidance placement

• Description only — routing guidance ("when to use this skill") belongs exclusively in frontmatter
• Never in the body — the body loads only after the skill has already triggered; routing guidance there is never read by the routing decision and wastes context on every invocation

Size invariants

---

Gap Analysis Checklist

Use this to identify what a skill would benefit from adding, not just what's wrong.

Would a `scripts/` directory help?

• [ ] Is there a code block that appears or would appear more than once?
• [ ] Is there a fragile operation that must produce consistent output?
• [ ] Is there a setup/validation/cleanup step that could be scripted?

Would a `references/` directory help?

• [ ] Does SKILL.md exceed 300 lines and have sections only needed for specific sub-tasks?
• [ ] Does the skill have domain-specific lookup data (option catalogs, field tables)?
• [ ] Does the skill have multiple variants (per-provider, per-framework) that could be split?

Would an `examples/` directory help?

• [ ] Does the skill produce output users will adapt (configs, templates, prompts)?
• [ ] Are there ambiguous instructions that a complete working example would clarify better than prose?
• [ ] Does the skill teach by demonstration?

Would additional frontmatter fields help?

• [ ] Does the skill accept a file path argument but lack argument-hint?
• [ ] Does the skill need user decisions mid-workflow but lacks AskUserQuestion in allowed-tools?