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".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.1 KB |
| references/patterns.md | markdown | 6.6 KB |
| references/writing-guide.md | markdown | 9.6 KB |
| scripts/init-skill.shexecutable | script | 2.5 KB |
| scripts/validate.pyexecutable | script | 8.0 KB |
references/writing-guide.md
View on GitHub# Skill Writing Guide
Detailed guidance for writing effective SKILL.md files. Read this when you need
to write or significantly revise a skill.
## Table of Contents
- [The Description Field](#the-description-field)
- [Body Structure Patterns](#body-structure-patterns)
- [Progressive Disclosure](#progressive-disclosure)
- [Degrees of Freedom](#degrees-of-freedom)
- [Scripts vs Instructions](#scripts-vs-instructions)
- [Working with References](#working-with-references)
- [Working with Assets](#working-with-assets)
- [Anti-Patterns](#anti-patterns)
- [Examples](#examples)
## The Description Field
The description is the single most important piece of a skill. It's the ONLY
content always in the agent's system prompt — everything else loads on demand.
### Structure
```
[What it does] + [When to use it] + [Key capabilities/file types]
```
### Good Descriptions
```yaml
# Specific, actionable, includes triggers
description: >
Analyzes Figma design files and generates developer handoff documentation.
Use when user uploads .fig files, asks for "design specs", "component
documentation", or "design-to-code handoff".
# Includes trigger phrases users would actually say
description: >
Manages Linear project workflows including sprint planning, task creation,
and status tracking. Use when user mentions "sprint", "Linear tasks",
"project planning", or asks to "create tickets".
# Clear value prop with file types
description: >
Extracts text and tables from PDF files, fills PDF forms, and merges
multiple PDFs. Use when working with PDF documents.
```
### Bad Descriptions
```yaml
# Too vague — won't trigger correctly
description: Helps with projects.
# Missing triggers — agent doesn't know WHEN to use it
description: Creates sophisticated multi-page documentation systems.
# Too technical, no user context
description: Implements the Project entity model with hierarchical relationships.
```
### Testing Your Description
Ask the agent: "When would you use the [skill-name] skill?" It will quote the
description back. If the answer doesn't match your intent, revise.
### Negative Triggers
For skills that might over-trigger, add exclusions:
```yaml
description: >
Advanced data analysis for CSV files. Use for statistical modeling,
regression, clustering. Do NOT use for simple data exploration or
basic charting (those don't need this skill).
```
## Body Structure Patterns
### Pattern 1: Workflow (sequential processes)
Best for multi-step procedures with a specific order.
```markdown
## Workflow
### Step 1: Validate Input
Run `scripts/validate.sh` to check format.
If validation fails, report the specific error.
### Step 2: Process Data
[Instructions with decision points]
### Step 3: Generate Output
[Instructions with quality checks]
```
Key techniques: explicit step ordering, dependencies between steps, validation
at each stage, rollback instructions for failures.
### Pattern 2: Task-Based (tool collections)
Best when the skill offers different independent operations.
```markdown
## Quick Start
[Most common operation]
## Merge PDFs
[Steps for merging]
## Split PDFs
[Steps for splitting]
## Extract Text
[Steps for extraction]
```
### Pattern 3: Decision Tree (conditional workflows)
Best when the approach depends on context.
```markdown
## Determine Approach
1. Check the input type:
- **PDF file** → Follow "PDF Processing" below
- **Image file** → Follow "Image Processing" below
- **Text file** → Handle directly, no special processing
## PDF Processing
[Steps]
## Image Processing
[Steps]
```
### Pattern 4: Iterative Refinement
Best when output quality improves with iteration.
```markdown
## Generate Draft
1. Create initial output
2. Save to temporary location
## Quality Check
1. Run `scripts/check.py`
2. Review against criteria:
- [ ] All sections present
- [ ] No placeholder text
- [ ] Data validated
## Refine
1. Address each issue
2. Re-run quality check
3. Repeat until passing
```
## Progressive Disclosure
The three-level system minimizes context window usage:
| Level | Content | Size target | Loaded when |
|---|---|---|---|
| 1. Frontmatter | name + description | ~100 words | Always |
| 2. SKILL.md body | Core instructions | <500 lines / <5000 words | Skill triggers |
| 3. Bundled files | Detail, scripts, assets | Unlimited | Agent decides |
### When to Split Content
Move content from SKILL.md to references when:
- SKILL.md exceeds 500 lines
- A section is only relevant to specific sub-tasks
- Detailed API docs, schemas, or specifications
- Framework-specific variations (aws.md, gcp.md, azure.md)
- Content that's useful 20% of the time
### Linking to References
Always explain WHAT the reference contains and WHEN to read it:
```markdown
## Database Operations
For simple queries, use the patterns below.
For complex joins and aggregations, see
[references/advanced-queries.md](references/advanced-queries.md) which covers
window functions, CTEs, and performance optimization.
```
Bad (no context for when to read it):
```markdown
See [references/stuff.md](references/stuff.md) for more information.
```
### Reference File Structure
For files over 100 lines, add a table of contents:
```markdown
# API Reference
## Table of Contents
- [Authentication](#authentication)
- [Endpoints](#endpoints)
- [Error Codes](#error-codes)
- [Rate Limits](#rate-limits)
## Authentication
...
```
## Degrees of Freedom
Match instruction specificity to the task's fragility:
### High Freedom (guidelines)
When multiple approaches work and context varies:
```markdown
## Writing Style
- Keep paragraphs short (2-4 sentences)
- Use active voice
- Adapt tone to the audience
```
### Medium Freedom (patterns with parameters)
When a preferred approach exists but variation is acceptable:
```markdown
## File Naming
Use the pattern: `YYYY-MM-DD-{slug}.md`
The slug should be lowercase, hyphenated, derived from the title.
```
### Low Freedom (exact scripts)
When operations are fragile, error-prone, or must be consistent:
```markdown
## Rotate PDF
Run exactly:
\`\`\`bash
python3 scripts/rotate_pdf.py --input {file} --degrees {angle} --output {output}
\`\`\`
Do not attempt to rotate PDFs any other way.
```
**Rule of thumb:** Use high freedom for creative tasks, low freedom for
data-sensitive or destructive operations.
## Scripts vs Instructions
### When to Use Scripts
- Same code rewritten every time → put in `scripts/`
- Operation must be deterministic (data processing, validation)
- Complex logic that's error-prone in natural language
- Performance-sensitive operations
### When to Use Instructions
- Context-dependent decisions
- Creative or judgment-based tasks
- Simple operations the agent can do inline
- One-off operations that vary each time
### Script Best Practices
```python
#!/usr/bin/env python3
"""
Brief description of what this script does.
Usage:
python3 scripts/process.py --input <file> --output <dir>
"""
# Scripts should be self-documenting with --help
# Include error handling and clear exit codes
# Test before including in the skill
```
Scripts can be executed WITHOUT loading into context — they're token-efficient.
But the agent may read them for understanding or patching.
## Working with References
### Good Reference Candidates
- API documentation (endpoints, parameters, auth)
- Database schemas (tables, relationships, types)
- Domain knowledge (policies, regulations, standards)
- Detailed workflow guides (only needed for complex cases)
- Framework-specific patterns (one file per framework)
### Bad Reference Candidates (keep in SKILL.md instead)
- Core workflow steps (the main thing the skill does)
- Critical warnings or gotchas
- Decision trees for choosing approach
- Configuration the agent always needs
## Working with Assets
Assets are files used in output — NOT loaded into context.
### Good Asset Candidates
- Document templates (.docx, .pptx, .xlsx)
- Boilerplate project directories
- Images, icons, logos
- Font files
- Sample data for testing
### Using Assets in Instructions
```markdown
## Create Report
1. Copy the template from `assets/report-template.docx`
2. Fill in the sections using the gathered data
3. Save to the output directory
```
## Anti-Patterns
### The Knowledge Dump
❌ Putting everything the agent could possibly need into SKILL.md
✅ Only include what the agent doesn't already know. Challenge each paragraph:
"Does this justify its token cost?"
### The README Trap
❌ Including README.md, CHANGELOG.md, INSTALLATION_GUIDE.md
✅ A skill is for the agent, not humans. All docs go in SKILL.md or references.
### The Inline Script
❌ 200-line code blocks inside SKILL.md
✅ Move to `scripts/`, reference with: `Run scripts/process.py`
### The Vague Description
❌ `description: Helps with data processing`
✅ Include WHAT + WHEN + trigger phrases
### Over-Explaining the Obvious
❌ "Git is a version control system. To commit changes, use `git commit`..."
✅ Skip what the agent already knows. Focus on YOUR specific conventions.
## Examples
### Minimal Skill (guidelines only)
```
code-style/
└── SKILL.md
```
```yaml
---
name: code-style
description: >
Enforce team coding standards for TypeScript projects. Use when writing
or reviewing TypeScript code, or when asked about code style.
---
```
### Medium Skill (workflow + script)
```
pdf-forms/
├── SKILL.md
└── scripts/
├── analyze_form.py
└── fill_form.py
```
### Full Skill (all resource types)
```
design-system/
├── SKILL.md
├── scripts/
│ └── extract_tokens.py
├── references/
│ ├── color-theory.md
│ └── wcag-guidelines.md
└── assets/
└── swatch-template.svg
```
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: 471k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |