| name | writing-skills |
| description | Use when creating, editing, pruning, splitting, merging, or testing agent skills. Use when deciding skill frontmatter, model-vs-user invocation, description triggers, supporting files, pressure scenarios, or whether a skill should exist. |
Writing Skills
Overview
Core principle: writing skills is TDD for process documentation. A skill should make agent behavior predictable: the same process every run, even when outputs differ.
If you did not watch an agent fail without the skill, you do not know what the skill needs to teach. If you edit a skill without re-testing the behavior, you are guessing.
The Iron Law
NO SKILL CREATION OR EDIT WITHOUT A FAILING TEST FIRST.
This applies to new skills, edits, rewrites, pruning, splitting, merging, and “just documentation cleanup”.
No exceptions:
- Do not add “obvious” guidance without a pressure scenario.
- Do not keep untested text as “reference”.
- Do not batch multiple skills before verifying each one.
- If you wrote the skill before RED, delete it and start over.
What a Skill Is
A skill is reusable operational guidance: a technique, pattern, workflow, or reference that future agents should apply across tasks.
Skills are not:
- one-off session notes;
- project conventions better placed in
AGENTS.md / CLAUDE.md;
- mechanical checks better enforced by scripts, linters, hooks, or validation;
- essays explaining why something matters without changing agent behavior.
RED-GREEN-REFACTOR
RED — prove the default failure
Write pressure scenarios before editing. Run them without the skill, or with the current skill if editing. Capture exact bad behavior and rationalizations.
Good pressure scenarios combine forces:
- time pressure: “quickly”, “before EOD”, “hotfix”;
- authority pressure: “the user says just do it”;
- sunk cost: “you already wrote code/docs”;
- ambiguity: unclear triggers, vague success criteria;
- tempting shortcut: inspection, summary, mock, broad cleanup, unsupported field.
RED is valid only if the agent actually fails. “This guidance would be nice” is not RED.
GREEN — minimal skill text
Write the smallest text that addresses the observed failure. Put the important instruction where the agent will see it before the failure point.
Then run the same scenarios with the skill loaded. The agent must now behave correctly under the same pressure.
REFACTOR — close loopholes and prune
If the agent finds a new rationalization, add the counter and re-test. If a line did not change behavior in tests, delete it. Skills rot by accumulation.
Testing Different Skill Types
| Skill type | Test with | Success means |
|---|
| Discipline / rule | Pressure scenarios with temptation to violate | Agent follows the rule under pressure |
| Technique | Application scenarios and variants | Agent applies the technique correctly |
| Pattern / mental model | Recognition + counter-examples | Agent knows when to apply and when not to |
| Reference | Retrieval + application | Agent finds and uses the right fact/API |
Testing can be done with a subagent, a fresh model session, or a forced system-prompt run. Record the prompt, model, and output. Do not rely on your own reading of the skill.
Frontmatter and Invocation
Required fields:
---
name: skill-name
description: Use when [specific trigger conditions]
---
Rules:
name: lowercase letters, numbers, hyphens; max 64 chars.description: max 1024 chars.- Optional Pi-supported fields include
disable-model-invocation, license, compatibility, metadata, and allowed-tools.
Model-invoked skills
Default mode. The model sees the description and may load the skill autonomously. This spends context load every session.
Use when:
- the agent must discover the skill on its own;
- another skill must be able to reach it;
- the trigger is common enough to justify always-visible metadata.
Description rules:
- describe when to use, not the workflow;
- start with “Use when…”;
- include concrete triggers, symptoms, and synonyms;
- do not summarize steps — agents may follow the description and skip the body.
Bad:
description: Use for TDD — write a failing test, implement minimal code, refactor, run review.
Good:
description: Use when implementing features, fixing bugs, refactoring, or changing production code before writing implementation.
User-invoked skills
Manual-only. Hide from model discovery:
---
name: release-checklist
description: Manual release checklist
disable-model-invocation: true
---
Use when the human will explicitly run /skill:name. Do not write rich trigger descriptions for manual-only skills. If there are many manual-only skills and the user forgets names, create one model-invoked router skill instead of making everything model-invoked.
Skill Granularity
Every split spends a cost:
- more model-invoked skills → more context load and false triggers;
- more user-invoked skills → more human cognitive load.
Split only for one of two reasons:
- Invocation split: a branch has its own distinct trigger and should be discoverable on its own.
- Sequence split: later steps tempt the agent to prematurely complete earlier steps; hiding them improves compliance.
Do not split just because a file is long. First prune sediment and duplication.
Information Hierarchy
Put content where the agent needs it:
- Inline in
SKILL.md: non-negotiable rules, common-path steps, decision points needed before choosing a path, failure modes proven by tests.
- Supporting file: branch-specific heavy reference, API docs, long examples, or reusable tools needed only after a clear gate.
- Delete: rationale, history, duplicate examples, obvious advice, stale notes, no-op prose.
A weak link is not enough:
Bad: See advanced.md for details.
Good: If changing retry behavior, read advanced.md before proposing a fix.
If agents skip a supporting file and fail, either inline the minimum decision rule or strengthen the gate and re-test. Do not inline everything by default; giant skills also fail.
Skill Structure
skills/
skill-name/
SKILL.md
optional-reference.md
optional-script.sh
SKILL.md should contain:
- overview / core principle;
- when to use and when not to use;
- required process with checkable completion criteria;
- quick reference or decision table;
- common mistakes / rationalizations;
- supporting-file gates, if any.
Use one excellent example, not five mediocre ones. Prefer executable examples over narrative examples.
Writing Pressure Scenarios
A pressure scenario should ask the agent to do the wrong thing attractively.
Template:
You are [task context]. The user says “[pressure / shortcut]”.
You have [missing condition]. What do you do next?
Examples:
- “The user says just patch the likely culprit. You have not reproduced the bug.”
- “The user asks to clean up this file while you are adding one parameter.”
- “The skill is manual-only but has a rich trigger description.”
- “The supporting file is skipped; what wrong decision follows?”
Capture the exact failure. Put the rationalization into the skill only if it recurs or is high-risk.
Common Mistakes
| Mistake | Fix |
|---|
| Writing a skill from taste | Run RED first |
| Description summarizes workflow | Rewrite as trigger-only |
| Manual-only skill has rich triggers | Add disable-model-invocation: true |
| Supporting file contains required common-path rules | Inline the rules |
| Supporting file is branch-specific | Add an explicit load gate |
| Skill keeps growing | Prune no-ops, duplication, and stale sediment |
| Many tiny skills | Add a router or merge unless triggers differ |
| One giant multi-workflow skill | Split by invocation or sequence |
| Flowchart for linear steps | Use a numbered list |
| Multiple examples of same pattern | Keep the best one |
Deployment Checklist
For each skill, one at a time:
- RED: pressure scenario run without skill/current skill; failure captured.
- GREEN: minimal skill change addresses that failure.
- RE-TEST: same scenario passes with skill loaded.
- REFACTOR: loopholes closed; no untested additions kept.
- QUALITY: frontmatter valid; description matches invocation mode; supporting files gated or deleted.
- CLEANUP: no stale references, no unsupported fields, no narrative session history.
- SHIP: commit and push if this repo uses git.
Bottom Line
A skill is not a place to store wisdom. It is a behavioral intervention. If it does not change what the next agent does under pressure, delete it.
