Skill Creator

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. 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:

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 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 for the full writing guide. Key points:

Frontmatter (Level 1 — always in context)

---
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):

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)

## Advanced Configuration

For database schema details, see [references/schema.md](references/schema.md).
For deployment patterns by provider, see:
- [references/aws.md](references/aws.md)
- [references/gcp.md](references/gcp.md)

The agent reads these files only when it needs them. This is progressive disclosure — keep SKILL.md lean, push detail into reference files.

Guidelines:

• Keep references one level deep from SKILL.md (no deeply nested links)
• For files over 100 lines, add a table of contents at the top
• Scripts can be executed without reading into context (token efficient)
• Assets are used in output, not loaded into context