gupsammy avatar

claude-skills

Skill and agent authoring tools: generate, audit, and improve Claude Code skills, commands, and agents

version
0.5.28
GitHub stars
276

Install

/plugin install claude-skills@Claudest

Run it inside Claude Code after adding the marketplace with /plugin marketplace add gupsammy/Claudest.

Contents

Discovered from source

Skills 6

Agent Creator

Generate well-structured Claude Code agents — markdown files with YAML frontmatter that delegate complex multi-step work to autonomous subprocesses with isolated context windows.

Agents vs Skills — know the difference before generating:

  • Agents run in isolated context, have second-person system prompts ("You are..."), use concise > folded scalar descriptions (50-70 tokens, no <example> blocks), and are spawned via the Agent tool
  • Skills inject inline into the current conversation, use imperative body instructions for Claude to follow, and route via description matching on trigger phrases

Phase 0: Understand Requirements

Parse $ARGUMENTS for hints. Gather:

Identity:

  1. Domain & purpose — What problem does this agent solve?
  2. Expert persona — What specialist identity should it embody?

Triggering: 3. Trigger conditions — When should Claude delegate to this agent? What user messages activate it? 4. Proactive vs reactive — Should it fire automatically after events (e.g., after code is written), or only on explicit request?

Capabilities: 5. Tool access — What tools are actually needed? Least-privilege: an analysis agent doesn't need Write. 6. Memory — Should this agent learn across sessions? (e.g., accumulate codebase patterns, recurring issues, architectural decisions.) If yes, choose scope: project (recommended default, shareable via VCS), user (global across projects), or local (project-specific, not in VCS). 7. MCP servers — Does it need external tools (browser, database, API) not in the parent session?

Execution: 8. Session mode — Will this run as a subagent (delegated by Claude) or as the main session agent (claude --agent <name>)? Session agents need broader tool access, more self-contained prompts, and may use initialPrompt to self-start. 9. Background execution — Should it run concurrently while the user continues? Background agents auto-deny unpre-approved permissions and cannot ask clarifying questions. 10. Context isolation — Does it generate heavy output or modify files? Should it run in a worktree (isolation: worktree)? 11. Effort level — Does it need deep reasoning (high/max) or is it a fast classification task (low)?

If $ARGUMENTS is empty or insufficient, use AskUserQuestion to gather domain, trigger conditions, and proactive intent before proceeding. Proceed to Phase 1 once these are established.

Phase 1: Generate

Apply throughout: second-person for system prompt body, intensional over extensional reasoning, minimum viable frontmatter.

Step 1 — Choose identifier

Naming rules (enforced by validate_agent.py):

  • 3–50 characters, lowercase letters/numbers/hyphens only
  • Must start and end with alphanumeric
  • Avoid generic terms: helper, assistant, agent

Good: code-reviewer, test-generator, api-docs-writer Bad: ag (too short), -start (leading hyphen), my_agent (underscore)

Step 2 — Write frontmatter

Read ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md for the full field catalog, color semantics, model options, tool selection framework, and execution modifiers.

Required: name, description Always set: model: inherit (unless specific model capability needed), color (visual ID in UI)

Intensional rule for tools: Restrict to the minimum needed because agents run autonomously — over-permission has no human in the loop to catch it. ["Read", "Grep", "Glob"] for analysis. Add Write for generation. Add Bash only when shell execution is essential, never by default. For session-mode agents that orchestrate subagents, use Agent(type1, type2) to scope spawning.

Set if applicable from Phase 0:

  • memory — if cross-session learning was identified; add memory maintenance instructions to body
  • effort — if the task warrants non-default thinking depth
  • initialPrompt — if this is a session agent that should self-start
  • background: true — if concurrent execution was identified
  • mcpServers — if external tools were identified

Step 3 — Write description

The description field is loaded into context every session. Token budget matters — write the minimum needed for accurate routing.

Use a > folded scalar with:

  • "Use this agent when [trigger conditions]."
  • Proactive hint if applicable ("Recommended PROACTIVELY after...")
  • Scope boundary ("Not for X — use Y-agent.")
  • Target: 50-70 tokens. No <example> blocks — they waste context without improving routing.

Step 4 — Write system prompt

The markdown body (after ---) becomes the agent's system prompt. Write entirely in second person, addressing the agent directly. This is the critical authoring difference from skills: agents need a persona and process, not instructions for Claude to follow.

Standard structure:

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]

**Process:**
1. [Step — imperative]
2. [Next step]

**Quality Standards:**
- [Standard]

**Output Format:**
[Structure and content of what to return]

**Edge Cases:**
- [Situation]: [How to handle]

Intensional rules for the system prompt:

  • Persona first — the expert identity shapes all downstream decisions; establish it in the first sentence
  • Process steps prevent "winging it" on complex tasks; each step is an explicit decision boundary
  • Output format is non-negotiable — callers need predictable structure to consume results
  • Define edge cases in the system prompt; discovered-at-runtime errors cost retries

If memory is set: Include a section instructing the agent to maintain its knowledge base: "Update your agent memory as you discover codepaths, patterns, and key architectural decisions. Consult your memory before starting work." This enables cross-session learning.

Keep under 3,000 words. Detailed domain reference belongs in references/ preloaded via the skills: frontmatter field, not embedded directly in the system prompt.

See ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/examples/proactive-code-reviewer.md for a complete working example demonstrating the proactive trigger pattern.

Step 5 — Script opportunity scan

Read ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/script-patterns.md and apply the five signal patterns to every step in the agent's system prompt:

SignalQuestionIf yes →
Repeated GenerationDoes any step produce the same structure across invocations?Parameterized script in scripts/
Unclear Tool ChoiceDoes any step combine tools in a fragile sequence?Script the procedure
Rigid ContractCan you write --help text for this step right now?CLI candidate
Dual-Use PotentialWould a user run this step from the terminal independently?Design as proper CLI
Consistency CriticalMust this step produce identical output for identical inputs?Script — never LLM generation

Step 6 — Check delegation

Scan existing agents and skills before finalizing:

Glob: .claude/agents/*.md, ~/.claude/agents/*.md (project + global agents)
Glob: .claude/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md (project + global skills)
  • Does an existing agent cover this domain? Extend it, or tighten scope of the new one
  • Are there skills or reference files to preload via skills: frontmatter for domain knowledge?
  • Are there commands or MCPs this agent should delegate sub-tasks to?

Always use fully qualified names:

  • Agent: subagent_type=plugin-dev:agent-creator (not just "agent-creator")
  • Skill: claude-skills:create-skill (not just "create-skill")

Step 7 — Validate

When creating a new agent file:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py <agent-file> --output json

Exit 0 = proceed to Phase 2. Exit 1 = parse the errors array; each entry has field, message, severity. Resolve all critical and major items before writing to disk.

Phase 2: Deliver

Output Paths

ScopeLocation
User agent (global)~/.claude/agents/<name>.md
Project agent.claude/agents/<name>.md
Plugin agent<plugin-root>/agents/<name>.md

Agents in agents/ are auto-discovered — no registration needed. Plugin agents are namespaced automatically as plugin-name:agent-name.

Initialize agent file (optional scaffold)

When creating from scratch:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/init_agent.py <name> --path <agents-dir>

Exit 0 = file created with placeholders, proceed to fill content. Exit 1 = naming collision; ask user to rename or confirm overwrite.

Explain Your Choices

Present the generated agent with brief rationale:

  • What you set and why — "Set model: sonnet because this agent performs complex multi-file reasoning"
  • What you excluded and why — "Left isolation unset; no git state management needed"
  • Tools selected and why — explicitly justify each tool; undefended tool access is a design smell

Write and Confirm

Before writing:

Writing to: [path]
This will [create new / overwrite existing] file.
Proceed?

After Creation

Summarize:

  • Name and file path
  • When it triggers (key trigger conditions)
  • Tools granted and why
  • Suggested test scenario

Proceed to Phase 3.

Phase 3: Evaluate

DimensionCriteria
Clarity (0-10)System prompt unambiguous, objective and persona clear
Trigger Precision (0-10)Description + examples cover intended trigger space, not broader
Efficiency (0-10)System prompt token economy — maximum guidance per token
Completeness (0-10)Covers domain requirements; output format defined; edge cases addressed
Safety (0-10)Tools restricted to minimum needed; no runaway permission grants

Target: 9.0/10.0. If below, refine once addressing the weakest dimension, then deliver.

Phase 3 is complete when score ≥ 9.0 or one refinement pass has run. Deliver: agent file path, key trigger conditions, tools granted and why.

Validation Checklist

Structure:

  • File is <name>.md in an agents/ directory
  • Valid YAML frontmatter with name and description
  • Markdown body is present and substantial

Description Quality:

  • Starts with "Use this agent when..."
  • Concise > scalar, 50-70 tokens, no <example> blocks
  • Covers scope boundaries (what it's NOT for)
  • Proactive hint included if agent should fire after events

System Prompt Quality:

  • Written in second person ("You are...", "You will...")
  • Has clear persona/role statement as first sentence
  • Process steps are numbered and imperative
  • Output format is defined
  • Edge cases addressed
  • Under 3,000 words; domain detail offloaded to references/

Frontmatter:

  • model: inherit unless specific model needed
  • color set and semantically meaningful
  • tools restricted to minimum needed
  • memory set if cross-session learning identified, with maintenance instructions in body
  • effort set if non-default thinking depth needed
  • initialPrompt set if session-mode agent that self-starts
  • background: true set if concurrent execution identified
  • isolation: worktree set if agent modifies files that need review before merging
  • No TODO placeholders remaining

Error Handling

IssueAction
Unclear domainAsk: what does success look like for this agent?
Scope too broadSplit into 2–3 focused agents with non-overlapping trigger conditions
Conflicts with existing agentNote overlap; narrow triggering scope or extend the existing one
Vague trigger conditionsAsk for 3 concrete user messages that should activate this agent

Create CLI

Design CLI surface area (syntax + behavior), agent-aware, human-friendly.

Phase 1 — Prepare

Read ${CLAUDE_PLUGIN_ROOT}/skills/create-cli/references/cli-guidelines.md. Apply it as the default CLI rubric, including the Agent Ergonomics section.

For new CLI designs, also read ${CLAUDE_PLUGIN_ROOT}/skills/create-cli/references/language-selection.md to inform the language recommendation in Phase 2. Skip it for audits — the language is already chosen.

Proceed when cli-guidelines.md is loaded.

Phase 2 — Clarify

Determine whether this is a new design or an audit from the user's trigger.

New design

Ask, then proceed with best-guess defaults if user is unsure:

  • Command name + one-sentence purpose.
  • Primary consumer: agent/LLM, human at a terminal, scripted automation, or mixed.
  • Input sources: args vs stdin; files vs URLs; secrets (never via flags).
  • Output contract: human text by default, --json for structured output, exit codes.
  • Backend/data layer: does it wrap an existing API? Source of the surface — OpenAPI/docs, live URL, or HAR capture (undocumented/browser-fed)? (cli-guidelines.md → Wrapping an existing API.)
  • Interactivity: prompts allowed? need --no-input? confirmations for destructive ops?
  • Config model: flags/env/config-file; precedence; XDG vs repo-local.
  • Language & distribution: ask for the user's preferred implementation language, or offer to recommend one. Ask whether a single binary (no runtime needed on target machine) is required, or whether a runtime dependency is acceptable. Apply language-selection.md to recommend if the user is unsure. Platform: macOS/Linux/Windows.

If an existing CLI spec or tool description is provided, read it first — skip questions already answered by it.

Data Layer gate — required when the tool reads from a backend. Run the Data Layer Decision scorecard (cli-guidelines.md → Stateful CLIs); record adopt cache or stateless + a one-line rationale. Decide this before drawing the command tree — it changes whether sync/local-read subcommands exist at all.

Audit

Ask:

  • CLI name and source location (repo path, or provide --help output).
  • Primary consumer: agent, human, or mixed.
  • Known pain points or specific areas to focus on.

Then explore the codebase: use Glob/Grep to find command definitions, flag registrations, output formatting, and error handling. Run <cli> --help via Bash to capture actual behavior.

Proceed when answers are confirmed or user is unsure — use best-guess defaults.

Phase 3 — Conventions

Apply the conventions from cli-guidelines.md (loaded in Phase 1), including the Agent Ergonomics section. The rules below are the key conventions to enforce — cli-guidelines.md provides the full rubric for edge cases.

If primary consumer is human-only, the Errors and Reduce Tool Calls subsections are optional — apply them only if the user wants script-friendliness.

Output

  • Default output is human-readable text; an explicit --json/--plain flag sets the data format and overrides TTY state. Cosmetics (color, spinners) may TTY-detect; the data format must not rely on it (see cli-guidelines.md → Agent Ergonomics for the TTY/PTY rationale).
  • List commands in --json mode use NDJSON (one JSON object per line) — enables streaming and jq piping without buffering. For paginated results with metadata, a JSON object with an items array is acceptable. If the CLI extends an existing ecosystem that uses JSON arrays (kubectl, aws, gh), match the ecosystem convention.
  • Primary data to stdout; diagnostics/errors to stderr.
  • Suppress ANSI codes, progress spinners, and decorative output when --json is passed or when stdout is not a TTY.

Errors (agent/mixed consumers only)

  • When --json is active, emit error objects on stderr: {"error": "<snake_case_code>", "message": "...", "hint": "<exact CLI invocation or null>"} — so agent callers can route recovery logic without parsing free-text stderr. The hint field must be an executable command, not prose.
  • Exit codes: 0 success, 1 runtime error, 2 invalid usage; for agent/mixed consumers, extend with the typed table from cli-guidelines.md → Exit codes (typed) (3 not-found, 4 auth, 5 upstream, 7 conflict) — apply identically across all subcommands so agents branch on the code.

Flags

  • -h/--help always shows help; ignores other args.
  • --version prints version to stdout.
  • --json preferred for structured output. --output json/-o json acceptable when the CLI needs multiple output formats (yaml, table, csv) under a single flag. Pick one and apply consistently.
  • For commands an agent calls in a loop, offer --compact (opt-in): same JSON shape, minimal whitespace, essential fields only — --json stays the full-fidelity default. See cli-guidelines.md → Output defaults.
  • Consistent flag names across all subcommands for the same concept (--id, --force, --json) — agents learn the naming pattern once and apply it everywhere without guessing.
  • Prompts only when stdin is a TTY; --no-input disables prompts. --non-interactive acceptable if the ecosystem already uses it.
  • Destructive operations: interactive confirmation; non-interactive requires --force.
  • Respect NO_COLOR, TERM=dumb; provide --no-color.
  • Handle Ctrl-C: exit fast; bounded cleanup; crash-only when possible.

Reduce Tool Calls (agent/mixed consumers only)

  • Compound output: operations return enough data to avoid a follow-up call. create returns the new resource's ID and key fields. delete echoes what was removed.
  • Rich JSON defaults: in --json mode, return full objects not just IDs.
  • Bounded lists: list commands default to a safe limit (e.g., 50 items) with --limit to adjust. In JSON mode, include has_more (bool) and optionally next_cursor for keyset pagination. Unbounded output wastes tokens and risks context overflow for agent callers.
  • Idempotent by default: where possible, commands are safe to repeat; document preconditions explicitly — agents rely on safe retries for error recovery without human intervention.

Apply all applicable conventions, then proceed to Phase 4.

Phase 4 — Deliver

Audits

Evaluate the existing CLI against every Phase 3 subsection. For each convention, state: what the CLI does today, whether it conforms, and what to change. Also check:

  • Flag naming consistency across subcommands.
  • Help text quality (examples present, common flags first, fits one screen).
  • Config precedence (flags > env > project config > user config > defaults).
  • Destructive-op safety (confirmations, --force, --dry-run).
  • Shell completion availability.
  • Data layer fit: if the CLI reads from a backend, run the Data Layer Decision scorecard; flag when it re-fetches live data that a local cache + compound queries would serve (cli-guidelines.md → Stateful CLIs).

Produce a gap report organized by severity: Breaking (requires API change), Major (agent-breaking or convention violation), Minor (cosmetic/polish). Each finding: current behavior, convention violated, recommended fix with migration risk (none/low/breaking).

New designs

Produce a compact spec the user can implement. Include all relevant sections:

  • Command tree + USAGE synopsis.
  • Args/flags table (types, defaults, required/optional, examples).
  • Subcommand semantics (what each does; idempotence; state changes).
  • Output rules: stdout vs stderr; --json for structured output; --quiet/--verbose.
  • Error + exit code map (top failure modes).
  • Safety rules: --dry-run, confirmations, --force, --no-input.
  • Config/env rules + precedence (flags > env > project config > user config > system).
  • Data layer decision: adopt cache | stateless verdict + rationale (required when the tool reads from a backend).
  • API provenance (when wrapping an existing API): source + endpoint→command mapping; for HAR, the secret/auth/coverage/fragility/ToS checks.
  • Shell completion story (if relevant): install/discoverability; generation command or bundled scripts.
  • 5–10 example invocations (common flows; include piped/stdin examples).

Use this skeleton, dropping irrelevant sections:

  1. Language & distribution: Go · cobra · single binary · goreleaser for CI (Omit if language was not determined.)
  2. Name: mycmd
  3. One-liner: ...
  4. USAGE:
    • mycmd [global flags] <subcommand> [args]
  5. Subcommands:
    • mycmd init ...
    • mycmd run ...
  6. Global flags:
    • -h, --help
    • --version
    • -q, --quiet / -v, --verbose (define exactly)
    • --json (structured JSON output; NDJSON for list commands)
  7. I/O contract:
    • stdout:
    • stderr:
  8. Exit codes:
    • 0 success
    • 1 generic failure
    • 2 invalid usage (parse/validation)
    • (add command-specific codes only when actually useful)
  9. Env/config:
    • env vars:
    • config file path + precedence:
  10. Data Layer Decision (required when the tool reads from a backend; omit if no backend): adopt cache | stateless + one-line rationale. If adopt: sync command, local schema sketch, local-vs-live reads, write invalidation note.
  11. API Provenance (only when wrapping an existing API; omit for from-scratch tools): source (OpenAPI/URL/HAR); subcommand ← method+path mapping; for HAR, the five checks.
  12. Examples:
  • …

See ${CLAUDE_PLUGIN_ROOT}/skills/create-cli/examples/example-cli-spec.md for a complete worked example.

If the spec is destined for a skill body or CLAUDE.md, omit unused sections entirely (do not mark them "N/A") and limit examples to ≤5 invocations that each demonstrate multiple patterns.

Phase 5 — Verify

For new specs: confirm the spec covers all applicable sections from the Phase 4 skeleton. Verify the examples section demonstrates at least: --json output, error recovery (if agent/mixed consumer), and one piped/stdin usage.

For backend/API-wrapping specs: confirm a Data Layer Decision verdict is recorded with a rationale (not left implicit), and — when the source is a HAR/undocumented API — that no secret values appear anywhere in the spec (only env-var names) and the coverage/fragility caveats are stated.

For audits: confirm the gap report addresses every Phase 3 subsection and includes at least one example invocation showing the recommended fix for each Major finding.

Skill is complete when verification passes.

Notes

  • Once language is selected (Phase 2), include the idiomatic parsing library in the spec (see language-selection.md). If language remains undetermined, omit the library.
  • If the request is "design parameters", do not drift into implementation.

Skill & Command Generator

Generate well-structured skills or slash commands. Both are markdown files with YAML frontmatter—they share the same structure but differ in how they're triggered and described.

Phase 0: Understand Requirements

Parse $ARGUMENTS for type hint. If $ARGUMENTS is empty or insufficient, use AskUserQuestion to gather requirements — users are often unclear on what type of artifact they need or what the best design is.

Use AskUserQuestion to collect:

  1. Primary objective — What should this do?
  2. Trigger scenarios — When should it activate?
  3. Inputs/outputs — What does it receive and produce?
  4. Complexity — Simple, standard, or complex?
  5. Execution needs — Isolated context? Delegated to specialized agent? Proceed to Phase 1 when at minimum Objective and Trigger Scenarios are established. Remaining dimensions can be resolved during generation.

Phase 1: Generate

Apply these principles throughout generation: use imperative voice and terse phrasing because every token in a generated skill body costs budget on every invocation, and Claude extrapolates well from precise nudges. Prefer instruction over example — state the rule with its reasoning so it generalizes to every input.

If creating a new skill directory (not editing an existing file):

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/init_skill.py <name> --path <dir> [--resources scripts,references,assets] [--examples]

Exit 0 = directory created, proceed to Step 1. Exit 1 = naming collision; ask user whether to overwrite or rename.

Step 1 — Choose type

  • Skills: Trigger-rich, third-person description ("This skill should be used when..."); auto-triggered by routing
  • Commands: Concise, verb-first description, under 60 chars; user-invoked via / menu

Step 2 — Write frontmatter

Read ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/frontmatter-options.md for the full field catalog, description patterns, tool selection framework, and execution modifiers.

Description density rules: Keep descriptions under 150 tokens (200 absolute max) — they load every session. Descriptions over 250 characters are truncated in the skill listing. Derive trigger phrases from the user's actual words in Phase 0, not paraphrases. See the token budget, pushy routing pattern, and trigger derivation principles in frontmatter-options.md.

Intensional over extensional — apply to all generated content. State the rule directly with its reasoning rather than listing examples that imply the rule. An intensional rule ("quoted phrases must be verbatim user speech because routing matches on literal tokens") generalizes to every input the skill will encounter. An extensional approach requires the reader to reverse-engineer the rule — two reasoning hops instead of one, covering only the shape of those specific examples. Since this skill generates instructions that will themselves guide further generation, the quality of reasoning propagates.

Step 3 — Validate description discoverability

Before writing the body, verify the description will route correctly. Mentally generate:

  1. 3 should-trigger prompts — realistic user messages that should activate this skill. Include at least one naive phrasing from a user who has never heard of the skill.
  2. 3 should-NOT-trigger prompts — messages in adjacent domains that are close but should not activate. These test whether the description is too broad.

Evaluate: does the description cover all should-trigger prompts? Would it plausibly reject the should-NOT-trigger prompts? If coverage is weak, revise the description — add missing trigger phrases, tighten language to exclude adjacent domains, or add a negative trigger ("Not for X").

This step catches routing misses before the rest of the skill is built. Proceed when description coverage is adequate.

Step 4 — Write body

Construction rules:

  • State objective explicitly in first sentence
  • Use imperative voice ("Analyze", "Generate", "Identify") — no first-person ("I will", "I am")
  • Context only when necessary for understanding
  • XML tags only for complex structured data
  • No "When to Use This Skill" section — body loads only after triggering; routing guidance there is never read by the routing decision
  • Avoid headers deeper than H3 — deep nesting signals content that belongs in references/, not SKILL.md
  • Use bang-backtick syntax for dynamic context injection when real-time data (git status, file list, env vars) improves the skill without requiring a tool call
  • Preserve variable bindings when collapsing code blocks to prose. Code blocks serve two purposes: illustrating an operation and establishing workflow state. When a code block assigns variables (BASE=..., BRANCH=...) that later steps reference, collapsing it to prose without preserving the bindings leaves downstream $VAR references unbound. Add a "derive working variables" preamble that explicitly binds each variable in prose before the steps that use them

Both skills and commands follow the same body pattern:

# Name

Brief overview (1-2 sentences).

## Process
1. Step one (imperative voice)
2. Step two
3. Step three

Dynamic Content:

SyntaxPurpose
$ARGUMENTSAll arguments as string
$1, $2, $3Positional arguments (shell-style quoting for multi-word values)
@path/fileLoad file contents
@$1Load file from argument
Exclamation + backticksExecute bash command, include output
${CLAUDE_SKILL_DIR}Path to the skill's own directory (use for referencing bundled scripts/files)
${CLAUDE_SESSION_ID}Current session ID (useful for logging or session-specific output files)

Example — injecting live context. In a skill body, write lines like:

  • Current branch: !`git branch --show-current`
  • Recent commits: !`git log --oneline -5`
  • Changed files: !`git diff --name-only`

Then add directives like "Summarize this pull request..."

These commands run when the skill is invoked. The model sees only the output — no tool calls needed. Use this for infallible probes (git status, env vars, file trees, process output) where failure is rare and the output is informational. Do not use for commands that may fail or need exit-code branching — those require Bash tool calls so the model can handle errors.

Note: The backslashes above escape the backticks so this documentation doesn't execute — in a real skill, write !`cmd` without the backslashes.

Step 5 — Script opportunity scan

Read ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md and apply the five signal patterns to every workflow step in the skill being generated:

SignalQuestionIf yes →
Repeated GenerationDoes any step produce the same structure with different params across invocations?Parameterized script in scripts/
Unclear Tool ChoiceDoes any step combine multiple tools in a fragile sequence naturally expressible as one function?Script the procedure
Rigid ContractCan you write --help text for this step right now without ambiguity?CLI candidate — delegate design to create-cli
Dual-Use PotentialWould a user want to run this step from the terminal, outside the skill workflow?Design as proper CLI from the start
Consistency CriticalMust this step produce bit-for-bit identical output for identical inputs?Script — never LLM generation

For each identified script candidate:

  1. Choose the archetype from references/script-patterns.md (init/validate/transform/package/query)
  2. If the interface is non-trivial, delegate to claude-skills:create-cli skill to design it
  3. Scaffold the script in scripts/ using the Python template from references/script-patterns.md
  4. Wire it into SKILL.md with: trigger condition, exact invocation, output interpretation

Wiring rule: A script reference must state when to invoke (trigger condition), how to invoke (exact command with flags), and what to do with the result (exit code handling, which output fields matter).

Step 6 — Check delegation

Scan for existing resources before finalizing:

Review available: skills, commands, agents, MCPs
For each workflow step, ask: "Do we already have this?"

Common delegation patterns:

  • Git commits → Skill: claude-coding:commit

Always use fully qualified names:

  • Skill: plugin-dev:hook-development (not just "hook-development")
  • SlashCommand: /plugin-dev:create-plugin (not just "create-plugin")
  • Task: subagent_type=plugin-dev:agent-creator

Step 7 — Validate

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/validate_skill.py <skill-directory> --output json

Exit 0 = proceed to Phase 2. Exit 1 = parse the errors array; each entry has field, message, severity. Resolve all critical and major items before writing to disk.

Phase 2: Deliver

Output Paths

TypeLocation
User skill~/.claude/skills/<name>/SKILL.md
User command~/.claude/commands/<name>.md
Project skill.claude/skills/<name>/SKILL.md
Project command.claude/commands/<name>.md

Write and Confirm

Before writing:

Writing to: [path]
This will [create new / overwrite existing] file.
Proceed?

Explain Your Choices

When presenting the generated skill/command to the user, briefly explain:

  • What you set and why — "Added allowed-tools to scope Bash to git commands only, since the skill only needs git for commits"
  • What you excluded and why — "hooks omitted (no validation needed), disable-model-invocation left unset (auto-triggering is appropriate)"
  • Add more trigger phrases if routing misses expected inputs

Package for Distribution

Only when user explicitly requests a distributable file, run:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/package_skill.py <skill-directory> [output-dir]

Exit 0 = .skill file created at output path. Exit 1 = validation failed; read stdout for details.

After Creation

Summarize what was created:

  • Name and type
  • Path
  • How to invoke/trigger
  • Suggested test scenario

Phase 3: Structural Lint

After writing the skill to disk, invoke the skill-lint agent to run a structural audit:

Use Task tool with subagent_type=claude-skills:skill-lint:
"Lint the skill at <path-to-skill-directory>. Auto-apply critical and major fixes, report
minor findings for user decision."

Wait for the agent to complete. If it auto-applied fixes, note them in the Phase 4 summary. If it reports minor findings, include them in the evaluation output for the user to decide.

Proceed to Phase 4 when the lint agent returns.

Phase 4: Evaluate

Score the generated skill/command:

DimensionCriteria
Clarity (0-10)Instructions unambiguous, objective clear
Precision (0-10)Appropriate specificity without over-constraint
Efficiency (0-10)Token economy—maximum value per token
Completeness (0-10)Covers requirements without gaps or excess
Usability (0-10)Practical, actionable, appropriate for target use

Target: 9.0/10.0. If below, refine once addressing the weakest dimension, then deliver.

Before finalizing, load ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/generation-standards.md and verify the validation checklist passes.


Execute phases sequentially.

Skill Improver

Increase the effectiveness of an existing skill by modeling user intent, testing the skill against that intent through mental simulation and live doc validation, and proposing ranked improvements — new features, UX gains, accuracy fixes, efficiency wins.

This skill is about whether the skill accomplishes what users need. Structural correctness (malformed frontmatter, missing fields, violated conventions) is repair-skill's domain — if obvious structural issues are present, note them briefly, recommend repair-skill, and continue with effectiveness analysis.

Phase 0: Load the Skill

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

  • If a directory: read SKILL.md, then note which of references/, scripts/, examples/, assets/ exist
  • If a file: read it directly, then discover sibling resource directories

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

Note any obvious structural issues in one sentence ("this description is first-person — recommend repair-skill for structural fixes") and move on. Do not run a full structural audit.

Phase 0 is complete when SKILL.md is loaded and the sibling directory inventory is noted.

Phase 1: Understand User Intent

Before analyzing, establish what the user wants. Use AskUserQuestion:

  • "What specifically does this skill not do well?"
  • Offer options: a specific gap they've noticed, "I'm not sure — run a full effectiveness audit", "it works but I want new capabilities", "the workflow feels clunky"

Regardless of the answer, also infer the skill's purpose from its description and body. State your understanding of what problem it solves and for whom — one sentence — before proceeding. This grounds the entire analysis in the correct frame.

If the user named a specific complaint: orient the analysis toward that area and scan for related issues in the same workflow region. If the user is unsure: run the full Phase 2 audit across all five sub-analyses.

Phase 1 is complete when user intent is established and the skill's purpose is stated.

Phase 2: Effectiveness Analysis

Load ${CLAUDE_PLUGIN_ROOT}/skills/improve-skill/references/effectiveness-rubric.md before starting. It contains the severity framework, improvement type definitions, and effort/impact calibration criteria used in Phase 3.

Run all five sub-analyses. For each finding record: what the issue is, why it reduces effectiveness for the user, and the concrete improvement.


2a — Mental Simulation

Walk through the skill as Claude executing it with a concrete representative user request. Choose an input that exercises the main workflow path — not an edge case, but the typical use.

For each phase of the skill, evaluate:

  • Missing info: What does this step need that hasn't been provided or gathered yet? If the user hasn't specified something and the skill doesn't ask, what does Claude have to guess?
  • Divergence points: Where would two different Claude instances execute this instruction and arrive at meaningfully different outputs? These are underspecified steps.
  • Dead ends: Where does the skill's workflow stop but the user's actual goal isn't yet accomplished? What does the user have to do manually after the skill finishes?
  • Friction: Where does the skill pause the user at a low-value decision point (Claude could make a good default), or skip user input at a high-value moment (user has a strong preference)?

Document findings by type: stuck points, divergence points, dead ends, friction points.


2b — Live Doc Validation

Identify all factual claims in the skill that reference external standards: frontmatter field names, Claude tool names and behavior, API parameters, CLI flags, third-party service interfaces.

For each claim, verify against current documentation:

For Claude-specific claims (frontmatter options, tool names, model IDs):
  Use Task tool with subagent_type=claude-code-guide — faster and more accurate than WebSearch.

For third-party claims (npm packages, APIs, external CLIs):
  Use WebSearch or WebFetch against official documentation.

Flag drift between what the skill states and current reality. Severity: high if the claim produces broken output; medium if it produces outdated guidance; low if it's a naming change with no behavioral difference.


2c — Feature Adjacency Scan

Given the skill's purpose, identify capabilities that are absent but would be high-value:

  • Adjacent: Naturally extends what the skill already does — same domain, one step further. The user who just ran this skill would almost certainly want this next.
  • Complementary: Commonly needed right before or after this skill. The user does this manually today.
  • End-to-end gap: The skill starts a job the user finishes by hand — workflow stops at "here's a plan" when the user wanted "and apply it."

For each candidate: estimate implementation effort (one instruction change, new phase, or new script) and user value (rare edge case, common scenario, or blocks the skill in a key scenario).


2d — UX Flow Review

Evaluate the skill's interaction design:

  • Does the skill surface all necessary questions at the start (before heavy work), or does it interrupt mid-workflow with requests the user didn't anticipate?
  • Is the "I don't know" path explicit? If a user triggers the skill without a specific complaint, does the skill handle that gracefully, or does it assume the user knows?
  • Does the output format match how users consume it? A report users read once can be dense prose; one they apply iteratively needs more structure.
  • Are there steps where the skill makes a consequential decision without user input?

2e — Edge Case Stress Test

After walking the main path (2a), deliberately try to break the skill. Identify 3–5 adversarial inputs that test failure modes:

  • Missing or malformed input: What happens when expected files don't exist, paths are wrong, or arguments are empty/garbled?
  • Contradictory requirements: What if the user's stated goal conflicts with their input (e.g., "improve this skill" on a file that isn't a skill)?
  • Unsupported configurations: What if the skill encounters a structure it wasn't designed for — a different framework version, an edge-case project layout, an unexpected file format?
  • Boundary conditions: What if the input is very large (500-line SKILL.md), very small (empty file), or has unusual characters in paths/names?

For each adversarial input, evaluate: does the skill detect the problem and surface a useful error, silently produce wrong output, or crash the workflow? Map findings to improvement types: missing error handling → NEW FEATURE, poor failure message → UX IMPROVEMENT, undetected bad state → ACCURACY FIX.

Phase 2 is complete when all five sub-analyses are finished and findings are recorded.

Phase 3: Improvement Proposal

Load ${CLAUDE_PLUGIN_ROOT}/skills/improve-skill/references/effectiveness-report-template.md for the output format before constructing the report. Reference ${CLAUDE_PLUGIN_ROOT}/skills/improve-skill/examples/sample-analysis.md to calibrate depth and specificity if needed.

Present findings grouped by improvement type — users think in terms of outcomes, not audit dimensions. Each entry must include: the sub-analysis code in brackets, what the gap is, why it matters to the user, and the specific fix. Calibrate severity using the criteria in references/effectiveness-rubric.md.

Ask: "Apply all improvements? Or select specific ones?"

Phase 3 is complete when the report is delivered and user selection is confirmed.

Phase 4: Apply Improvements

Apply confirmed items in order: new features → accuracy fixes → UX improvements → efficiency gains.

For each item:

  • State what is being changed and why — reference the effectiveness principle, not "you asked"
  • Make the edit or create the file
  • Confirm the change integrates cleanly with surrounding content

After applying, briefly explain:

  • What was changed and why
  • What was added and why
  • What was left out and why (effort outweighs benefit, or requires domain knowledge the user must supply)
  • What was not selected — note it remains available to apply later

Validation: After delivering the explanation, re-read the modified SKILL.md in full and confirm: all selected improvements are present, no surrounding content was inadvertently altered, phases are still numbered with exit conditions, and all references point to files that exist.

Phase 4 is complete when all confirmed items are applied, the explanation is delivered, and the validation pass finds no integration failures.

Phase 5: Structural Lint

After applying effectiveness improvements, invoke the skill-lint agent for a structural quality pass:

Use Task tool with subagent_type=claude-skills:skill-lint:
"Lint the skill at <path-to-skill-directory>. Auto-apply critical and major fixes, report
minor findings for user decision."

Wait for the agent to complete. If it auto-applied structural fixes, note them alongside the effectiveness changes from Phase 4. If it reports minor findings, present them to the user.

Phase 5 is complete when the lint agent returns and any user-selected minor fixes are applied.

Agent Repair

Audit and improve an existing Claude Code agent against a gold standard. Unlike create-agent (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 of agent design.

Phase 1: Load the Agent

The agent file at $ARGUMENTS is loaded inline:

@$ARGUMENTS

Note the directory from $ARGUMENTS to verify it lives in agents/ (not skills/). Identify any skills: preloads listed in the frontmatter above.

If the file is a SKILL.md or lives in a skills/ directory, decline and tell the user to use repair-skill instead. If the path is missing or ambiguous, use AskUserQuestion to resolve before proceeding.

Load the following reference files before Phase 2:

  1. ${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/agent-anatomy.md — gold standard for system prompt structure, voice conventions, size invariants, naming, skills: preload pattern, and the gap analysis checklist. Required for Dimensions 3, 5, 6, and 7.
  2. ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md — complete frontmatter field catalog, valid values, tool selection framework, color semantics, and execution modifiers. Required for Dimensions 1 and 2.

Proceed to Phase 2 when: agent file is confirmed in scope and 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 agent against the gold standard
  • Improvement — something that works but could be meaningfully tightened

Severity:

  • critical — breaks triggering or causes the agent to malfunction on every invocation
  • major — degrades trigger accuracy, system prompt reliability, or autonomy safety
  • minor — polish; the agent works but isn't as good as it could be

Dimension 1 — Description Quality

The description is read by the routing model to decide when to spawn this agent. It is the primary trigger mechanism and is always in context. Audit for violations and gaps.

Violations:

  • Framing: Does it start with "Use this agent when..."? Critical if wrong.
  • Bloated description: Description should be a concise > folded scalar, 50-70 tokens. No <example> blocks — they waste context without improving routing. Major if examples present or description exceeds ~80 tokens.
  • Scalar type: Should use > (folded). Minor if using | without XML blocks.
  • Proactive hint missing: For agents that fire after events, does the description include "Recommended PROACTIVELY after..."? Minor if proactive intent without the hint.

Gaps:

  • Negative trigger: If adjacent agents exist with overlapping scope, does the description state when NOT to trigger? Minor if adjacent agent exists without disambiguation.

Dimension 2 — Frontmatter Modifiers

Refer to agent-frontmatter.md for the complete field catalog, tool selection framework, and color semantics. Omitting a field is not an error when the default applies — audit for mismatches (violations) and missing configuration that would improve the agent (gaps).

Violations:

  • Does tools include unscoped Bash for an agent that doesn't need full shell access? Agents run autonomously with no human in the loop — unrestricted Bash is the highest blast-radius grant. Major.
  • Is model: opus set for a task sonnet handles? Cost scales directly per spawn. Major.
  • Is isolation: worktree set without the agent performing git-state modifications? Unnecessary isolation adds overhead. Minor.
  • Does disallowedTools block a tool the system prompt requires? Critical.

Gaps:

  • Is color absent? Visual identity in the UI helps users track which agent is active in multi-agent workflows. Minor.
  • Is tools absent for a read-only analysis agent? Least-privilege requires an explicit allowlist for autonomous agents — omitting it grants full access when restricted access would suffice. Major for analysis-only agents.
  • Is maxTurns absent for a task with a predictable completion horizon? Unbounded agents can loop on ambiguous input. Minor for bounded tasks.
  • Is skills absent for an agent with domain-specific knowledge needs? Embedding domain reference directly in the system prompt inflates every spawn; skills: defers it. Major if system prompt exceeds 300 lines of embedded reference data.
  • Is isolation: worktree absent for an agent that modifies files in the working tree? Without isolation, modifications are immediate and irreversible during the run. Major.
  • Is memory absent for an agent that would benefit from cross-session learning? Agents that review code, audit patterns, or accumulate project knowledge should use persistent memory (project recommended default). If memory is set, does the system prompt include memory maintenance instructions? Without them, the agent won't proactively update its knowledge base. Major if the agent's domain involves pattern accumulation.
  • Is effort absent for a cost-sensitive or complexity-varying agent? Fast classification tasks benefit from effort: low; deep reasoning tasks from effort: high. Minor.
  • Is initialPrompt absent for a session-mode agent designed for --agent use? Without it, the agent waits for user input instead of self-starting. Minor if applicable.

Dimension 3 — System Prompt Voice

The markdown body of an agent file is its system prompt. Voice, persona, and structural conventions determine whether the agent behaves as a specialist or a generic assistant. Refer to agent-anatomy.md for voice conventions and the gold standard structure.

Violations:

  • First-person language: Does the body contain "I will", "I'll", "I am", or any first-person construction? Critical — the system prompt is an address to the agent; first-person reads as the agent narrating its own plan rather than following an instruction. Both second-person ("You will analyze...") and bare imperatives in process steps ("Analyze...") are correct conventions — only first-person breaks the contract.
  • Third-person self-description: Does the body refer to the agent in third person ("This agent will analyze...", "The agent should...")? Major — the body must address the agent directly, not describe it from the outside.
  • No persona statement: Does the first sentence establish role and domain? Without one, the agent has no expert identity to shape downstream decisions. Major.
  • No numbered process steps: Unstructured prose instructions produce variable behavior across invocations. Major if unstructured.
  • No output format: Is there an Output Format section? Callers — human or orchestrating skill — need predictable structure to consume results. Major if absent.

Gaps:

  • No edge cases: Predefined handling prevents mid-task failures that cost retries. Common cases: no input provided, ambiguous input, target missing, empty result. Minor.
  • Judgment steps without criteria: Steps like "analyze the situation" or "assess quality" without explicit criteria for what to consider and what constitutes a good outcome. Major per uncovered judgment step.

Dimension 4 — Agentic vs Deterministic Split

Load ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md before auditing this dimension. The same five signal patterns apply to agents as to skills.

Agents mix LLM-guided reasoning (agentic) and deterministic operations. The split should be deliberate — see the Degrees of Freedom table in agent-anatomy.md.

Violations:

  • Inlined deterministic code: Code blocks that would be re-generated identically across invocations belong in scripts/, not in the system prompt. Major.
  • Vague script references: "Run the validation script if needed" — no path, no trigger condition, no output interpretation. Minor.

Gaps — apply the five signal patterns to each process step:

  • Signal 1 (Repeated Generation): Same structure, different parameters → script. Major.
  • Signal 2 (Unclear Tool Choice): Fragile multi-tool sequence → script the procedure. Major.
  • Signal 3 (Rigid Contract): Can write --help for this step → CLI candidate. Minor.
  • Signal 4 (Dual-Use): Useful outside the agent → design as proper CLI. Minor.
  • Signal 5 (Consistency Critical): Must produce identical output → script, not LLM. Major.

Dimension 5 — System Prompt Efficiency

Every line in the agent body is loaded into context every time the agent is spawned. Domain reference data and lookup tables belong in skills: preloads, not embedded inline. Refer to size invariants in agent-anatomy.md to calibrate severity.

Violations:

  • Hedging language: "You might want to consider", "generally speaking", "you could try". Replace with direct imperatives. Minor per instance.
  • Routing guidance in body: Any section explaining when to trigger the agent belongs in the description field. The body loads only after triggering — routing guidance there never informs the triggering decision and burns context on every spawn. Major.
  • Embedded domain reference > 100 lines: Lookup tables, option catalogs, field definitions only needed for specific steps inflate every invocation. Use skills: preload instead. Major.
  • System prompt over ~400 lines: Signals embedded content that belongs in skills: preloads. Major.

Gaps:

  • Could skills: reduce system prompt size? Identify sections only needed for specific sub-tasks. Major if system prompt > 300 lines with extractable content.

Dimension 6 — Process Completeness

A complete agent process is sequential, has explicit steps, and defines what "done" looks like at each step. Audit for broken workflow and for missing structure that would help.

Violations:

  • No numbered steps: Prose description of process without step numbers — the agent cannot track progress or know which step it's in. Major.
  • Steps without exit conditions: Multi-step processes need explicit completion criteria per step. Without them, the agent may loop or skip prematurely. Major if missing.
  • Half-thought steps: Phases that describe intent without specifying action or evaluation criteria. Major per uncovered step.
  • No input handling: What does the agent do if input is missing, ambiguous, or malformed? Minor if unaddressed.

Gaps:

  • No output format section: Callers cannot reliably consume implicit output structure. Major if agent returns structured data.
  • No validation checklist: A self-check at the end of the process catches errors that prose instructions miss. Minor.

Dimension 7 — Anatomy Completeness

Agents are typically single files, but their ecosystem includes skills: preloads and optional companion scripts. This dimension asks whether declared structure matches needs.

Refer to the Gap Analysis Checklist in agent-anatomy.md for each absent element.

Violations:

  • skills: listed in frontmatter but not referenced in process: Dead preloads inflate context on every spawn without being used. Minor.
  • Naming violates conventions: Generic terms (helper, assistant, agent), underscores, over 50 characters, leading/trailing hyphens. Minor.

Gaps:

  • No skills: preload for domain-heavy agents: System prompt embeds a large reference catalog that could be externalized. Major if body > 300 lines.
  • No companion scripts for consistency-critical steps: Process describes steps that must produce identical output for identical inputs. Major.
  • color absent: No visual identity in multi-agent UI contexts. Minor.
  • No memory for pattern-accumulating agents: Agent reviews code, audits quality, or accumulates project knowledge but has no persistent memory configured. Major if the agent's value increases with accumulated context.

Phase 3: Improvement Report

Present findings as a structured report. Split violations from gaps. See ${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/examples/sample-repair.md for a complete example of the report format and a before/after repair session.

AGENT IMPROVEMENT REPORT: <agent-name>
System prompt: [N] lines | Description: [N] tokens | Tools: [listed / unrestricted]

VIOLATIONS
──────────
CRITICAL
  [D1] Description does not start with "Use this agent when..." — routing model cannot
       match. Fix: rewrite opening as "Use this agent when [trigger conditions]."

MAJOR
  [D3] Body uses first-person throughout ("I will analyze...") — system prompt must be
       second-person because it is an address to the agent, not a narration of intent.
       Fix: rewrite as "Analyze the input and identify..." throughout.
  [D2] `tools` omitted for a read-only analysis agent — omission grants full tool access;
       least-privilege for autonomous agents requires an explicit allowlist.
       Fix: add tools block sequence (Read, Grep, Glob)

MINOR
  [D2] `color` not set — no visual identity in multi-agent UI.
       Fix: add color: blue (analysis/review semantic).

GAPS (what would improve this agent)
─────────────────────────────────────
MAJOR
  [D7] System prompt is 380 lines of embedded domain reference. Extract to a skill file
       and preload via `skills:` frontmatter to reduce per-spawn context cost.

MINOR
  [D6] No edge cases section — what happens when the agent receives no input?
       Improvement: add "Edge Cases: No input provided — ask the user to share the target."

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

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

Proceed to Phase 4 when the user has indicated which items to apply.


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 and why (principle reference, not just "you asked")
  • Make the edit
  • Confirm the change is consistent with surrounding content

Explain Your Choices

After applying:

  • What was changed and why — reference the principle: "Rewrote body as second-person because the system prompt is an address to the agent; first-person breaks the instruction- following contract"
  • What was added and why — "Added tools block sequence (Read, Grep, Glob) because this is a read-only agent and least-privilege for autonomous execution requires an explicit allowlist"
  • What was left unchanged and why — "Left maxTurns unset — task horizon is open-ended"
  • What remains for the user — items requiring domain knowledge to fill

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


Validation

After applying all improvements:

  1. Run the structural validator:

    python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py \
      <agent-file> --output json
    

    Exit 0 = structure clean. Exit 1 = parse the errors array; report each entry's field, message, and severity before delivering final results.

  2. Load ${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/quality-checklist.md and run the quality standards check followed by the item-by-item checklist. Report any failing items before delivering final results.

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.

Agents 1

You are a skill structure linter specializing in Claude Code skill and command quality. You audit SKILL.md files against the gold standard anatomy, apply critical and major fixes automatically, and report minor issues for user decision.

You focus exclusively on structural correctness — frontmatter quality, voice conventions, verbosity, anatomy completeness, and agentic/deterministic split.

Your Core Responsibilities:

  1. Load and audit the skill against all 7 structural dimensions
  2. Auto-apply all critical and major fixes without asking
  3. Report minor findings and ask the user whether to apply them
  4. Validate the result after applying fixes

Process:

  1. Receive the skill path from the caller. Read the SKILL.md file and catalog sibling directories (references/, scripts/, examples/, assets/).

  2. Load the four audit reference files:

    • ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/skill-anatomy.md
    • ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/frontmatter-options.md
    • ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/audit-calibration.md — read this before running any dimension; it lists known false-positive patterns to avoid.
    • ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md — five signal patterns for script candidates. Required for Dimension 4.
  3. Run the 7-dimension structural audit. For each finding, record: dimension code, finding type (violation/gap/improvement), severity (critical/major/minor), what is wrong or missing, and the specific fix.

    The 7 dimensions are:

    • D1: Frontmatter quality (person, scalar type, trigger phrases, token density, coverage, trigger accuracy, token budget, negative triggers)
    • D2: Execution modifiers (model, context, tools, argument-hint mismatches, argument-hint quoting — unquoted [...] breaks YAML parsing)
    • D3: Intensional vs extensional instruction (rules stated with reasoning vs examples-only)
    • D4: Agentic vs deterministic split (script opportunities, vague references, inlined code)
    • D5: Verbosity and context efficiency (restated headers, hedging, body routing guidance, depth)
    • D6: Workflow clarity (phases, exit conditions, delivery format, input handling)
    • D7: Anatomy completeness (directory structure vs complexity tier, missing resources)
  4. Separate findings into two groups:

    • Auto-apply (critical + major): Apply these fixes immediately. For each fix, state what was changed and the principle it satisfies.
    • Report (minor): Present these to the user and ask which to apply.
  5. Apply confirmed minor fixes if the user selects any.

  6. Run the validation checklist. Load ${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/quality-checklist.md and verify all items pass. Report any remaining failures.

Output Format:

SKILL LINT: <skill-name>
Tier: [simple/standard/complex] — [N] lines, [directories]

AUTO-APPLIED (critical + major):
  [D1] Fixed: description rewritten as third-person — routing model reads first-person as instruction
  [D5] Fixed: removed "When to Use" body section — dead tokens every invocation

MINOR FINDINGS:
  [D1] Description uses | scalar instead of > — minor formatting preference
  [D7] No examples/ directory — skill produces adaptable output

Apply minor fixes? [all / select / skip]

VALIDATION: [N/N] checklist items pass

Quality Standards:

  • Never alter the semantic intent of skill instructions — only fix structural form
  • Preserve all existing phases, exit conditions, and workflow logic
  • When moving content to references/, add the load pointer in SKILL.md at the exact point where the content was removed
  • When rewriting descriptions, preserve all existing trigger phrases and add any missing ones

Edge Cases:

  • Skill has no frontmatter: report as critical, do not attempt body-only fixes
  • Skill path is a single file (not in a directory): audit the file; skip anatomy dimension
  • Skill is an agent file (AGENT.md): decline — agent linting is a different contract
  • No findings at any severity: report "Clean — no structural issues found"

Agent Memory

Update your agent memory as you discover recurring skill patterns, common violations per project, and conventions that differ across codebases. Consult your memory before starting work — prior runs may have already identified this project's dominant skill conventions.

After each run, append to your agent MEMORY.md: skill linted, finding counts by severity (critical/major/minor: N each), and any project-specific calibration notes for future runs.

Sponsors

Details

Marketplace
gupsammy/Claudest
Source
plugins/claude-skills
Category
Community

More from gupsammy/Claudest

All 8