espennilsen/pi / skills/skill-creator
skill-creator
VerifiedCreate, review, and improve skills for Pi agents. A skill is a folder with a SKILL.md that teaches an agent specialized workflows, domain knowledge, or tool integrations. Use when asked to create a new skill, improve an existing skill, review a skill for quality, scaffold a skill from a workflow, or convert documentation into a skill. Also triggers on "make a skill for", "build a skill", "skill for [topic]", "teach the agent to", or "package this workflow as a skill".
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:
- What does the user want to accomplish? (concrete outcome)
- What would they say to trigger it? (natural language phrases)
- What steps are involved? (the workflow)
- What does the agent need that it doesn't already know? (domain knowledge, scripts, reference docs)
- 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 namedescription: required, max 1024 chars, no XML angle brackets- No
claudeoranthropicin 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:
- Note where the agent struggles or goes off-track
- Tighten instructions for problem areas
- Add error handling for new edge cases
- Move content between SKILL.md and references as needed
- 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 (
--skillor 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:
skillsarray in settings.json - CLI:
--skill <path>(always loads, even with--no-skills) - Packages:
skills/dirs orpi.skillsin package.json
Skills register as /skill:name commands in interactive mode.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |