---
name: skill-create
description: Creates new agent skills following the agentskills.io specification. Use when the user wants to design, draft, or refine a skill — including structuring SKILL.md frontmatter, organizing supporting directories, and applying best practices for scope, calibration, and progressive disclosure.
metadata:
  author: pi-local
  version: "1.0"
---

# Skill Creator

Creates new agent skills that follow the [agentskills.io specification](https://agentskills.io/specification).

## Specification requirements

Every skill is a directory containing a `SKILL.md` file with YAML frontmatter:

```
skill-name/
├── SKILL.md          # Required: frontmatter + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: detailed docs loaded on demand
└── assets/           # Optional: templates, static resources
```

### Frontmatter fields

| Field | Required | Rules |
|-------|----------|-------|
| `name` | Yes | 1–64 chars, lowercase + hyphens only, no leading/trailing/consecutive hyphens, must match directory name |
| `description` | Yes | 1–1024 chars. Describe **what** the skill does AND **when** to use it. Include keywords agents will match on. |
| `license` | No | License name or reference to bundled file |
| `compatibility` | No | 1–500 chars. Environment requirements (tools, network, OS) |
| `metadata` | No | Arbitrary key-value string map |
| `allowed-tools` | No | Space-separated pre-approved tools (experimental) |

### Size constraints

- `SKILL.md` body: **under 500 lines / <5000 tokens**
- Move detailed reference material to `references/` — tell the agent *when* to load each file
- Frontmatter (name + description) loads at startup; body loads on activation; resources load on demand

## Workflow

### 1. Gather domain context

**Do not generate a skill from generic LLM knowledge alone.** Ask the user for:

- **A real task they completed** — extract the steps that worked, corrections they made, input/output formats
- **Existing artifacts** — runbooks, style guides, API specs, code review comments, incident reports, version control history
- **Gotchas** — environment-specific facts that defy reasonable assumptions (e.g., "users table uses soft deletes, always filter `WHERE deleted_at IS NULL`")

If the user has no artifacts, walk through a real task with them first, then extract the pattern.

### 2. Define scope

- **One coherent unit of work** — not too narrow (forces multiple skills to load) and not too broad (hard to activate precisely)
- **Ask:** "Would the agent get this wrong without this skill?" If no, the skill may not be needed.
- **Ask:** "Can multiple valid approaches work here?" If yes, give the agent freedom. If the task is fragile, be prescriptive.

### 3. Create the skill directory

```bash
mkdir -p <scope-path>/<skill-name>
```

Scope paths:
- Project: `.pi/skills/<skill-name>/`
- User: `~/.pi/skills/<skill-name>/`
- Package: `<package>/skills/<skill-name>/`

The directory name **must match** the `name` field in frontmatter.

### 4. Write SKILL.md

Follow these principles when drafting the body:

#### Add what the agent lacks, omit what it knows
Don't explain what a PDF is, how HTTP works, or what a database migration does. Focus on project-specific conventions, non-obvious edge cases, and particular tools/APIs to use.

#### Provide defaults, not menus
```markdown
# Bad: Too many options
You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...

# Good: Clear default with escape hatch
Use pdfplumber for text extraction. For scanned PDFs, use pdf2image with pytesseract.
```

#### Favor procedures over declarations
Teach *how to approach* a class of problems, not *what to produce* for one instance.

#### Include a gotchas section
The highest-value content in many skills. Concrete corrections to mistakes the agent will make without being told:

```markdown
## Gotchas
- The user ID is `user_id` in the DB, `uid` in auth, `accountId` in billing.
- The `/health` endpoint returns 200 even if the DB is down. Use `/ready`.
```

#### Use templates for output format
Agents pattern-match well against concrete structures. Short templates inline; long ones in `assets/`.

#### Use checklists for multi-step workflows
Helps the agent track progress and avoid skipping steps with dependencies.

#### Include validation loops
Do the work → run a validator → fix issues → repeat until validation passes.

### 5. Create supporting files (if needed)

- `scripts/` — self-contained executable code with helpful error messages
- `references/` — focused docs loaded on demand (e.g., "Read `references/api-errors.md` if the API returns non-200")
- `assets/` — templates, schemas, lookup tables

Keep file references **one level deep** from `SKILL.md`.

### 6. Validate

Check against the spec:

- [ ] `name` field matches directory name
- [ ] `name` is lowercase + hyphens, no leading/trailing/consecutive hyphens
- [ ] `description` describes what AND when to use (with keywords)
- [ ] `SKILL.md` body is under 500 lines
- [ ] No generic explanations the agent already knows
- [ ] Gotchas section included if there are non-obvious traps
- [ ] References tell the agent *when* to load them

### 7. Refine with real execution

The first draft usually needs refinement. Run the skill against a real task, then ask:

- What triggered false positives?
- What was missed?
- What could be cut?
- Did the agent waste time on unproductive steps? (Usually caused by: instructions too vague, instructions that don't apply, too many options without a clear default)

Read agent execution traces, not just final outputs. Even a single pass of execute-then-revise noticeably improves quality.

## Calibration guide

Match the specificity of instructions to the fragility of the task:

| Situation | Approach |
|-----------|----------|
| Multiple valid approaches, task tolerates variation | Give freedom, explain *why* |
| Fragile operations, consistency matters | Be prescriptive, give exact commands |
| Output format matters | Provide a template |
| Multi-step with dependencies | Use a checklist |
| Destructive/batch operations | Use plan-validate-execute pattern |

## Common pitfalls

- **Vague instructions** — "handle errors appropriately" → agent tries several approaches before finding one that works
- **Too comprehensive** — covering every edge case hurts more than helps; let the agent handle most with its own judgment
- **Generic knowledge** — skills synthesized from general training data instead of real project context
- **No refinement** — shipping the first draft without running it against real tasks
- **Overly broad scope** — "database querying AND database administration" is two skills
- **Deep reference chains** — keep file references one level deep from SKILL.md