Skip to content

espennilsen/pi / skills/skill-creator

skill-creator

Verified

Create, 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:

  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 typeWhere it goesWhen to use
Workflow steps, decisions, guidanceSKILL.md bodyCore instructions the agent follows
Executable code that's reusedscripts/Deterministic operations, data processing, validation
Detailed docs, API refs, schemasreferences/Loaded only when the agent needs them
Templates, images, boilerplateassets/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):

PatternBest forExample
WorkflowSequential processesSteps 1→2→3 with validation gates
Task-basedTool collections"Merge PDFs" / "Split PDFs" / "Extract text"
ReferenceStandards, guidelinesBrand guide with colors / typography / voice
CapabilitiesFeature setsNumbered 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

MistakeFix
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 knowsRemove — only add novel domain knowledge
No trigger phrases in descriptionAdd "Use when..." with natural language examples
Inline scripts in SKILL.mdMove to scripts/, reference with relative path
Magic values without explanationDocument all constants, paths, credentials
Missing error handlingAdd "If X fails..." for each critical step
README.md in the skill folderDelete — 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.

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: 466kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexUnverifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall