claude-skills

What this skill does

# Agent Skills

Guide for creating modular, self-contained Agent Skills that extend Claude's capabilities with specialized knowledge.

## What Are Agent Skills?

Agent Skills are organized directories containing instructions, scripts, and resources that Claude can dynamically discover and load. They enable a single general-purpose agent to gain domain-specific expertise without requiring separate custom agents for each use case.

### Key Concepts

- **Modularity**: Self-contained packages that can be mixed and matched
- **Reusability**: Share and distribute expertise across projects and teams
- **Progressive Disclosure**: Load context only when needed, keeping interactions efficient
- **Specialization**: Deep domain knowledge without sacrificing generality

### Skill Categories

Skills fall into two categories (source: Anthropic PDF Guide):

**Capability Uplift**: Enhances Claude's core abilities (coding, analysis, reasoning). These are stable across model versions because they build on general capabilities. Example: a code review skill that adds structured review steps.

**Encoded Preference**: Encodes user-specific workflows, formatting, and conventions. These need updates when models change because they depend on model behavior for fidelity. Example: a commit message skill that enforces team-specific format.

When creating a skill, identify its category — this determines testing strategy and maintenance expectations.

## How Skills Work

Skills operate on a principle of progressive disclosure across multiple levels:

### Level 1: Discovery
Agent system prompts include only skill names and descriptions, allowing Claude to decide when each skill is relevant based on the task at hand.

### Level 2: Activation
When Claude determines a skill applies, it loads the full `SKILL.md` file into context, gaining access to the complete procedural knowledge and guidelines.

### Level 3+: Deep Context
Additional bundled files (like references, forms, or documentation) load only when needed for specific scenarios, keeping token usage efficient.

This tiered approach maintains efficient context windows while supporting potentially unbounded skill complexity.

## Skill Structure

### Minimal Requirements

Every skill must have:

```
skill-name/
└── SKILL.md
```

### Complete Structure

More complex skills can include additional resources:

```
skill-name/
├── SKILL.md           # Required: Core skill definition
├── scripts/           # Optional: Executable code for deterministic tasks
├── references/        # Optional: Documentation loaded on-demand
└── assets/            # Optional: Templates, images, boilerplate
```

## SKILL.md Format

Each `SKILL.md` file must begin with YAML frontmatter followed by Markdown content:

```markdown
---
name: skill-name
description: Concise explanation of when Claude should use this skill
license: MIT
---

# Skill Name

Main instructional content goes here...
```

### YAML Properties

Source: [Claude Code Skills documentation](https://code.claude.com/docs/en/skills#frontmatter-reference). All fields are optional; only `description` is recommended.

- `name`: Display name. If omitted, defaults to the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters).
- `description` (recommended): What the skill does and when to use it. Claude uses this to decide when to apply the skill. Combined `description` + `when_to_use` is truncated at 1,536 characters in the skill listing — put the key use case first.
- `when_to_use`: Additional trigger phrases or example requests, appended to `description` in the listing.
- `license`: License name or filename reference.

The full upstream frontmatter reference (with `disable-model-invocation`, `user-invocable`, `allowed-tools`, `model`, `effort`, `context: fork`, `agent`, `hooks`, `paths`, `shell`, `arguments`, `argument-hint`, `metadata`) lives in `references/frontmatter-fields.md`. Load that reference when authoring a skill that needs anything beyond name/description/license.

**Description constraints**:
- Use third person (not "I can help you" or "You can use this")
- Include both **what it does** AND **when to use it**
- Pattern: `[What it does]. Use when [trigger conditions].`

> **Critical**: The `description` is the ONLY text Claude sees during skill discovery (Level 1). The body's "When to Use" section only loads AFTER activation (Level 2) and cannot trigger it. All activation triggers belong in the description.

### Frontmatter policy for THIS marketplace

The upstream Claude Code spec allows `allowed-tools` on a skill — it pre-approves listed tools while the skill is active. **This marketplace's `test/validate-plugin.nu` rejects `allowed-tools` on skills as a hard validation failure.** Reasoning:

- Tool filtering belongs on **agents** (the `tools:` frontmatter on an agent file), not on skills the agent loads. See the `claude-agents` skill.
- Skills in this marketplace stay capability-driven (knowledge, procedure) and inherit tools from the calling context.
- An agent that needs constrained tool access defines its own allowlist; skills it consumes do not override that.

When working in this marketplace: keep skill frontmatter to `name`, `description`, optional `license`, optional `metadata`. Use `allowed-tools` on agents instead.

When working in another project that does not enforce this policy, the upstream `allowed-tools` field is valid and documented.

### Markdown Body

The content section has no structural restrictions. Include:

- When to activate the skill
- Core procedural knowledge
- Best practices and guidelines
- Examples and patterns
- References to additional resources (if any)

## Pre-edit checklist

Before writing or editing any SKILL.md, verify:

- [ ] Description uses third person and includes a `Use when ...` trigger pattern
- [ ] Combined `description` + `when_to_use` under 1,536 characters
- [ ] No `allowed-tools` field in frontmatter (this marketplace's validator rejects it; use agents for tool allowlists)
- [ ] Body under 500 lines per upstream guideline; split into `references/` once exceeded
- [ ] References stay one level deep (SKILL.md → reference, not reference → reference)
- [ ] Zero hedging verbs: should, may, might, consider, try to, offer to, it would be good to
- [ ] Anti-fabrication rules apply to this SKILL.md itself — every claim about a tool, file, or behavior is verifiable

A failed checkbox is a blocker, not a preference.

## Skill content types

Three patterns from the upstream docs guide what to put in the body:

- **Reference content** — knowledge, conventions, style guides. Loads inline alongside conversation context. Example: API design patterns for a codebase.
- **Task content** — step-by-step instructions for a specific action (deploy, commit, generate). Often pair with `disable-model-invocation: true` to prevent automatic invocation.
- **Subagent-fork content** — runs in an isolated context (`context: fork` + `agent: Explore|Plan|...`). Skill body becomes the task prompt; skill produces a self-contained result.

## Dynamic context and substitutions

Skills support runtime substitution before content reaches the model. Source: [Claude Code Skills docs](https://code.claude.com/docs/en/skills#inject-dynamic-context).

**Shell injection** — Claude Code can run shell commands embedded in a skill before the body reaches the model; the command's stdout replaces the placeholder. Two forms:

- **Inline**: a bang character followed by a backtick-quoted command on a single line.
- **Fenced**: a code fence whose opening line is three backticks followed by a bang.

`````markdown
## Current diff
!`git diff HEAD`

```!
node --version
npm --version
```
`````

**String substitutions** in skill content:
- `$ARGUMENTS` — full arguments string
- `$ARGUMENTS[N]` or `$N` — argument by 0-based index
- `$name` — named argument when `arguments:` declared in frontmatter
- `${CLAUDE_SESSION_ID}` — current session ID
- `${CLAUDE_EFFORT}` — curr