skill-creator

Files (5)

• SKILL.md
• patterns.md · references/
• writing-guide.md · references/
• init-skill.sh · scripts/
• validate.py · scripts/

SKILL.md (first lines)

# Skill Creator

Create effective, well-structured skills for Pi agents. This skill covers the
full lifecycle: planning, scaffolding, writing, validating, and iterating.

Pi implements the [Agent Skills standard](https://agentskills.io/specification).
Skills work across Pi, Claude Code, and the Anthropic API.

## What Is a Skill?

A skill is a folder that teaches an agent how to handle specific tasks:

```
skill-name/
├── SKILL.md           # Required — frontmatter + instructions
├── scripts/           # Optional — executable code (deterministic operations)
├── references/        # Optional — documentation loaded on-demand
└── assets/            # Optional — templates, fonts, icons used in output
```

**Skills are NOT code.** They are structured instructions — like an onboarding
guide for a new team member who happens to be an AI.

## Skill Creation Process

### Step 1: Understand the Use Case

Before writing anything, answer these questions:

1. **What does the user want to accomplish?** (concrete outcome)
2. **What would they say to trigger it?** (natural language phrases)
3. **What steps are involved?** (the workflow)
4. **What does the agent need that it doesn't already know?** (domain knowledge, scripts, reference docs)
5. **What tools does the agent need?** (bash, web_fetch, extensions, MCP)

Ask 2-3 clarifying questions if the use case isn't clear. Get concrete examples
of how the skill would be used before proceeding.

### Step 2: Plan the Skill Contents

For each step in the workflow, decide what belongs where:

| Content type | Where it goes | When to use |
|---|---|---|
| Workflow steps, decisions, guidance | SKILL.md body | Core instructions the agent follows |
| Executable code that's reused | `scripts/` | Deterministic operations, data processing, validation |
| Detailed docs, API refs, schemas | `references/` | Loaded only when the agent needs them |
| Templates, images, boilerplate | `assets/` | Files used in output, not loaded into context |

**Key principle:** Only include what the agent doesn't already know. Claude is
already smart — don't explain how to write Python or use git. Add the domain
knowledge, specific workflows, and tribal knowledge that make this task unique.

### Step 3: Scaffold the Skill

Run the init script to create the directory structure:

```bash
bash scripts/init-skill.sh <skill-name> [target-directory]
```

Default target: current working directory. The script creates the folder with
SKILL.md template and optional subdirectories.

### Step 4: Write the SKILL.md

See [references/writing-guide.md](references/writing-guide.md) for the full
writing guide. Key points:

#### Frontmatter (Level 1 — always in context)

```yaml
---
name: kebab-case-name
description: >
  What it does + when to use it + specific trigger phrases.
  Max 1024 chars. This is the ONLY thing loaded by default.
---
```

The description is the most important part — it determines whether the skill
activates. Include:
- What the skill does (1 sentence)
- When to use it (specific scenarios)
- Trigger phrases users would actually say

**Rules:**
- `name`: kebab-case, lowercase, max 64 chars, must match folder name
- `description`: required, max 1024 chars, no XML angle brackets
- No `claude` or `anthropic` in the name (reserved)

#### Body (Level 2 — loaded when skill activates)

Keep SKILL.md body **under 500 lines / ~5000 words**. This goes into the
agent's context window alongside conversation history, other skills, and
system prompt.

Structure options (pick the best fit):

| Pattern | Best for | Example |
|---|---|---|
| **Workflow** | Sequential processes | Steps 1→2→3 with validation gates |
| **Task-based** | Tool collections | "Merge PDFs" / "Split PDFs" / "Extract text" |
| **Reference** | Standards, guidelines | Brand guide with colors / typography / voice |
| **Capabilities** | Feature sets | Numbered list of related features |

**Writing rules:**
- Use imperative form ("Run the script", not "You should run the script")
- Be specific and actionable (file paths, commands, parameters)
- Include error handling for common failures
- Provide concrete examples over abstract explanations
- Reference bundled files with relative paths: `scripts/validate.sh`, `references/api.md`

#### Bundled Resources (Level 3 — loaded on demand)

```markdown
## Advanced Configuration

For database schema details, see [references/schema.md](references/schema.md).

From espennilsen/pi, MIT.

More from espennilsen/pi