skill-creator

Files (7)

• SKILL.md
• claude-code-extensions.md · references/
• design-principles.md · references/
• output-patterns.md · references/
• skill-patterns.md · references/
• workflow-patterns.md · references/
• quick_validate.py · scripts/

SKILL.md (first lines)

# Create a New Skill

Guide the user through creating a new agent skill following the [Agent Skills specification](https://agentskills.io/specification). Follow each step in order.

## Step 1: Understand the Skill

Gather requirements before writing anything.

**Ask the user:**
1. What should this skill do? (one sentence)
2. When should an agent use it? (trigger phrases users would say)
3. What tools does the skill need? (Read, Grep, Glob, Bash, Task, WebFetch, etc.)
4. Where should the skill live? (which plugin or directory)

**Determine the skill name:**
- Lowercase letters, digits, and hyphens only (`a-z`, `0-9`, `-`)
- 1-64 characters; must not start or end with `-`; no consecutive hyphens (`--`)
- Descriptive and unique among existing skills
- Prefer action-oriented names: `processing-pdfs`, `fix-issue`, `code-review`
- Check the target skills directory to avoid name collisions

**Choose a complexity tier:**

| Tier | Structure | Use When |
|------|-----------|----------|
| **Simple** | `SKILL.md` only | Self-contained instructions under ~200 lines |
| **With references** | `SKILL.md` + `references/` | Domain knowledge that agents load conditionally |
| **With scripts** | `SKILL.md` + `scripts/` | Workflow automation needing Python scripts |
| **Full** | All of the above | Complex skills with automation and domain knowledge |

Read `${CLAUDE_SKILL_ROOT}/references/design-principles.md` for guidance on keeping skills focused and concise.

## Step 2: Plan the Skill

Analyze how each use case would be executed from scratch. Identify what reusable resources would help when executing these tasks repeatedly.

For each concrete example, ask:
1. What code would be rewritten every time? → candidate for `scripts/`
2. What documentation is needed to inform decisions? → candidate for `references/`
3. What templates or assets are used in output? → candidate for `assets/`

Example analysis:
- "Rotate a PDF" → rotating requires rewriting the same code → `scripts/rotate_pdf.py`
- "Query BigQuery metrics" → need table schemas each time → `references/schema.md`
- "Build a frontend app" → same boilerplate HTML/React → `assets/hello-world/`

## Step 3: Study Existing Skills

Before writing, study 1-2 existing skills that match the chosen tier. Look for skills in the target repository or plugin to understand local conventions.

Read `${CLAUDE_SKILL_ROOT}/references/skill-patterns.md` for concrete examples of each tier.

Also read `CLAUDE.md` (or `AGENTS.md`) at the repository root for repo-specific conventions that the skill should follow.

## Step 4: Write the SKILL.md

Create `<skill-directory>/<name>/SKILL.md`.

### Frontmatter

The YAML frontmatter **must** be the first thing in the file. No comments or blank lines before `---`.

```yaml
---
name: <skill-name>
description: <what it does>. Use when <trigger phrases>. <key capabilities>.
---
```

**Required fields:**
- `name` — must match the directory name exactly
- `description` — up to 1024 chars, no angle brackets (`<` or `>`); include trigger keywords that help agents match user intent

**Optional fields:**
- `allowed-tools` — comma-separated list (e.g., `Read, Grep, Glob, Bash`); omit to allow all tools
- `license` — license name or path (add when vendoring external content)
- `metadata` — arbitrary key-value mapping for additional metadata
- `compatibility` — environment requirements (max 500 chars); most skills don't need this

For Claude Code-specific fields (`argument-hint`, `disable-model-invocation`, `context`, etc.), read `${CLAUDE_SKILL_ROOT}/references/claude-code-extensions.md`.

### Description Guidelines

The description is the **primary trigger mechanism** — it determines when agents activate the skill. All "when to use" information belongs here, not in the body.

**Write in third person:**
- Good: "Processes Excel files and generates reports. Use when..."
- Bad: "I can help you process Excel files" or "You can use this to..."

**Include natural trigger phrases:**
```yaml
# Good — specific triggers users would actually say
description: Security code review for vulnerabilities. Use when asked to "security review", "find vulnerabilities", "check for security issues", "audit security".

# Bad — too vague, no trigger phrases
description: A helpful skill for code quality.
```

**Pattern:** `<What it does>. Use when <trigger phrases>. <Key capabilities>.`

### Body Guidelines

Write the body in **imperative voice** — these are instructions, not documentation.

| Do | Don't |
|----|-------|
| "Read the file and extract..." | "This skill reads the file and extracts..." |
| "Report only HIGH confidence findings" | "The agent should report only HIGH confidence findings" |
| "Ask the user which option to use" | "You may want to ask the user..." |

**Structure:**
1. Start with a one-line summary of what the skill does
2. Organize steps with `## Step N: Title` headings
3. Use tables for decision logic and mappings
4. Include concrete examples of expected output
5. End with validation criteria or exit conditions

For workflow and output patterns, read:
- `${CLAUDE_SKILL_ROOT}/references/workflow-patterns.md` — sequential workflows, feedback loops, plan-validate-execute

From HazAT/pi-config, MIT.

More from HazAT/pi-config