Skill

/skill — Create Agent Skills

Create Agent Skills for .claude/skills/ following the agentskills.io specification. Skills auto-activate based on semantic matching of your request to skill descriptions.

Skill Types

Directory Standard

Every skill must have SKILL.md. Populate the optional folders when they add value — skip them when they don't.

skill-name/
├── SKILL.md              # Required
├── references/           # Detailed docs the agent reads on demand
│   └── REFERENCE.md      # (or topic-specific: api-patterns.md, examples.md)
├── scripts/              # Executable code the agent runs
│   └── validate.sh       # (or helpers, extractors, validators)
└── assets/               # Static files: templates, schemas, data
    └── template.md       # (or schema.json, diagram.png)

When to create each folder:

Frontmatter Rules

Good description:

description: "Extracts text and tables from PDF files, fills PDF forms, merges PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction."

Bad description:

description: "Helps with PDFs."

Naming: prefer gerund form (processing-pdfs, testing-code); avoid vague (helper, utils) or generic (data, files) names. See naming conventions.

File Reference Rules

Use relative paths from the skill root, one level deep only, with forward slashes (never backslashes).

See [API reference](references/api-patterns.md) for details.
Run the validation script: scripts/validate.sh

❌ Never: references/sub/deep.md — nested chains break progressive disclosure.

**Skill Request Analysis**
**Name:** [kebab-case]
**Type:** [technique / reference / guardrail]
**Purpose:** [What problem does it solve?]
**Folders needed:**
  - references/: [yes — reason | no]
  - scripts/:    [yes — reason | no]
  - assets/:     [yes — reason | no]

Phase 2: Check for Existing Skills

ls -la .claude/skills/
find .claude/skills -name "SKILL.md" -exec head -3 {} \; -print

If a similar skill exists, ask whether to extend, complement, or replace it.

Phase 3: Delegate to skill-author

Spawn the skill-author subagent with full context:

"You are the skill-author for this session.

Task: Create this skill using TDD methodology.

**Request:** [full request text]
**Name:** [kebab-case]
**Type:** [technique / reference / guardrail]
**Location:** .claude/skills/[name]/

**Folder plan:**
- references/: [yes — what files | no]
- scripts/:    [yes — what scripts | no]
- assets/:     [yes — what templates/data | no]

Starter templates are in .claude/skills/skill/assets/:
  technique-template.md, reference-template.md, guardrail-template.md

The SKILL.md is a prompt — follow .claude/skills/skill/references/prompting-guide.md:
  right altitude (defaults + rationale, not if-else prose), calibrated language
  (reserve ALWAYS/NEVER for true invariants), canonical examples over rule lists,
  lean SKILL.md with depth in references/, completion defined by a checkable signal.

Apply the Agent Skills best practices (.claude/skills/skill/references/agent-skills-spec.md):
  - name: gerund form preferred; no XML tags; no reserved words (anthropic/claude)
  - description: third person, what + when, trigger keywords; no XML tags
  - file references: one level deep, forward slashes only
  - reference files >100 lines: add a ## Contents table of contents
  - scripts: solve-don't-punt, no voodoo constants, clear execute-vs-read intent, list deps
  - MCP tools: fully-qualified ServerName:tool_name

TDD process (evaluation-driven):
1. Baseline test WITHOUT the skill — record ≥3 representative failures verbatim
2. Write SKILL.md + populate folders addressing those failures
3. Test WITH the skill — verify fix; test across target models where feasible
4. Close loopholes, re-test

Return a <skill-author-result> block."

Wait for the <skill-author-result> block before proceeding.

Phase 4: Validate

bash .claude/skills/skill/scripts/validate-skill.sh .claude/skills/[skill-name]/
ls -la .claude/skills/[skill-name]/
wc -l .claude/skills/[skill-name]/SKILL.md

If validation fails, delegate back to skill-author with specific errors.

Phase 5: Report

## Skill Created ✅

**Location:** `.claude/skills/[name]/`
**Type:** [technique / reference / guardrail]
**Lines:** [SKILL.md line count]

**Structure:**
- `SKILL.md` ([n] lines)
- `references/[file]` — [purpose]  ← if created
- `scripts/[file]` — [purpose]     ← if created
- `assets/[file]` — [purpose]      ← if created

**Baseline failures addressed:**
1. [failure] → [fix]

**Activates when:** [paraphrase description trigger]

**Next steps:**
- [ ] Test with a real scenario to verify activation
- [ ] `git add .claude/skills/[name]/`

Resources

• Prompting Guide — The standard every SKILL.md is written against: altitude, calibrated language, canonical examples, lean SKILL.md, external completion
• Agent Skills Specification — Full spec reference
• Skill Templates — Annotated templates for all three types
• Starter templates: assets/technique-template.md, assets/reference-template.md, assets/guardrail-template.md
• Validation: scripts/validate-skill.sh <path-to-skill-dir>