write-skill

Create compact skills under skills/<name>/ that load only the behavior needed at invocation time.

Workflow

1. Clarify only missing essentials: capability, triggers, non-triggers, tool/script needs, and portability.
2. Read every description in catalog.json. If a skill already owns the capability, extend it instead. Otherwise pick a unique kebab-case name; where another skill's triggers could also fire, add Do NOT use ... (use <other>) to both descriptions.
3. Draft SKILL.md as an operator card: what to run, when to run it, what output means, what traps matter. End each step with a checkable completion criterion.
4. Add helper files only when they remove repeated deterministic work.
5. Compress once; add one README row; do not commit unless asked.

Template

---
name: <kebab-case>
description: <Concrete capability.> Use when <real phrases, file types, tools, or contexts>. Do NOT use <negative triggers if broad>.
---

# <name>

<One-line operational contract.>

## Usage / Commands / Routing

```bash
scripts/tool_or_helper.py <arg>
```

## Notes

- <What output shape means, or how to consume it.>
- <Hard rule, setup failure, safety boundary, or common mistake.>

Description

The description is the routing surface; optimize it first.

• Use 1-3 sentences, third person, present tense.
• Sentence 1 names the concrete capability.
• Sentence 2 starts with Use when ... and lists actual trigger phrases, file types, tools, or contexts.
• Add Do NOT use ... for broad domains such as review, search, docs, macOS, git, or browser work.
• Avoid marketing words, time-sensitive claims, and duplicate "this skill should be used when" phrasing.
• State triggers, never a workflow summary: agents follow a summarized flow in the description and skip the body.
• Keep the trigger nouns users actually say (product, tool, action, object); cut the rest. Codex gives the whole skill list 2% of the context window and truncates every description equally when it overflows.

Body

Keep:

• runnable commands or exact workflow steps;
• setup checks that commonly block first use;
• compact output contracts;
• routing boundaries and safety pitfalls;
• one strong example per command or concept (several invite pattern-matching instead of understanding).

Match the form to the failure the skill fixes:

Delete:

• overview prose that restates the description;
• installation/contributing/privacy/troubleshooting sections unless they change agent behavior;
• copied CLI help, schemas, flag catalogs, or generated docs;
• repeated prompt examples and canned analyses;
• detail already present in README, references, or helper scripts.

Tool Skills

• Put deterministic work in scripts/ or the existing executable.
• Make SKILL.md a menu of invocations plus output shape and gotchas.
• Use Run <tool> --help for all flags; keep only non-obvious flags.
• Prefer 30-60 lines. If setup is long, keep the readiness check inline and move walkthroughs one hop away.

Workflow Skills

• Keep the lens, decision order, and output contract.
• Avoid rigid full templates unless structure is the skill's core value.
• Findings should lead for review skills; summaries and praise are optional.
• Split philosophy, examples, and source notes into references/REFERENCE.md. Keep examples inline when the example is the instruction, as in an output-shape skill.
• For a skill that orchestrates subagents, claims coverage, or emits a report artifact, read references/heavyweight-workflow-patterns.md for mode gating, verdict tiers, coverage ledgers, and fail-loud terminal states. Not needed otherwise.

Targeting

Shared skills target Codex, Claude Code, and Pi. Keep task knowledge, acceptance criteria, and executable helpers shared. Prefer existing CLIs for repeatable operations. Isolate harness-specific behavior only where required, and declare its dependency explicitly. Do not prescribe another harness's tool names, subagent APIs, or compaction mechanism.

Keep names/descriptions brief and task-specific. Model-specific corrections belong in local settings or a relevant reference, supported by an observed failure rather than a universal rule. Use detailed sequences where order or safety matters; otherwise describe the outcome and boundaries.

When the user chooses explicit-only activation, use disable-model-invocation: true in frontmatter for Claude/Pi and policy.allow_implicit_invocation: false in agents/openai.yaml for Codex. Preserve existing metadata and local overrides. Invocation controls do not grant action permissions. Keep automatically useful operational skills discoverable; require approval at the actual restricted action.

Cross-skill pointers: a negative one (Do NOT use for charts (use dataviz)) degrades harmlessly where the named skill is absent; a positive one (run X first) dangles, so those must name a skill in skills/.

Final Check

• Name is unique kebab-case, no existing skill owns the capability, and overlapping skills point at each other.
• Description has concrete Use when ... triggers and needed Do NOT use ... boundaries.
• SKILL.md is under ~120 lines, preferably 30-60 for tool wrappers.
• Helpers are invoked, not duplicated in prose.
• Positive cross-skill pointers name a skill that exists in skills/; scripts/check_skill_frontmatter.py also rejects description (use X) pointers to a skill not in skills/.
• Agent- or OS-only requirements are declared in compatibility:, not worked around.
• Update the existing catalog row if the skill's purpose or invocation changes.