
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@ClaudestRun it inside Claude Code after adding the marketplace with /plugin marketplace add gupsammy/Claudest.
Contents
Discovered from sourceSkills 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:
- Domain & purpose — What problem does this agent solve?
- 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 bodyeffort— if the task warrants non-default thinking depthinitialPrompt— if this is a session agent that should self-startbackground: true— if concurrent execution was identifiedmcpServers— 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:
| Signal | Question | If yes → |
|---|---|---|
| Repeated Generation | Does any step produce the same structure across invocations? | Parameterized script in scripts/ |
| Unclear Tool Choice | Does any step combine tools in a fragile sequence? | Script the procedure |
| Rigid Contract | Can you write --help text for this step right now? | CLI candidate |
| Dual-Use Potential | Would a user run this step from the terminal independently? | Design as proper CLI |
| Consistency Critical | Must 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
| Scope | Location |
|---|---|
| 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: sonnetbecause this agent performs complex multi-file reasoning" - What you excluded and why — "Left
isolationunset; 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
| Dimension | Criteria |
|---|---|
| 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>.mdin anagents/directory - Valid YAML frontmatter with
nameanddescription - 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: inheritunless specific model needed -
colorset and semantically meaningful -
toolsrestricted to minimum needed -
memoryset if cross-session learning identified, with maintenance instructions in body -
effortset if non-default thinking depth needed -
initialPromptset if session-mode agent that self-starts -
background: trueset if concurrent execution identified -
isolation: worktreeset if agent modifies files that need review before merging - No TODO placeholders remaining
Error Handling
| Issue | Action |
|---|---|
| Unclear domain | Ask: what does success look like for this agent? |
| Scope too broad | Split into 2–3 focused agents with non-overlapping trigger conditions |
| Conflicts with existing agent | Note overlap; narrow triggering scope or extend the existing one |
| Vague trigger conditions | Ask 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,
--jsonfor 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
--helpoutput). - 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/--plainflag 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
--jsonmode use NDJSON (one JSON object per line) — enables streaming andjqpiping without buffering. For paginated results with metadata, a JSON object with anitemsarray 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
--jsonis passed or when stdout is not a TTY.
Errors (agent/mixed consumers only)
- When
--jsonis 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. Thehintfield must be an executable command, not prose. - Exit codes:
0success,1runtime error,2invalid usage; for agent/mixed consumers, extend with the typed table from cli-guidelines.md → Exit codes (typed) (3not-found,4auth,5upstream,7conflict) — apply identically across all subcommands so agents branch on the code.
Flags
-h/--helpalways shows help; ignores other args.--versionprints version to stdout.--jsonpreferred for structured output.--output json/-o jsonacceptable 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 —--jsonstays 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-inputdisables prompts.--non-interactiveacceptable 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.
createreturns the new resource's ID and key fields.deleteechoes what was removed. - Rich JSON defaults: in
--jsonmode, return full objects not just IDs. - Bounded lists: list commands default to a safe limit (e.g., 50 items) with
--limitto adjust. In JSON mode, includehas_more(bool) and optionallynext_cursorfor 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;
--jsonfor 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|statelessverdict + 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:
- Language & distribution:
Go·cobra· single binary ·goreleaserfor CI (Omit if language was not determined.) - Name:
mycmd - One-liner:
... - USAGE:
mycmd [global flags] <subcommand> [args]
- Subcommands:
mycmd init ...mycmd run ...
- Global flags:
-h, --help--version-q, --quiet/-v, --verbose(define exactly)--json(structured JSON output; NDJSON for list commands)
- I/O contract:
- stdout:
- stderr:
- Exit codes:
0success1generic failure2invalid usage (parse/validation)- (add command-specific codes only when actually useful)
- Env/config:
- env vars:
- config file path + precedence:
- Data Layer Decision (required when the tool reads from a backend; omit if no backend):
adopt cache|stateless+ one-line rationale. Ifadopt:synccommand, local schema sketch, local-vs-live reads, write invalidation note. - 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.
- 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:
- Primary objective — What should this do?
- Trigger scenarios — When should it activate?
- Inputs/outputs — What does it receive and produce?
- Complexity — Simple, standard, or complex?
- 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:
- 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.
- 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/, notSKILL.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$VARreferences 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:
| Syntax | Purpose |
|---|---|
$ARGUMENTS | All arguments as string |
$1, $2, $3 | Positional arguments (shell-style quoting for multi-word values) |
@path/file | Load file contents |
@$1 | Load file from argument |
| Exclamation + backticks | Execute 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:
| Signal | Question | If yes → |
|---|---|---|
| Repeated Generation | Does any step produce the same structure with different params across invocations? | Parameterized script in scripts/ |
| Unclear Tool Choice | Does any step combine multiple tools in a fragile sequence naturally expressible as one function? | Script the procedure |
| Rigid Contract | Can you write --help text for this step right now without ambiguity? | CLI candidate — delegate design to create-cli |
| Dual-Use Potential | Would a user want to run this step from the terminal, outside the skill workflow? | Design as proper CLI from the start |
| Consistency Critical | Must this step produce bit-for-bit identical output for identical inputs? | Script — never LLM generation |
For each identified script candidate:
- Choose the archetype from
references/script-patterns.md(init/validate/transform/package/query) - If the interface is non-trivial, delegate to
claude-skills:create-cliskill to design it - Scaffold the script in
scripts/using the Python template fromreferences/script-patterns.md - 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
| Type | Location |
|---|---|
| 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-toolsto scope Bash to git commands only, since the skill only needs git for commits" - What you excluded and why — "
hooksomitted (no validation needed),disable-model-invocationleft 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:
| Dimension | Criteria |
|---|---|
| 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 ofreferences/,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:
${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.${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
toolsinclude unscopedBashfor 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: opusset for a task sonnet handles? Cost scales directly per spawn. Major. - Is
isolation: worktreeset without the agent performing git-state modifications? Unnecessary isolation adds overhead. Minor. - Does
disallowedToolsblock a tool the system prompt requires? Critical.
Gaps:
- Is
colorabsent? Visual identity in the UI helps users track which agent is active in multi-agent workflows. Minor. - Is
toolsabsent 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
maxTurnsabsent for a task with a predictable completion horizon? Unbounded agents can loop on ambiguous input. Minor for bounded tasks. - Is
skillsabsent 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: worktreeabsent for an agent that modifies files in the working tree? Without isolation, modifications are immediate and irreversible during the run. Major. - Is
memoryabsent for an agent that would benefit from cross-session learning? Agents that review code, audit patterns, or accumulate project knowledge should use persistent memory (projectrecommended default). Ifmemoryis 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
effortabsent for a cost-sensitive or complexity-varying agent? Fast classification tasks benefit fromeffort: low; deep reasoning tasks fromeffort: high. Minor. - Is
initialPromptabsent for a session-mode agent designed for--agentuse? 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
--helpfor 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
descriptionfield. 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.
colorabsent: No visual identity in multi-agent UI contexts. Minor.- No
memoryfor 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
toolsblock 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
maxTurnsunset — 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:
-
Run the structural validator:
python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py \ <agent-file> --output jsonExit 0 = structure clean. Exit 1 = parse the
errorsarray; report each entry'sfield,message, andseveritybefore delivering final results. -
Load
${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/quality-checklist.mdand 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 ofreferences/,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:
${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.${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.${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$ARGUMENTSor$1/$$2without anargument-hintfield? 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
Bashwhen a scoped pattern (Bash(git:*)) would work? - Does the skill have tools in
allowed-toolsit never uses? Dead entries add noise.
Gaps:
-
Does the skill invoke other skills or spawn agents without
SkillorTaskinallowed-tools? -
Does the skill require user decisions mid-workflow but lacks
AskUserQuestioninallowed-tools? -
Does the skill read a file path from
$1but uses aReadtool call instead of@$1inline 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
--helptext for right now? → CLI candidate; delegate design tocreate-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$VARreferences 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
$VARreferenced in a step have an explicit binding in an earlier step or a pre-flight/preamble section? Scan all$VARNAMEtokens 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 — "
hooksleft 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:
- Load and audit the skill against all 7 structural dimensions
- Auto-apply all critical and major fixes without asking
- Report minor findings and ask the user whether to apply them
- Validate the result after applying fixes
Process:
-
Receive the skill path from the caller. Read the SKILL.md file and catalog sibling directories (references/, scripts/, examples/, assets/).
-
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.
-
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)
-
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.
-
Apply confirmed minor fixes if the user selects any.
-
Run the validation checklist. Load
${CLAUDE_PLUGIN_ROOT}/skills/repair-skill/references/quality-checklist.mdand 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