Agent Skills Creator

Agent Skills Creator

Create and improve skills that follow the Agent Skills open format. Covers the full lifecycle from pattern selection through validation and README update.

• IS: creating new agent skills and auditing or rewriting existing ones: SKILL.md, references, rules folders, scripts, evaluations.
• IS NOT: AGENTS.md/CLAUDE.md instruction files (use agents-md) or general documentation quality (use docs-writing).

Choose a Mode

• Creating a new skill → follow the Creation Workflow below.
• Auditing, improving, or rewriting an existing skill → load references/improving-existing-skills.md. It scores ten audit dimensions, runs an ordered rewrite procedure, then reuses Steps 5-8 below for validation and shipping.

Reference Files

Choose a Skill Category

Determine what type of problem the skill solves. Category informs pattern choice.

Load references/skill-categories.md for detailed guidance per category including authoring tips and examples.

Choose a Skill Pattern

Decision guide:

• Auditing or linting against a checklist: rules-based
• Guiding a multi-step process: workflow
• Dispatching to different tracks by context: simple/hub
• Unsure: start with workflow (most flexible)

Load references/skill-patterns.md for structural templates and skeletons of each pattern.

Creation Workflow

Copy this checklist to track progress:

Skill creation progress:
- [ ] Step 1: Choose skill category and pattern
- [ ] Step 2: Create directory and frontmatter
- [ ] Step 3: Write SKILL.md body
- [ ] Step 4: Add reference or rule files
- [ ] Step 5: Validate with quality checklist
- [ ] Step 6: Update README.md
- [ ] Step 7: Smoke-test installation
- [ ] Step 8: Evaluate and iterate

Step 1: Choose skill category and pattern

First determine the category (what problem the skill solves), then pick the structural pattern. Load references/skill-categories.md for category guidance and references/skill-patterns.md for structural templates.

Step 2: Create directory and frontmatter

Load references/format-specification.md for hard constraints.

• Create skills/<name>/SKILL.md
• Folder name must match name field (kebab-case)
• name: max 64 chars, lowercase letters/numbers/hyphens, no "anthropic" or "claude"
• description: max 1024 chars, third-person voice, include "Use when..." triggers with specific keywords

Step 3: Write SKILL.md body

• Keep under 500 lines; split into reference files if longer
• Open the body with an IS/IS-NOT boundary pair when adjacent skills exist or scope creep is likely (see "Open with Boundaries" in references/authoring-tips.md)
• Only add context Claude does not already have (see "Don't State the Obvious" in references/authoring-tips.md)
• Use consistent terminology throughout
• Match degrees of freedom to task fragility: prose for open-ended work, specific scripts for fragile or destructive operations (see "Degrees of Freedom" in references/authoring-tips.md)
• Reach for named content patterns when they fit: template for fixed output, examples for format-sensitive output, conditional for decision points
• Include a copyable progress checklist for multi-step workflows
• Include validation/feedback loops for quality-critical tasks
• Build a Gotchas section from observed failure points; this is the highest-signal content
• Load references/authoring-tips.md for content strategy guidance on voice, degrees of freedom, content patterns, descriptions, and more

Step 4: Add reference or rule files

Workflow/mixed pattern: add references/ folder with focused files. Link each from SKILL.md with "Read when..." guidance in a table.

Rules-based pattern: add rules/ folder. Load references/rules-folder-structure.md for the _sections.md, _template.md, file-naming, and priority-table layout.

Simple/hub pattern: add track files alongside SKILL.md. Link from a tracks table.

Key constraints:

• References must be one level deep from SKILL.md (no chains)
• Files over 100 lines need a table of contents at the top
• Files are only loaded when explicitly listed in SKILL.md
• Long reference files (up to ~450 lines) are fine when TOC'd and single-topic; split by loading condition, not by line count alone
• For broad domains, prefer a comprehensive-reference folder of many small focused files over a few monoliths (see "Comprehensive Reference Folders" in references/authoring-tips.md)
• agents/ is a sanctioned optional folder for subagent prompt definitions the skill dispatches to

Advanced options:

• Include executable scripts in scripts/ for Claude to compose; load references/executable-code.md for error handling, constants, plan-validate-execute, runtime environment, package deps, and MCP tool naming
• Add config.json for skills needing user-specific setup context across sessions
• Define on-demand hooks (PreToolUse/PostToolUse) for safety gates or observation

Step 5: Validate

Load references/quality-checklist.md and run all applicable checks.

Step 6: Update README.md

Add a bullet under the matching category heading and bump the skill count near the top of the README:

- **[<skill-name>](./skills/<skill-name>/SKILL.md)**: <one-line description>

Categories used in this repo: Architecture, Design, Writing, Quality, Shipping, Authoring.

Step 7: Smoke-test

Install via the skills CLI, never cp -R into ~/.claude/skills/, which bypasses the ~/.agents/skills symlink chain:

npx skills add mblode/agent-skills -g --skill <name> -y
ls ~/.claude/skills/<name>/

Deploy chain: skills add writes to ~/.agents/skills/<name>/, which is symlinked into ~/.claude/skills/<name>/ for Claude Code to pick up.

For local iteration without reinstalling, symlink the repo folder directly and unlink when done:

ln -s /path/to/agent-skills/skills/<name> ~/.claude/skills/<name>

Step 8: Evaluate and iterate

Load references/evaluation-and-iteration.md. Define 3+ evaluation scenarios, test on each target model, and iterate based on observed Claude behavior, not assumptions about what Claude should need.

Anti-patterns

• Dumping full specification into SKILL.md body (use reference files)
• Creating reference-to-reference chains (keep one level deep)
• Including time-sensitive content ("before August 2025, use...")
• Restating what Claude already knows (how to write Markdown, general coding advice, standard conventions)
• Using "I audit..." or "Use this to..." voice in descriptions (use third-person)
• Adding README.md, CHANGELOG.md, or INSTALLATION_GUIDE.md to the skill folder
• Dropping files in folders without linking them from SKILL.md
• Installing with cp -R into ~/.claude/skills/, which bypasses the ~/.agents/skills symlink chain; use npx skills add
• Leaving supporting files at the skill root when the skill is not a simple/hub pattern (move them to references/)
• Over-constraining Claude's approach when specifying outcomes would suffice (railroading)
• Writing the description as a human summary instead of a model trigger with "Use when..." phrases and quoted user phrases
• Skipping a Gotchas section for skills with known failure modes
• Hardcoding absolute paths for persistent data instead of using ${CLAUDE_PLUGIN_DATA}
• Storing persistent data in the skill directory itself (gets deleted on upgrade)
• Referencing MCP tools without the server prefix (bigquery_schema instead of BigQuery:bigquery_schema)
• Magic numbers in scripts with no justifying comment (voodoo constants)
• Shipping a skill without testing it on every target model; what reads well to Opus may underspecify for Haiku

Related Skills

• agents-md for auditing AGENTS.md/CLAUDE.md instruction files
• docs-writing for documentation quality rules

Authoring Tips

Practical guidance for writing high-signal skill content. These complement the format rules in format-specification.md.

Contents

• Don't State the Obvious
• Open with Boundaries (IS/IS-NOT)
• Build a Gotchas Section
• Use the File System for Progressive Disclosure
• Comprehensive Reference Folders
• Degrees of Freedom
• Common Content Patterns
• The Description Field Is For the Model
• Think Through the Setup
• Memory and Storing Data
• Store Scripts and Generate Code
• On-Demand Hooks
• Composing Skills
• Measuring Skills

Don't State the Obvious

Claude knows a lot about coding and your codebase. Focus on information that pushes Claude out of its normal way of thinking.

• If Claude would do it correctly without the instruction, omit it
• General coding advice ("use descriptive variable names") adds noise
• Standard framework conventions (2-space indentation, semicolons) are already known
• Focus on where your org deviates from defaults or where Claude consistently gets it wrong

Test: For each line in SKILL.md, ask "Would removing this cause Claude to make a mistake?" If not, cut it.

Open with Boundaries (IS/IS-NOT)

When sibling skills exist or scope creep is likely, open the body (immediately after the H1 intro) with a bold IS/IS-NOT pair. It prevents the model from running the wrong skill or stretching this one past its remit.

- **IS:** producing a self-contained brief another agent can execute without clarification.
- **IS NOT:** doing the task itself, or planning work you will execute in this session.

Name the sibling skill to route to in the IS-NOT line where one exists ("use agents-md"). Skip the opener for skills with no adjacent skills and an unmistakable scope; it would restate the description.

Build a Gotchas Section

The highest-signal content in any skill. Build from common failure points Claude runs into when using the skill.

• Place near the end of SKILL.md as a quick-reference section (call it "Gotchas" or "Anti-patterns")
• Ground every gotcha in a real observed failure, not hypothetical concerns
• Each gotcha names the concrete command, value, or path involved and the consequence of getting it wrong; a warning without a consequence reads as optional
• Update the section over time as new failure modes appear
• Format as short, scannable bullets, not paragraphs

Good: "Don't use the brand domain for tenant subdomains; reputation damage from one tenant affects all" Bad: "Be careful with domain naming" (too vague, no reason given)

Use the File System for Progressive Disclosure

A skill is a folder, not just a markdown file. Think of the entire file system as context engineering. Tell Claude what files are in your skill, and it will read them at appropriate times.

• references/: deep-dive documentation loaded on demand
• scripts/: executable utilities Claude can compose
• assets/: template files for output Claude should copy and adapt (e.g., if your skill produces a markdown report, include the template in assets/)
• examples/: usage examples and code snippets Claude can reference
• rules/: categorized rule files for audit/lint skills

The simplest form of progressive disclosure is pointing to other markdown files. Split detailed function signatures, API docs, or usage examples into separate files and tell Claude when to load them.

Comprehensive Reference Folders

For broad domains (a design system, a full CLI surface, a style guide), a folder of many small focused files beats a few monoliths. A design-system skill with 40 files of 50-200 lines each (buttons.md, colors.md, typography.md, forms.md) lets Claude load exactly the two files a task needs instead of a 2000-line reference.

• One concern per file; name the file after the concern
• Keep an index.md (or a table in SKILL.md) mapping concerns to files
• Each file stands alone, with no cross-file reading order
• Individual files can run long (up to ~450 lines) when single-topic and TOC'd; split by loading condition, not line count

Degrees of Freedom

Match specificity to how fragile the task is. Over-constraining open-ended tasks makes the skill brittle; under-constraining fragile tasks loses determinism.

Analogy: Claude is a robot crossing a landscape. On a narrow bridge with cliffs on either side, hand it exact steps. In an open field, point in a direction and let it choose the path.

High freedom: multiple valid approaches; context determines best path. Use prose instructions:

Review the code for bugs, readability, and adherence to project conventions.

Medium freedom: a preferred pattern exists but variation is acceptable. Use pseudocode or parameterized scripts:

def generate_report(data, format="markdown", include_charts=True):
    ...

Low freedom: fragile, consistency-critical, or destructive. Use specific commands with few parameters:

python scripts/migrate.py --verify --backup

When to be prescriptive: format contracts, safety constraints, naming conventions, API schemas, migrations. When to be flexible: implementation approach, code structure, tool selection.

Railroading anti-pattern: "Use exactly this signature: async function fetchUser(id: string): Promise<User>" Flexible alternative: "Fetch functions return typed promises and accept string IDs"

Common Content Patterns

Three patterns recur across skills. Name them explicitly when reaching for one.

Template pattern

Provide a fixed or flexible output format so Claude produces consistent results. Use strict phrasing when the format is a contract ("ALWAYS use this exact template"), flexible phrasing when it's a starting point ("Here is a sensible default; adjust sections as needed").

# [Title]

## Executive summary
[One paragraph]

## Key findings
- Finding 1
- Finding 2

Examples pattern

When output quality depends on style (commit messages, copy, changelog entries), provide 2-3 input/output pairs. Examples convey tone and level of detail more efficiently than description.

Input: Added user authentication with JWT tokens
Output:
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

Conditional workflow pattern

Route Claude through decision points instead of listing every path upfront.

Determine modification type:
- Creating new content? → Follow "Creation workflow" below
- Editing existing content? → Follow "Editing workflow" below

Push large branches into separate reference files so the main SKILL.md stays scannable.

The Description Field Is For the Model

When Claude Code starts a session, it scans every skill's description to decide relevance. The description is a trigger description, not a human summary.

• Optimize for the words users will say when they need the skill
• Include action verbs and domain nouns the model uses for routing
• Add quoted user phrases: "how do I...", "build a...", "fix my..."
• Structure: [Does what] for/using [domain]. [Covers what]. Use when [specific trigger phrases].

Weak: "Provides architecture guidance for multi-tenant platforms" Strong: "Provides architecture guidance for multi-tenant platforms on Cloudflare or Vercel. Use when defining domain strategy, tenant identification, isolation, routing, or asking 'how do I support multiple tenants' or 'build a white-label platform'."

Think Through the Setup

Some skills need user-specific context before they can work. Use a config pattern rather than asking the same questions every session.

• Store setup information in a config.json file in the skill directory
• If config is not set up, the skill's first step should gather context from the user
• Use AskUserQuestion for structured, multiple-choice questions
• Pattern: Step 1 checks for config → gathers if missing → remaining steps use it

{
  "slack_channel": "#team-standups",
  "ticket_project": "BACKEND",
  "author": "Jane Smith"
}

Memory and Storing Data

Skills can persist data across sessions by storing files. This enables skills that learn and improve over time.

• Use ${CLAUDE_PLUGIN_DATA} as the storage path; it is stable across skill upgrades (data in the skill directory itself may be deleted on upgrade)
• Formats: append-only text logs, JSON files, SQLite databases
• Example: a standup skill keeps a standups.log so it knows what changed since yesterday
• Example: an audit skill stores previous-findings.json to track regressions

Store Scripts and Generate Code

One of the most powerful tools you can give Claude is code. Scripts and libraries let Claude spend its turns on composition rather than reconstructing boilerplate.

• Include executable scripts (.sh, .py, .ts) alongside SKILL.md
• Give Claude helper functions to compose rather than regenerate each time
• Pattern: scripts/ folder holds utilities, Claude generates wrapper scripts on the fly
• Example: data skill includes fetch_events(), fetch_users(), run_query() that Claude composes for complex analysis

For error handling, constants, plan-validate-execute, runtime environment, package dependencies, and MCP tool references, see executable-code.md (linked from SKILL.md).

On-Demand Hooks

Skills can include hook definitions that activate only when the skill is called and last for the session duration. Use for opinionated safety or observation hooks that should not run all the time.

• PreToolUse hooks: validate or block tool calls (e.g., block rm -rf in a prod skill)
• PostToolUse hooks: observe and log tool results
• Define hooks in the SKILL.md instructions for Claude to register

Example use cases:

• /careful: blocks destructive commands via PreToolUse matcher on Bash
• /freeze: blocks Edit/Write outside a specific directory during debugging
• /observe: logs all Bash commands to an audit trail

Composing Skills

Skills can depend on each other. Reference other skills by name in your SKILL.md and the model will invoke them if they are installed.

• Dependency management is not built into skills yet; composition is name-based
• Use a "Skill handoffs" or "Related skills" section to document which skills yours connects to
• Pattern: "After completing this workflow, run skill-name for the next step"
• Keep each skill focused on one concern; compose rather than duplicate

Measuring Skills

To understand adoption and quality, track when and how often skills are invoked.

• Use a PreToolUse hook to log skill invocations across your org
• Compare actual usage against expected trigger rates to find undertriggering skills
• Undertriggering often means the description field needs better trigger phrases
• Popular skills are candidates for promotion to your marketplace or shared repo

Evaluation and Iteration

How to measure whether a skill works and improve it over time. Build evaluations before writing extensive documentation; they reveal actual gaps instead of imagined ones.

Contents

• Build Evaluations First
• Test Across Models
• Iterate with Two Claudes
• Observe How Claude Navigates
• Measuring Adoption

Build Evaluations First

Write 3+ representative scenarios before expanding SKILL.md. Without evals, skill content drifts toward anticipated problems that never materialize.

Process: 1. Run Claude on the target task without the skill. Note what it gets wrong or is missing 2. Convert each failure into an eval scenario 3. Measure baseline (no skill) vs. treatment (with skill) on the same scenarios 4. Iterate until the treatment consistently beats baseline

Eval scenario structure:

{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF and save to output.txt",
  "files": ["fixtures/document.pdf"],
  "expected_behavior": [
    "Reads the PDF with an appropriate library or CLI tool",
    "Extracts text from every page",
    "Writes extracted text to output.txt in readable form"
  ]
}

There is no built-in runner for this format; treat it as a rubric. Execute scenarios manually or build a thin harness.

Test Across Models

Skills augment the underlying model. What works for Opus may underspecify for Haiku; what's necessary for Haiku may clutter Opus.

• Haiku: does the skill provide enough guidance and explicit steps?
• Sonnet: is the content clear and efficient?
• Opus: does the skill avoid over-explaining?

Test on every model the skill is likely to run under. If a skill targets Claude Code specifically, the current default model is the minimum bar.

Iterate with Two Claudes

Use one Claude instance (Claude A) to author and refine the skill. Use another (Claude B) in a fresh session with the skill loaded to perform real tasks.

1. Give Claude B a real task 2. Watch where Claude B struggles, skips a rule, or makes a surprising choice 3. Report the specific observation to Claude A ("B forgot to filter test accounts on a regional report") 4. Let Claude A suggest targeted edits: stronger language, reordering, a new section 5. Apply the edit and test again

This loop improves skills based on observed behavior, not assumptions. Avoid rewriting from memory of what Claude "should" need.

Observe How Claude Navigates

Watch real sessions for:

• Unexpected exploration paths: Claude reads files in an order the author did not plan; structure may be wrong
• Missed connections: Claude fails to follow a reference; links need to be more prominent
• Overreliance on one section: if the same file is read every time, move its content into SKILL.md
• Ignored content: if a reference file is never accessed, either delete it or signal it better in SKILL.md

The name and description fields matter most for triggering. If the skill isn't invoked when expected, the description needs clearer trigger phrases before any body content matters.

Re-Evaluating After a Rewrite

After improving an existing skill (see improving-existing-skills.md), rerun its evaluation scenarios before shipping. A rewrite that scores better on the audit dimensions but worse on the evals is a regression: the dimensions measure form, the evals measure behavior.

Measuring Adoption

See the "Measuring Skills" section of authoring-tips.md for hook-based logging of skill invocations across an org. Use that data to find undertriggering skills and candidates for promotion to a shared library.

Executable Code in Skills

Guidance for skills that include scripts, depend on packages, or invoke MCP tools. Focus is on patterns that keep scripts reliable and cheap to execute.

Contents

• Execute vs. Read as Reference
• Solve, Don't Punt
• No Voodoo Constants
• Plan-Validate-Execute
• Runtime Environment
• Package Dependencies
• MCP Tool References
• Visual Analysis

Execute vs. Read as Reference

Make execution intent explicit in SKILL.md. Without it, Claude may read a script and reconstruct its logic instead of running it, wasting tokens and diverging from the canonical behavior.

• Execute: "Run scripts/analyze_form.py input.pdf > fields.json"
• Reference: "See scripts/analyze_form.py for the field-extraction algorithm"

Prefer execution for deterministic work. Reserve reference reads for cases where Claude must adapt the algorithm to a novel input.

Solve, Don't Punt

Scripts should handle recoverable errors, not defer them to Claude. Punting wastes a turn and produces non-deterministic outcomes.

Punt (bad):

def process_file(path):
    return open(path).read()

Solve (good):

def process_file(path):
    try:
        with open(path) as f:
            return f.read()
    except FileNotFoundError:
        print(f"{path} not found, creating default")
        with open(path, "w") as f:
            f.write("")
        return ""

A script that always returns a sensible default (or fails with a specific, actionable error message) is more useful than one that raises raw exceptions.

No Voodoo Constants

Every magic number needs a comment explaining why. If the author cannot justify the value, Claude cannot either.

Voodoo:

TIMEOUT = 47
MAX_RETRIES = 5

Justified:

# HTTP requests typically complete under 30s; extra margin for slow connections
REQUEST_TIMEOUT = 30

# 3 retries covers most intermittent failures without excessive latency
MAX_RETRIES = 3

Plan-Validate-Execute

For batch or destructive operations, split the work into three phases so errors surface before changes are applied.

1. Plan: Claude writes an intermediate file describing the operation (e.g., changes.json listing every field and value) 2. Validate: a script checks the plan against the target (schema, conflicts, missing fields) and produces actionable errors 3. Execute: a second script applies the plan once validation passes

Use this for multi-record edits, schema migrations, form filling, and similar operations where a dry run is valuable. Validation scripts should name specific problems: "Field signature_date not in form. Available: customer_name, order_total, signed_date."

Runtime Environment

Skills run in a filesystem with bash and code execution. The execution model affects how to organize content.

• Only the frontmatter (name, description) is pre-loaded at session start
• SKILL.md is read when a trigger matches; reference files are read on demand
• Scripts can be executed via bash without their source entering the context window; only output counts
• Large reference files and datasets are free until accessed
• Use forward slashes in all paths; Windows-style paths break on Unix
• Name files descriptively (form-validation-rules.md, not doc2.md) so Claude can guess content from the path

Bundle comprehensive resources (docs, examples, datasets) because they cost nothing until read.

Package Dependencies

List required packages explicitly in SKILL.md. Availability differs by environment:

• Claude Code / claude.ai code execution: can install from npm and PyPI at runtime
• Claude API (direct): no network access, no runtime installs; dependencies must be pre-installed

When writing scripts, prefer the standard library when possible. When third-party packages are required, name them and show the install command once in SKILL.md.

MCP Tool References

Always reference MCP tools by their fully qualified name: ServerName:tool_name. Unqualified names cause "tool not found" errors when multiple servers expose similarly named tools.

• BigQuery:bigquery_schema, not bigquery_schema
• GitHub:create_issue, not create_issue
• Linear:list_issues, not list_issues

Use the qualified form in both instructions and examples. If a server name changes, update every reference at once.

Visual Analysis

When inputs can be rendered as images, Claude can analyze them directly with vision. This is often more reliable than parsing structured text for layout-heavy formats.

• PDF forms → render pages to images, analyze field positions
• Charts and diagrams → describe contents from the image, not the source
• Web pages → screenshot and inspect layout

Provide a script that produces the image (pdf_to_images.py), then instruct Claude to read the output with vision. Keep the script focused on conversion; let Claude handle interpretation.

Format Specification

Hard constraints for the Agent Skills format. Every skill must follow these rules.

Contents

• Directory structure
• Frontmatter (required)
• Description examples
• SKILL.md body rules
• Reference and rule files
• Naming conventions
• Advanced skill features

Directory Structure

skills/<name>/
├── SKILL.md              (required)
├── references/            (optional, for progressive disclosure)
├── rules/                 (optional, for audit/lint skills)
│   ├── _sections.md       (category map)
│   ├── _template.md       (rule file template)
│   └── <prefix>-<slug>.md (individual rules)
├── scripts/               (optional, executable utilities)
├── assets/                (optional, templates for output files)
├── examples/              (optional, usage examples and code snippets)
├── agents/                (optional, subagent prompt definitions dispatched from SKILL.md)
├── config.json            (optional, user-specific setup context)
└── <track>.md             (optional, for hub-style skills)

Root-level <track>.md files are exclusive to the simple/hub pattern. Every other pattern keeps supporting files in references/ (or rules/ for audit skills). Multiple rules folders (e.g. rules/ plus rules-modern/) are sanctioned only when SKILL.md explicitly dispatches to each layer.

• Forward slashes only in file paths (even on Windows)
• Kebab-case for all folder and file names
• Folder name must match the name field in frontmatter

Frontmatter (Required)

Both name and description are mandatory. Skills without valid frontmatter will not be recognized.

---
name: skill-name
description: What the skill does. Use when...
---

name field

• Max 64 characters
• Lowercase letters, numbers, and hyphens only (a-z, 0-9, -)
• Must not start or end with a hyphen
• Must not contain consecutive hyphens (--)
• Must not contain "anthropic" or "claude"
• Must match the parent directory name

description field

• Max 1024 characters
• Non-empty, no XML tags
• Third-person voice: "Audits..." not "I audit..." or "Use this to audit..."
• Structure: what the skill does + "Use when..." trigger phrases
• Include specific keywords users might say to trigger the skill

Optional frontmatter fields

• license: License name or reference to bundled LICENSE file
• compatibility: Max 500 chars, environment requirements (rare)
• metadata: Arbitrary key-value pairs for custom properties

Description Examples

Strong descriptions from this repo:

Pattern: [Does what] for/using [domain]. [Checks/covers what]. Use when [specific trigger phrases with keywords].

SKILL.md Body Rules

• Max 500 lines; split into reference files if approaching this limit
• Only add context Claude does not already have (Claude is smart by default)
• Use consistent terminology (pick one term and stick with it)
• Forward slashes in all file paths
• No time-sensitive content (use collapsed "Old patterns" section if needed)
• No em dashes; restructure with commas, colons, periods, or parentheses (applies to every file in the skill, including the description)

Reference and Rule Files

• References must be one level deep from SKILL.md (no chains)
• Files are only loaded when explicitly listed in SKILL.md
• Files over 100 lines should start with a table of contents
• Long references up to ~450 lines are fine when TOC'd and single-topic; split by loading condition, not by line count alone
• Dropping a file in the folder without linking it from SKILL.md means it will not be discovered

Naming Conventions

Advanced Skill Features

Optional features for skills that need persistent state, executable code, or session hooks.

config.json

For skills that need user-specific context (Slack channel, project name, author). Include a template config.json in the skill folder. The skill's first step should check for config and gather missing values via AskUserQuestion.

${CLAUDE_PLUGIN_DATA}

Stable storage path for persistent data that survives skill upgrades. Use this instead of storing data in the skill directory itself. Supports log files, JSON state, and SQLite databases.

Script files

Executable scripts (.sh, .py, .ts) in a scripts/ folder give Claude composable utilities. Document invocation instructions in SKILL.md. Claude can generate wrapper scripts that compose these helpers.

On-demand hooks

Skills can define PreToolUse and PostToolUse hooks that activate only when the skill is invoked and last for the session. Use for safety gates (block destructive commands) or observation (log tool usage). Define hook instructions in SKILL.md.

Improving Existing Skills

Audit-then-rewrite protocol for an existing skill. Use when asked to improve, audit, rewrite, or review a skill that already ships.

Contents

• Relationship to the Creation Workflow
• Audit Dimensions
• Rewrite Procedure
• Structure Normalization Decision Table
• Large Rule-Set Scoping
• Validation

Relationship to the Creation Workflow

Improvement replaces Steps 1-4 of the Creation Workflow with the audit and rewrite phases below, then reuses Steps 5-8 (validate, README, smoke-test, evaluate) unchanged. Never skip Step 5: a rewrite that was never validated against the quality checklist is a regression risk, not an improvement.

Copy this checklist to track progress:

Skill improvement progress:
- [ ] Phase A: Read everything (SKILL.md, every linked file, repo AGENTS.md, README entry)
- [ ] Phase B: Score the ten audit dimensions (before)
- [ ] Phase C: Rewrite in the ordered procedure
- [ ] Phase D: Validate (quality checklist + lint + counts)
- [ ] Phase E: Re-score dimensions (after), update README one-liner, commit

Phase A: Read everything first

• Read SKILL.md fully, then every file it links (references, tracks, rules layers).
• For rules-based skills: read _sections.md, _template.md, and at least 2 sample rules per category.
• Read the repo's AGENTS.md and the skill's current README entry; these are the source of truth for install commands and conventions.
• ls -R the skill folder and list orphan files not referenced from SKILL.md.

Do not start editing during Phase A. Findings discovered mid-edit cause inconsistent half-rewrites.

Audit Dimensions

Score each dimension 1-5 before touching anything. The lowest scores dictate where rewrite effort goes; report before/after scores when done.

Rewrite Procedure

Execute in this order, correctness before triggers, triggers before structure, structure before polish. Reordering causes rework (e.g., density-cutting a section you later move).

1. Stale-path/command/count fixes. Anything contradicting the repo AGENTS.md or observable reality (install commands, file paths, rule counts, CLI flags). These are bugs; fix them before any stylistic work. 2. Description sharpening. Third-person opener stating what the skill does, capability summary, "Use when..." triggers with quoted user phrases. Explicitly disambiguate from sibling skills: if two descriptions could route the same prompt, both need an edge ("For X, use other-skill"). 3. Boundary opener. Add or repair the IS/IS-NOT pair after the H1 (see "Open with Boundaries" in authoring-tips.md). 4. Structure normalization. Apply the decision table below. Update every link after a move; grep all SKILL.md files repo-wide for the old path. 5. Signal-density cut. Delete lines Claude would do correctly anyway; deduplicate content that appears in both SKILL.md and a reference; merge near-duplicate sections. 6. Gotchas pass. Rewrite vague warnings into concrete-failure format (specific command/value + consequence); delete hypothetical concerns nobody has observed. 7. TOC additions. Any file over 100 lines without a table of contents gets one. 8. Workflow integrity. Ensure a copyable progress checklist exists for multi-step workflows and the final step produces evidence (command output, score table, file listing), never "seems right".

Structure Normalization Decision Table

After any rename or move: grep -rn "<old-path>" <repo>/skills/*/SKILL.md must return nothing.

Large Rule-Set Scoping

For rules-based skills with 30+ rule files, do not rewrite every rule. Drift concentrates in SKILL.md, _sections.md, and _template.md; rewrite those fully. Then run a mechanical consistency pass over rule files:

• Frontmatter present (title, impact, tags)
• Filename prefix matches a _sections.md section
• Incorrect/correct example pair present
• Counts reconcile everywhere they appear: ls rules*/ | grep -v '^_' | wc -l vs description, priority table, and any prose mentions

Sample-read ~10% of rules per category; deep-rewrite only the rules that fail sampling. Rewriting a correct rule can only stay equal or get worse.

Validation

1. Run all applicable checks in quality-checklist.md; record the pass count. 2. Frontmatter lint: name matches folder, regex-clean, description ≤1024 chars, no XML tags. 3. wc -l SKILL.md under 500. 4. Every file in the folder is linked from SKILL.md or lives in a dispatched rules layer. 5. Rule counts reconcile (rules-based skills). 6. Repo-wide grep for any path you renamed returns clean. 7. Install smoke-test: npx skills add <repo-slug> -g --skill <name> -y && ls ~/.claude/skills/<name>/. 8. Re-score the ten audit dimensions and report before/after alongside files moved and anything deferred.

Quality Checklist

Run before shipping a new or updated skill. Score each applicable item.

Scoring: Yes = 1, No = 0, N/A = exclude from denominator. Target: all applicable items pass.

Frontmatter (4 checks)

1. name field present, max 64 chars, lowercase letters/numbers/hyphens only 2. name does not contain "anthropic" or "claude", no consecutive hyphens 3. description field present, non-empty, max 1024 chars, no XML tags 4. description uses third-person voice with "Use when..." triggers and specific keywords

SKILL.md Body (8 checks)

5. Under 500 lines 6. Only adds context Claude does not already have 7. Uses consistent terminology throughout (one term per concept) 8. Forward slashes in all file paths (no Windows-style backslashes) 9. Includes copyable progress checklist (if multi-step workflow) 10. Includes validation/feedback loop (if quality-critical) 11. No time-sensitive content 12. Every reference file is explicitly linked with loading guidance

Content Quality (10 checks)

13. Gotchas/anti-patterns section present for skills with known failure modes; each gotcha names a concrete command/value and its consequence 14. Description optimized as model trigger with "Use when..." phrases (not a human summary) 15. No railroading: outcomes specified where flexibility is appropriate, prescriptive only for format/safety 16. Degrees of freedom match task fragility (low for destructive/fragile ops, high for open-ended tasks) 17. Common content patterns applied where relevant (template for fixed output, examples for format-sensitive output, conditional for decision points) 18. Setup/config pattern used if skill requires user-specific context across sessions 19. Only non-obvious guidance included (passes "would Claude do this anyway?" test) 20. Workflow terminates with a concrete verification step that produces evidence (green tests, clean build, screenshot, log output); "seems right" is never a valid exit criterion 21. Anti-rationalization table included for skills where steps are frequently skipped under time pressure (see skill-patterns.md for format) 22. IS/IS-NOT boundary opener present after the H1 when sibling skills exist or scope creep is likely

Reference Files (6 checks)

23. All references are one level deep from SKILL.md (no chains) 24. No reference-to-reference chains 25. Files over 100 lines have a table of contents at the top 26. File names are kebab-case 27. Each reference adds focused value (not duplicating SKILL.md content) 28. Supporting files live in the pattern-correct location (root track files only for simple/hub; otherwise references/ or a rules folder)

Rules Folder (5 checks, rules-based skills only)

29. _sections.md present with numbered categories, impact levels, and prefix mapping 30. _template.md present with YAML frontmatter (title, impact, tags) and incorrect/correct examples 31. Each rule file named <prefix>-<slug>.md matching a section prefix 32. Each rule file has YAML frontmatter and follows the template structure 33. Rule counts reconcile everywhere they appear (description, priority table, prose) with ls rules*/ | grep -v '^_' | wc -l

Repository Integration (3 checks)

34. README.md updated: bullet under the matching category heading (- **[<name>](./skills/<name>/SKILL.md)**: <one-liner>) and skill count bumped 35. Folder name matches name field in frontmatter exactly 36. Smoke-test passes via the install command documented in the repo AGENTS.md (npx skills add), and files appear in the target directory

Evaluation and Testing (2 checks)

37. At least 3 evaluation scenarios documented covering representative tasks 38. Skill tested with all target models (Haiku, Sonnet, Opus as applicable)

Executable Code and MCP (7 checks, only when applicable)

39. ${CLAUDE_PLUGIN_DATA} used for persistent data (not hardcoded absolute paths) 40. Hook definitions follow PreToolUse/PostToolUse schema if skill includes hooks 41. Script files have clear invocation instructions in SKILL.md (execute vs. read as reference) 42. Scripts handle recoverable errors explicitly (no punting raw exceptions to Claude) 43. Script constants justified with comments (no voodoo numbers) 44. MCP tool references use fully qualified ServerName:tool_name format 45. Required packages listed in SKILL.md and available in target runtime

Automatic Fail

• Missing name or description in frontmatter
• SKILL.md over 500 lines without splitting into reference files
• Reference files present but not linked from SKILL.md
• Reference-to-reference chains (more than one level deep)
• Hardcoded absolute paths where ${CLAUDE_PLUGIN_DATA} should be used for persistent storage
• README.md, CHANGELOG.md, or other auxiliary docs inside the skill folder
• Install instructions using cp -R into ~/.claude/skills/, which bypasses the ~/.agents/skills symlink chain

Rules Folder Structure

For rules-based skills (audits, lints, checklists), create a rules/ folder with a section map, a rule template, and one file per rule.

rules/_sections.md

Category map with impact levels. Format:

# Sections

This file defines all sections, their ordering, impact levels, and descriptions.
The section ID (in parentheses) is the filename prefix used to group rules.

---

## 1. Category Name (prefix)

**Impact:** CRITICAL | HIGH | MEDIUM-HIGH | MEDIUM | LOW-MEDIUM
**Description:** One sentence explaining why this category matters.

rules/_template.md

Template for individual rule files:

---
title: Rule Title Here
impact: MEDIUM
tags: tag1, tag2
---

## Rule Title Here

Brief explanation of the rule and why it matters.

**Incorrect (description of what's wrong):**

[code block with bad example]

**Correct (description of what's right):**

[code block with good example]

Individual rule files

• Named <prefix>-<slug>.md where prefix matches the section ID
• One rule per file
• Each file follows the _template.md structure

SKILL.md priority table

Include a table mapping categories to prefixes and rule counts:

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | Category Name | CRITICAL | `prefix-` | N |

Large rule sets

For 30+ rule files, maintenance shifts from rewriting rules to keeping the set consistent:

• Every rule has frontmatter (title, impact, tags) and an incorrect/correct example pair
• Every filename prefix matches a _sections.md section
• Rule counts reconcile everywhere they appear (description, priority table, prose): ls rules/ | grep -v '^_' | wc -l

Multi-layer variant

A skill may carry more than one rules folder (e.g. rules/ for a stable baseline plus rules-modern/ for a newer catalog) only when SKILL.md explicitly dispatches to each layer with its own loading condition. Without that dispatch, consolidate into a single rules/ folder.

Skill Categories

Nine categories that describe what type of problem a skill solves. These are orthogonal to the four structural patterns (Simple/hub, Workflow, Rules-based, Mixed) which describe how a skill is organized. A skill has one category and one pattern.

Contents

• How categories and patterns relate
• Library & API Reference
• Product Verification
• Data Fetching & Analysis
• Business Process & Team Automation
• Code Scaffolding & Templates
• Code Quality & Review
• CI/CD & Deployment
• Runbooks
• Infrastructure Operations

How Categories and Patterns Relate

Category answers what type of problem the skill solves. Pattern answers how the skill is organized structurally.

These are recommendations, not requirements. A Runbook could use Rules-based if it has categorized diagnostic checks.

1. Library & API Reference

Definition: Skills that explain how to correctly use a library, CLI, or SDK, including internal libraries and common libraries Claude sometimes gets wrong.

Key authoring tips:

• Include a folder of reference code snippets showing correct usage
• Focus on gotchas, edge cases, and footguns, not basic usage Claude already knows
• Document the differences between versions if migration is common
• Include error messages and their solutions

Example use cases: internal billing library edge cases, internal CLI wrapper with every subcommand, design system component usage patterns

2. Product Verification

Definition: Skills that describe how to test or verify code is working, often paired with external tools like Playwright, tmux, or headless browsers.

Key authoring tips:

• Include scripts that drive the verification (Playwright scripts, tmux commands)
• Have Claude record evidence (screenshots, video, logs) so you can see what was tested
• Enforce programmatic assertions on state at each step, not just visual checks
• Define clear pass/fail criteria

Example use cases: signup flow driver with state assertions, checkout verifier with Stripe test cards, interactive CLI testing via tmux

3. Data Fetching & Analysis

Definition: Skills that connect to data and monitoring stacks. Include libraries to fetch data, dashboard IDs, credentials patterns, and common analysis workflows.

Key authoring tips:

• Include helper functions/scripts for common data fetches (see "Store Scripts" in authoring-tips.md)
• Document specific table names, column semantics, and join patterns
• Include dashboard IDs and query templates
• Let Claude compose scripts on the fly from your helper library

Example use cases: funnel query with canonical user_id tables, cohort comparison with significance testing, Grafana datasource UID lookup

4. Business Process & Team Automation

Definition: Skills that automate repetitive workflows into one command. Often simple instructions but with dependencies on other skills or MCPs.

Key authoring tips:

• Save previous results in log files so the model stays consistent across runs
• Use ${CLAUDE_PLUGIN_DATA} for stable storage of run history
• Compose with other skills by referencing them by name
• Keep the skill focused on orchestration, not reimplementing what tools already do

Example use cases: standup post aggregation, ticket creation with schema enforcement, weekly recap from PRs and tickets

5. Code Scaffolding & Templates

Definition: Skills that generate framework boilerplate for a specific function in your codebase. Combine with scripts that can be composed.

Key authoring tips:

• Include template files in the skill folder for Claude to copy and adapt
• Useful when scaffolding has natural language requirements (naming conventions, architectural decisions) that pure code generators cannot cover
• Store reusable scripts alongside templates
• Define clear validation steps to confirm the scaffold works

Example use cases: new service/workflow/handler scaffold with org annotations, migration file template with gotchas, new internal app with auth/logging/deploy pre-wired

6. Code Quality & Review

Definition: Skills that enforce code quality standards and review code. Can include deterministic scripts or tools for maximum robustness.

Key authoring tips:

• Consider running these automatically via hooks or in GitHub Actions
• Adversarial review pattern: spawn a fresh-eyes subagent to critique, iterate until findings degrade to nitpicks
• Include both the rules and the verification method
• Separate style preferences (flexible) from correctness requirements (strict)

Example use cases: adversarial code review, org-specific code style enforcement, testing practices and coverage expectations

7. CI/CD & Deployment

Definition: Skills that help fetch, push, and deploy code. Often reference other skills for data collection or verification.

Key authoring tips:

• Include rollback procedures as a first-class concern
• Define clear gates between stages (build → test → deploy → verify)
• Use on-demand hooks for safety (block force-push, require confirmation for prod)
• Reference monitoring/alerting skills for post-deploy verification

Example use cases: PR babysitting (retry flaky CI, resolve conflicts, auto-merge), gradual traffic rollout with error-rate comparison, cherry-pick to prod workflow

8. Runbooks

Definition: Skills that take a symptom (alert, error, Slack thread) and walk through a multi-tool investigation to produce a structured report.

Key authoring tips:

• Structure as symptom → tools → query patterns → findings
• Include the specific dashboard IDs, log queries, and service names for your stack
• Define the output format (structured report with severity, impact, next steps)
• Map common symptoms to their usual root causes

Example use cases: service-specific debugging playbook, oncall alert investigation, request ID log correlation across systems

9. Infrastructure Operations

Definition: Skills that perform routine maintenance and operational procedures, especially those involving destructive actions that benefit from guardrails.

Key authoring tips:

• Build in confirmation gates before destructive operations
• Include soak periods (wait and verify before proceeding)
• Use on-demand hooks to block dangerous commands (rm -rf, DROP TABLE, kubectl delete)
• Log all actions for audit trails

Example use cases: orphaned resource cleanup with Slack notification and confirmation, dependency approval workflow, cost investigation with specific bucket and query patterns

Skill Patterns

Structural templates for the four skill patterns. Pick one and adapt.

These patterns describe how a skill is organized. For what type of problem a skill solves, see skill-categories.md.

Contents

• Simple/hub pattern
• Workflow pattern
• Rules-based pattern
• Mixed pattern

Simple/Hub Pattern

When: Dispatch to 2-5 focused files by track or concern.

skills/<name>/
  SKILL.md          (20-35 lines)
  <track-1>.md
  <track-2>.md

SKILL.md skeleton:

---
name: <name>
description: <what it does>. Use when <triggers>.
---

# Title

Choose the right track and follow its guidance.

## Tracks

- **Track A**: See [track-a.md](track-a.md)
- **Track B**: See [track-b.md](track-b.md)

## Related skills

- `skill-name` for related concern

Example: ui-design (24 lines, dispatches to product-ui.md and marketing-ui.md)

Category affinity: Library & API Reference, Business Process Automation

Root-level track files are exclusive to this pattern; in every other pattern, supporting files live in references/ (or rules/).

Comprehensive-reference variant: for broad domains (a design system, a full CLI surface), the hub dispatches into a folder of many small focused files, e.g. a design-guidelines/ folder with 40 files like buttons.md, colors.md, forms.md, each 50-200 lines, mapped from an index.md. Claude loads exactly the files a task needs. See "Comprehensive Reference Folders" in authoring-tips.md.

Workflow Pattern

When: Multi-step sequential process with progressive reference loading.

skills/<name>/
  SKILL.md          (80-130 lines)
  references/
    <detail-1>.md
    <detail-2>.md

SKILL.md skeleton:

---
name: <name>
description: <what it does>. Use when <triggers>.
---

# Title

One-line summary.

## Reference Files

| File | Read When |
|------|-----------|
| `references/<file>.md` | <condition> |

## Workflow

Copy this checklist to track progress:

[checklist]

### Step 1: ...
### Step 2: ...

## Anti-patterns
- ...

## Related skills
- ...

Example: agents-md (120 lines, 5 references with conditional loading)

Category affinity: Most categories use this pattern: Scaffolding, CI/CD, Verification, Runbooks, Infrastructure Operations

Rules-Based Pattern

When: Audit or lint against categorized rules with priority levels.

skills/<name>/
  SKILL.md          (75-90 lines)
  rules/
    _sections.md
    _template.md
    <prefix>-<slug>.md  (one per rule)

SKILL.md skeleton:

---
name: <name>
description: <what it does>. N rules across M categories covering A, B, C. Use when <triggers>.
---

# Title

N rules across M categories for [domain] quality.

## Audit Workflow

Copy and track this checklist during the audit:

[checklist with steps: scope, load by category, prioritize, fix, recheck]

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | Category Name | CRITICAL | `prefix-` | N |

## Quick Reference

Read only what is needed for the current scope:
- Category map and impact rationale: `rules/_sections.md`
- Rule-level guidance and examples: `rules/<prefix>-*.md`

Each rule file contains:
- Why the rule matters
- Incorrect example
- Correct example

## Review Output Contract

Report findings in this format:

[finding format template with severity, rule ID, issue, fix]

Example: typography-audit (90 rules in 10 categories)

Category affinity: Code Quality & Review

Mixed Pattern

When: Workflow steps with conditional or platform-specific references.

skills/<name>/
  SKILL.md          (50-105 lines)
  references/
    <context-1>.md
    <context-2>.md

SKILL.md skeleton:

---
name: <name>
description: <what it does>. Use when <triggers>.
---

# Title

## Workflow

1. Determine context
2. If context A, load [references/a.md](references/a.md)
3. If context B, load [references/b.md](references/b.md)
4. Execute based on loaded reference
5. Validate output

## References

Load only the reference matching your context:
- **Context A**: [references/a.md](references/a.md)
- **Context B**: [references/b.md](references/b.md)

Example: multi-tenant-architecture (103 lines, 5 platform-specific references)

Category affinity: Data Fetching & Analysis, Runbooks, Infrastructure Operations

Cross-Cutting: Anti-Rationalization Tables

Any pattern above can include an anti-rationalization table: pre-written rebuttals to common excuses for skipping the workflow. Agents (and tired engineers) will produce plausible-sounding justifications for skipping steps. Anti-rationalization tables are the counter.

When to include: Skills where steps are frequently skipped under time pressure (specs, tests, security review, code review).

Format:

## Anti-Rationalizations

| Excuse | Rebuttal |
|--------|----------|
| "This task is too simple for a spec." | Acceptance criteria still apply. Five lines is fine. Zero lines is not. |
| "I'll write tests later." | There is no later. Write the failing test first. |
| "Tests pass, ship it." | Passing tests are evidence, not proof. Did you verify user-visible behavior? |

Place the table after the workflow section but before anti-patterns. Each row should be a specific excuse the agent might generate, paired with a concrete rebuttal that redirects to the workflow step being skipped.