Write Skill

This skill helps you author high-signal, maintainable Skills that reliably improve agent performance.

It is intentionally procedural where the platform has hard constraints (frontmatter validity, invocation controls, safety) and guiding where multiple viable design strategies exist (structure, tone, degree of strictness).

A skill you write should be usable by a different agent (or a human) with no prior context—it should stand on its own.

Workflow overview

Follow the detailed steps below. In practice, the shortest correct path is:

1. Step 0: Identify request type (Create / Refactor / Harden / Integrate / Update).
2. Step 2: Capture intent + define "done."
3. Steps 3–5: Choose invocation/safety, execution model, and structure.
4. Steps 6–8: Draft frontmatter, SKILL.md body, and supporting files (progressive disclosure).
5. Step 10: Validate and deliver (folder tree + full contents; minimal assumptions).

Request type routing (cheat sheet)

How this skill uses supporting files

This skill includes optional supporting material in references/ and templates/.

• When a workflow step says Load: path/to/file.md, open that file before continuing.
• If you feel uncertain about a decision point (ambiguity, edge cases, contradictions), jump to Appendix: Reference Index to find the right deep-dive.

Operating principles

1. Be efficient with context window, but gravitate towards correctness and completeness.

   • Ensure all top-level nuances and details that are critical or required for use of the skill are captured in the top-level SKILL.md and are unambiguously clear.
   • Always gravitate towards correctness and completeness as long as the content is appropriate, genuinely useful given the skill's use cases/scenarios, and clearly applicable.
   • Avoid duplication or repetitiveness — say it once, say it well, and in the right place.
   • Move deep reference material into references/ and load it only when needed — but do not exile critical behavioral guidance to reference files just to keep SKILL.md short. If the agent needs it to execute the workflow correctly, it belongs in SKILL.md.

2. Default to one strong path, with escape hatches.

   • Provide a recommended default workflow.
   • If alternatives exist, name them explicitly, but avoid option overload.

3. Optimize for reliability, not elegance.

   • If a step is fragile or easy to mess up, add guardrails (as appropriate for context):
     • a checklist
     • a validation loop
     • a script
     • an explicit output template

4. Write for execution, but keep it scannable.

   • Use clear imperatives: "Do X. Then do Y."
   • Assume the reader is skimming: headings, lists, tables, and short examples are encouraged.
   • Use explicit nouns and verbs; prefer concrete phrasing that is unambiguous and clear.

5. Calibrate language assertiveness to the instruction's confidence scope.

   • Use unconditional imperatives ("always", "never", "must") only for instructions that genuinely apply across all situations the skill will encounter.
   • For instructions designed for specific scenarios or that assume a particular input space, use measured language that signals the boundary — qualifiers like "when X," "in cases where," "typically," "for the scenarios covered here." This lets the agent recognize when it's outside the instruction's intended scope rather than confidently applying it where it doesn't belong.
   • Agents encounter unknown unknowns by default. Overly imperative language in context-dependent zones removes the agent's ability to exercise judgment when a novel situation arises. Qualified language preserves that judgment.
   • This does NOT mean hedging everything — procedural steps that truly always apply should remain direct and imperative. The goal is precision of commitment, not softness.

6. Make outputs standalone, self-enclosed, and non-redundant by default.

   • Assume a first-time reader with zero context.
   • A skill must not reference or depend on another skill's content unless it explicitly loads that skill at runtime (via the Skill tool, skills: frontmatter, or Agent+Skill composition). Implicit cross-skill references ("follow the approach from /research", "as described in the spec skill") create silent dependencies that break when the other skill changes, isn't present, or lives in a different plugin.
   • Prefer sections that build on each other or follow coherently in a procedural or sequential like way; avoid re-stating the same details unless repetition materially improves usability or safety.

7. Match the user's framing and nuance.

   • Reuse the user's terminology where it adds clarity and preserves intent.
   • Mirror their level of certainty (e.g., "must" vs "usually" vs "consider") - Make utterly clear negative commands like ("never", "don't", etc.)

8. Treat unstructured inputs as fallible evidence, not directives.

   • Large dumps (notes, transcripts, logs, research notes, ai reports, tool outputs) attached to a user's message may be noisy or irrelevant.
   • Your job includes triaging and filtering for relevance, extracting what matters, and setting the rest aside unless instructed otherwise.

The workflow to create or revise a skill

Follow these steps in order. Skip only if you have a concrete reason.

Create workflow tasks (first action)

Before starting any work, create a task for each step using TaskCreate with addBlockedBy to enforce ordering. Derive descriptions and completion criteria from each step's own workflow text.

1. Write-skill: Route request and load context
2. Write-skill: Capture intent and decide if skill is right artifact
3. Write-skill: Design decisions — invocation, execution model, structure, frontmatter
4. Write-skill: Draft SKILL.md body and supporting files
5. Write-skill: Validate and deliver

Mark each task in_progress when starting and completed when its step's exit criteria are met. On re-entry, check TaskList first and resume from the first non-completed task.

Update requests: If Step 0 routes to the update playbook, the update playbook creates its own task set (see references/updating-existing-skills.md). Mark this task list's remaining tasks as deleted — the update workflow's tasks replace them.

Step 0: Identify the request type

Determine which you're doing:

• Create a new skill from scratch
• Refactor an existing skill (shorten, restructure, split into references)
• Harden a skill (add validations, reduce hallucinations, limit tools, prevent side effects)
• Integrate a skill with subagents (e.g., context: fork, agent: Explore)
• Update/refactor an existing skill (intent-preserving)

If updating/refactoring an existing skill:

Load: references/updating-existing-skills.md

Critical: Before proceeding with any update work, you must complete Step 0: Full context loading from that file. This means reading:

1. Every file in the write-skill/ folder (SKILL.md + all references/ + all templates/ + all scripts/)
2. Every file in the target skill folder

Do not skip this step. Partial context loading is the primary cause of semantic drift during updates.

Default to fidelity-preserving changes only; treat substantive/routing/tool changes as "requires author consent." When requesting author decisions, use the Decision Support Protocol in that file.

If the user request is ambiguous, ask 2–4 targeted questions by default, then proceed with reasonable assumptions and make those assumptions explicit in your output.

If the ambiguity is high or the consequences are high-stakes (routing, tool power, destructive ops), you may ask up to 5–10 questions—but keep them sharply scoped and easy to answer. If you find yourself needing many questions, prefer progressive disclosure (see below) to avoid decision fatigue.

Clarification strategy (when to ask vs. when to assume)

Use this decision table to reduce both under-asking and over-asking:

Question design checklist (when you need human input)

When you need input from a human, make it easy to answer:

• Offer 2–4 clearly labeled options and include a keep as-is option when appropriate.
• Include an Other option when your options might not cover reality.
• Put your recommended option first and label it (e.g., "(Recommended)"), with a 1–2 sentence consequence.
• Avoid leading questions and false dichotomies ("A or B?" when C is plausible).
• If you proceed with assumptions, clearly label them as Assumptions and provide a simple way for the user to correct them.

At the end of your output, include a Quick Reference summary that recaps all pending decisions in a scannable format (question + options + your recommendation). This lets the human respond quickly without re-reading everything.

Progressive disclosure (optional, but recommended when many decisions are pending)

If you need more than a few clarifications, start with a single question like:

• Quick (Recommended): Use sensible defaults; ask only critical questions.
• Custom: Ask all configuration questions up front.
• Guided: Step-by-step with explanations and recommendations at each step.

Then tailor follow-up questions to the chosen mode.

Suggested minimal questions:

• What should the skill be named (or should I propose one)?
• Is it meant to be auto-invoked by Claude, a manual command, or background knowledge?
• Does it need to run tools / scripts, or is it purely guidance?

Step 1: Decide whether this should be a skill

Use a skill when you need portable procedural knowledge that should load on demand.

Prefer alternatives when they fit better:

• CLAUDE.md / AGENTS.md (project rules + setup):
  • Use for repo-specific commands, conventions, "how to work here," and evergreen constraints.
• Subagents (specialized system prompts + tool constraints):
  • Use for isolation, parallelization, or a distinct role with different permissions.
• Tools / MCP servers (capability extension):
  • Use when the core need is a deterministic action (send email, query DB) rather than guidance.
• Docs / llms.txt (reference):
  • Use for comprehensive "what exists" coverage, not "what to do in practice."

If the user explicitly asked for a skill, proceed.

Step 2: Capture intent and define "done-ness"

Before you draft structure, capture an intent snapshot (for you, not necessarily to paste verbatim):

• Goal: what the user wants to make repeatable
• Audience: who will read/use the outputs (default: first-time reader with no context)
• Constraints: safety, tools, runtime, "never do X" rules
• Tone / modality: how strict vs flexible the instructions should be
• Success criteria: what must be true for the skill to be "working"

Then write down (briefly):

• Scope: what tasks the skill covers, and what it explicitly does not cover
• Usage breadth: what range of contexts, domains, or situations will this skill be used in? If a concept in the skill means different things in different contexts (e.g., "deep" research means different things for cost analysis vs security analysis vs architecture review), the skill should use illustrative examples rather than prescriptive defaults — examples teach the agent to choose the right interpretation for the specific context
• Primary failure modes: what the model commonly gets wrong without this skill

If the request is high-stakes (security, production deploys, destructive ops), require a validation step.

Default output assumptions (unless the user specifies otherwise):

• Output format is Markdown.
• Optimize for human consumption (scannable headings, lists, tables where helpful).

Copy/paste template (optional but recommended):

**Intent Snapshot**
- Goal:
- Audience:
- In-scope:
- Out-of-scope:
- Constraints (tools/safety/runtime):
- Operating assumptions (tools, workflow model, platform, user intent):
- Success criteria (what "done" means):
- Primary failure modes to prevent:
- Usage breadth (contexts/domains/situations where this skill will be used):
- Output format expectations (if any):
- Safety posture (invocation + side-effects policy):
- Assumptions (if any):
- Open questions / pending decisions (if any):

Usage breadth: mandatory thinking, conditional context negotiation.

After capturing the intent snapshot, enumerate the usage contexts for this skill: the distinct contexts, domains, workflows, or situations where it will be invoked. Write these in the "Usage breadth" field. This thinking is mandatory — do not skip it even for seemingly simple skills.

Then check: do any concepts in the skill (depth labels, defaults, workflows, output formats) mean different things or need different treatment across these contexts? Signs a concept likely varies: subjective labels ("deep", "thorough", "simple"), behavioral defaults, approach choices ("use X vs Y"). Signs it likely doesn't vary: factual statements, structural conventions, platform constraints.

If yes — negotiate context with the user:

The user knows about usage contexts the agent can't infer from the goal description alone. Present your enumeration as a structured comparison (table or list) showing what varies across contexts:

"I've identified these usage contexts and where key concepts vary:

Context	[Concept X] means...	[Concept Y] means...
[Context A]	[treatment 1]	[treatment 3]
[Context B]	[treatment 2]	[treatment 3]
[Context C]	[treatment 1]	[treatment 4]

This means [Concept X] should be illustrative examples rather than a single default. If I'm missing a context, what guidance in this skill would need to be written differently?"

If the user adds contexts or flags new variation, trace the implications: what other design decisions are affected? Surface those and confirm. Continue until the usage model stabilizes.

If no — proceed. If all contexts get the same treatment for all concepts, note this in the intent snapshot and move to Step 3. No interaction needed.

Step 3: Choose invocation and safety posture

Load: references/frontmatter-and-invocation.md

If the skill includes scripts, tool access, external fetching, or high-stakes domains:

Load: references/security-and-governance.md

Decide how the skill is invoked:

1. Default (recommended for most skills): Claude and the user can invoke it.
2. Manual-only command: set disable-model-invocation: true
   • Use when the skill has side effects or should not run opportunistically.
3. Claude-only background knowledge: set user-invocable: false
   • Use when it's not meaningful as a command, but should guide behavior.

Guidance:

• If a skill can run commands that could change state, strongly consider manual-only plus tool restrictions.

Step 4: Choose execution model and composition with subagents

Continue using: references/frontmatter-and-invocation.md

There are four "skills + subagents" compositions. A–C use the in-process Agent/Task tool (subagents within a session). D uses subprocess spawning (full child claude -p processes):

A) Skill runs as an isolated subagent (context: fork)

• Use when you want:
  • isolation from the main thread
  • a specialized agent type (Explore, Plan, etc.)
  • a skill to act like a "mini-program" with a clear task prompt
• Requires: the skill body must contain a complete task prompt.
• ⚠️ Known reliability issue: context: fork frequently fails to actually fork — the skill runs inline instead. This particularly affects plugin skills. See references/frontmatter-and-invocation.md for details and workarounds.

B) Subagent preloads one or more skills (subagent frontmatter skills:)

• Use when you want:
  • a persistent role agent (reviewer, planner, researcher)
  • skills to be "reference material" injected into its context
• Note: subagents don't inherit the parent's skills automatically.

C) Parent spawns a subagent that loads a skill at runtime (Agent tool + Skill load)

• Use when:
  • a skill's workflow needs to invoke another skill in isolation (e.g., a research skill running a grounding skill as a preliminary step)
  • the caller decides at runtime whether to delegate — isolation is a property of the invocation, not the skill itself
  • context: fork is unreliable in your environment (e.g., plugin skills)
• Pattern: spawn a general-purpose subagent via the Agent tool. Start its prompt with "Before doing anything, load /skill-name", then provide context and the task. The subagent uses its Skill tool to load the skill, executes the workflow, and returns results.
• Constraint: subagents cannot spawn other subagents, so this only works one level deep.

D) Skill orchestrates via subprocess spawning (claude -p child processes)

• Use when:
  • the skill needs parallel fan-out of N independent tasks
  • children need to spawn their own subagents (Task-tool subagents cannot nest; subprocesses can)
  • work may exceed the 600s Bash tool timeout
  • the workflow is an iteration loop where fresh children pick up from file-based state
• Key design implication: children start with zero context — no conversation history, no loaded skills, no parent state. The skill must design for file-based state handoff (state files, progress files, output files) rather than conversational continuity.
• Children run non-interactively: no human is present to answer prompts. Any skill loaded by a child must support headless execution (see content pattern #20).
• See /nest-claude for the full subprocess spawning reference (env guard, parallel patterns, monitoring, result collection).

See also: templates/SKILL.fork-task.template.md for forked execution pattern.

Step 5: Pick a structure (choose one default)

Load: references/structure-patterns.md

Choose the simplest structure that can still be high-quality:

Pattern 1: Single-file skill

• Best when it fits comfortably under the size guidance and doesn't need deep reference.

Pattern 2: SKILL.md + references/

• Best when you need deep details sometimes (schemas, API docs, edge cases).

Pattern 3: SKILL.md + scripts/

• Best when reliability matters and you want deterministic steps (validation, transformations).

Pattern 4: Index skill + rules/

• Best for "many discrete rules" and prioritized playbooks.

Pattern 5 — Forked execution skill: SKILL.md with context: fork runs as an isolated subagent task.

Pattern 6 — Multi-variant: Separate reference files per provider, language, or framework.

Pattern 7 — Path-scoped: SKILL.md with paths field auto-activates only for matching files.

Step 6: Write frontmatter (routing metadata)

Continue using: references/frontmatter-and-invocation.md

Write frontmatter that includes:

• name: short, hyphen-case, matches folder name
• description: what it does + when to use + key trigger terms (file types, platforms, domain nouns)
• argument-hint (if command-like)

Verify these are present before moving to Step 7.

Step 7: Write SKILL.md body (the "runtime prompt")

Load: references/content-patterns.md

If the skill depends on external tools, platform features, a specific workflow, or assumes user intent beyond its explicit inputs, also Load: references/assumptions-and-adaptability.md

If the skill includes interactive gates (AskUserQuestion, confirmation prompts, routing selectors) and might be invoked by automated callers, also apply content pattern #20: Design for headless execution.

If the skill manages persistent state across turns or sessions (e.g., it writes artifacts that evolve, accumulates evidence, or needs to support session resumption), also Load: references/stateful-skill-patterns.md

For such skills, before writing workflow steps, decide:

• What does this skill produce? (messages only, or also persistent artifacts?)
• Who consumes each output? (invoker now? future session of this skill? downstream system?)
• How long must each output survive? (this turn? this session? across sessions?)
• How does each output change over time? (overwritten? appended? immutable?)

Use imperative language and a structure that makes the model's job easy.

Include everything the agent needs to execute the workflow correctly. Move deep reference material to supporting files, but keep critical behavioral guidance, nuances, and decision criteria in SKILL.md itself.

When drafting, keep these defaults in mind:

• Keep the artifact standalone: it should not depend on the reader knowing anything from earlier chats.
• Avoid unnecessary repetition: later sections should introduce new information, not rephrase earlier content.
• Preserve the user's intent and nuance; weave brief "why" context where it prevents bad judgment calls.
• If the skill operates over messy/unstructured artifacts, include a relevance-triage step and avoid treating raw content as authoritative unless verified.

Common high-signal sections (mix and match):

• Workflow: step-by-step sequence
• Task creation: upfront workflow tasks for skills with 3+ phases (see content-patterns.md #1b)
• Decision points: short decision trees or tables
• Quality bar: must-have / should-have checklists
• Examples: correct vs incorrect
• Validation loop: "do → verify → fix → re-verify"
• Output format: exact template if consistency matters

Before moving on, verify each instruction passes the interpretation test: Could it be read two ways? Does it assume context the reader won't have? (See content-patterns.md #14 for the full test.)

Step 8: Add supporting files (progressive disclosure)

Use supporting files for two reasons:

• keep SKILL.md focused on workflow and critical behavioral guidance (not deep reference material)
• make detailed reference info available only when needed

Recommended:

• Put detailed material in references/*.md.
• Put executable utilities in scripts/.
• Put reusable templates in assets/ (or templates/ if they're authoring aids).

Avoid:

• deep chains (reference files that require chasing other references)
• duplicating the same content across files

If you add files under references/ or templates/, follow the "Use when / Priority / Impact" header standard (see Appendix) so routing stays reliable.

Step 9 (optional): Tests

If and only if asked to come up with a testing strategy for the skill:

Load: references/testing-and-iteration.md

Key notes:

• Tests live outside the skill. Skills are self-contained; test harnesses are separate infrastructure (e.g. an agent execution framework)
• Tests ≠ runtime validations. Runtime validations are instructions within the skill for the agent to verify its own outputs. Tests are deterministic scripts that validate artifacts or side effects after execution.
• Not all skills need tests. Testing is most valuable for skills that produce structured outputs, modify files, or have clear testable pass/fail criteria.

Step 10: Deliver the output cleanly

When asked to "write a skill," output:

1. The folder tree
2. The full contents of each file
3. Minimal assumptions (clearly labeled)

If revising an existing skill, provide:

• what you changed and why (briefly)
• before/after structure if relevant

Keep the resulting skill(s) stateless and standalone:

• Do not embed "change notes" or update commentary inside SKILL.md.
• Put update commentary in your response or a separate changelog file only if requested.

Optional validation (recommended when you can):

• If bun is available, run:
  • bun scripts/validate_skill_dir.ts path/to/skill-folder
• If it fails, fix and rerun.
• Treat warnings as "review required," not automatic blockers.

Final self-check (copy/paste):

• Frontmatter has name + description and name is hyphen-case.
• Invocation posture matches risk (manual-only for side effects).
• SKILL.md has a default workflow + clear success criteria.
• Output is standalone (first-time reader can execute it).
• No implicit cross-skill dependencies — any reference to another skill uses explicit loading (Skill tool, skills: frontmatter, or Agent+Skill composition).
• Any references are one-level-deep and have a "Use when / Priority / Impact" header.
• If inputs are messy/unstructured, the skill includes a relevance-triage step.
• If the skill is high-stakes, it includes a validation loop / stop-and-verify step.
• Checked for ambiguous instructions that could be interpreted differently in other contexts.
• If the skill has interactive gates, it supports --headless for non-interactive callers (content pattern #20).

Guidance vs house conventions

This skill describes multiple valid skill structures. Skills do not need to follow a single format.

However, within this write-skill/ skill, we use a few house conventions to keep our own supporting files discoverable and reliable. See the appendices for the conventions and the reference index.

Making supporting files discoverable (optional pattern)

If you decide to split a skill into multiple files (e.g., references/, templates/, rules/), it often helps to:

• Add explicit pointers in the workflow ("Load: references/x.md") at the moment the file becomes relevant
• Give each supporting file a short "Use when / Priority / Impact" header

This is not required for all skills. Many skills should remain single-file. Use this pattern when you notice agents aren't consulting supporting material reliably.

Appendices

Appendix: Reference File Header Standard (house convention)

For files under references/ and templates/ in this skill, we add a short routing header at the top so an agent can quickly decide relevance.

Header format:

Use when: <1–3 trigger conditions>
Priority: P0 | P1 | P2
Impact: <what goes wrong if skipped>

Use-when phrasing should be task-shaped ("Designing X with Y constraint") rather than concept-shaped ("Reasoning about Z") — see references/content-patterns.md #26.

Appendix: Reference Index (navigation aid)

This index exists to help you quickly find the right deep-dive. In the main workflow, prefer the Load: pointers.

Priority legend:

• P0 = must for correctness/reliability of the skill-writing process
• P1 = improves quality and consistency
• P2 = optional depth

Appendix: House conventions for this skill

• No orphan files: If we add a file under references/ or templates/, we either:
  • add a Load: pointer in the workflow where it's relevant, and/or
  • list it in the Appendix Reference Index with "Use when"
• Headers on supporting files: Each file under references/ and templates/ includes a "Use when / Priority / Impact" header block.
• Appendix for navigation, workflow for execution: The Reference Index is for scanning and maintenance; actual loading happens via Load: gates in the workflow steps.