espennilsen/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:

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

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

## 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

Step 5: Validate

Run the validation script:

python3 scripts/validate.py <path/to/skill-folder>

Checks: frontmatter format, naming conventions, description quality, file structure, broken references, line count.

Step 6: Iterate

Skills are living documents. After real usage:

1. Note where the agent struggles or goes off-track
2. Tighten instructions for problem areas
3. Add error handling for new edge cases
4. Move content between SKILL.md and references as needed
5. Re-validate after changes

Review Mode

When asked to review an existing skill, evaluate against this checklist:

Triggering

• [ ] Description includes what + when + trigger phrases
• [ ] Tested: would the agent load this for the right queries?
• [ ] Tested: would it NOT load for unrelated queries?

Structure

• [ ] SKILL.md exists with valid frontmatter
• [ ] Name is kebab-case, matches folder name
• [ ] Body under 500 lines
• [ ] Progressive disclosure used (references for detail)
• [ ] No README.md or extraneous docs in the skill folder

Content Quality

• [ ] Only includes knowledge the agent doesn't already have
• [ ] Instructions are specific and actionable
• [ ] Error handling for common failures
• [ ] Concrete examples provided
• [ ] Scripts tested and working

Pi-Specific

• [ ] Relative paths use skill directory as root
• [ ] Compatible with Pi's skill loading (--skill or discovery)
• [ ] Works alongside other skills (composable)

Report findings as: 🔴 Critical | 🟡 Important | 🔵 Minor | ✅ Good

Common Mistakes

| Mistake | Fix | |---|---| | Description too vague ("Helps with projects") | Add specific triggers and capabilities | | Everything in SKILL.md (2000+ lines) | Move detail to references/, keep body lean | | Explaining things the agent already knows | Remove — only add novel domain knowledge | | No trigger phrases in description | Add "Use when..." with natural language examples | | Inline scripts in SKILL.md | Move to scripts/, reference with relative path | | Magic values without explanation | Document all constants, paths, credentials | | Missing error handling | Add "If X fails..." for each critical step | | README.md in the skill folder | Delete — all docs go in SKILL.md or references |

Pi Skill Locations

Skills are discovered from these locations (first match wins on name collision):

• Global: ~/.pi/agent/skills/, ~/.agents/skills/
• Project: .pi/skills/, .agents/skills/ (cwd + ancestors to git root)
• Settings: skills array in settings.json
• CLI: --skill <path> (always loads, even with --no-skills)
• Packages: skills/ dirs or pi.skills in package.json

Skills register as /skill:name commands in interactive mode.