Menu
Create SKILL.md files that teach the agent new domains. Use when authoring a new pi skill with frontmatter, body structure, and references.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Renders markdown to self-contained HTML with a custom dark stylesheet and opens in browser. Use when previewing markdown documents, generating styled HTML from README or report files.
Inform the user what is happening — skip passive lookups
Manage version control with Jujutsu (jj) — no staging area, immediate changes, smart rebasing. Use when navigating history, squashing, or pushing to Git remotes.
Programmatic hunk selection for Jujutsu — split, commit, or squash specific hunks without interactive prompts. Use when making partial commits or selective squashes.
Gather facts from the web using evidence-first approach with mandatory citations. Use when researching topics, answering factual questions, or any task requiring web-sourced evidence.
Model minimum-move problems as BFS over a state space. Use when solving bucket pouring puzzles, sliding tiles, or any problem asking for the shortest sequence of moves to reach a goal.
| name | skill-authoring |
| topic | Pi Skill Authoring |
| description | Create SKILL.md files that teach the agent new domains. Use when authoring a new pi skill with frontmatter, body structure, and references. |
| token_cost | 200 |
| keywords | ["skill","author","create","improve","domain"] |
Skills are Markdown files (SKILL.md) that teach the agent how to do something it doesn't know by default. Each skill covers one or more use cases within a single domain — e.g., "NixOS configuration management" with sub-areas for system updates, home manager, and package search. The agent loads the full file when the user's request matches the trigger description.
my-skill/
├── SKILL.md # Frontmatter + workflow instructions (keep under 120 lines)
├── references/ # Deep docs loaded on demand (API specs, advanced patterns)
└── scripts/ # Helper scripts the agent runs directly
Assets go in assets/ for templates and files the agent uses in outputs. Scripts in scripts/ are deterministic code — not rewritten each invocation.
Every skill requires name, description, and keywords. Additional fields depend on the skill type.
---
name: my-skill-name # kebab-case, matches directory name (max 64 chars)
description: "Does X. Use when Y."
keywords: ["keyword1", "keyword2", "keyword3"]
---
name: lowercase letters, numbers, hyphens only. No leading/trailing hyphens.description: quoted string. First sentence starts with a verb. Second starts with "Use when".keywords: array of single lowercase words used for scoring. Each word match scores 1.0 — you need at least 2 matches (score >= 2.0) for injection. Pick words users actually type. Avoid sharing keywords with other skills.Tool skills (in tools/ directory, name = tool name):
related: [other-skill] # co-inject related skills
Knowledge skills (domain knowledge):
topic: State-Space Search # required — display heading in injected block
token_cost: 120 # estimated token budget (default: 150)
requires_tools: [read, find] # tools needed before this skill fires
Protocol skills (behavioral rules):
topic: Conventional Commits # required — display heading in injected block
# Skill Name
One-line summary of the domain this skill covers.
## Workflow / Commands
Step-by-step examples or command reference with inline code snippets.
## Details
Common variations, edge cases, or tricky parts specific to this domain.
## Constraints / Best Practices
Rules, gotchas, and things the agent must do (or not do).
See [deep reference](references/DEEP.md) for API specs and advanced usage.
references/ for anything deep. One level of linking only.Good — focused domain, multiple use cases:
# nh: one domain (Nix operations), three sub-domains (system updates, home manager, package search)
description: "Switches NixOS/Home Manager configurations, cleans old generations, and performs system maintenance. Use when running os/home switch, pruning the Nix store, or managing system generations."
Good — single use case within a domain:
# transcribe-audio: one domain (audio transcription), one primary use case
description: "Transcribes audio files to text using whisper-cpp. Use when converting speech to text, transcribing podcasts, lectures, or meetings."
name is kebab-case and matches the directory name exactlydescription is a quoted string with verb-first sentence + "Use when..." clausekeywords are single lowercase words, at least 3 per skilltopic present for knowledge and protocol skillsrelated lists logically connected skills for co-injectionreferences/)> chevron instead of "quoted" — convert to quoted string