# Expert Skill Creator

> Expert-level guidance for creating high-quality Claude Code skills. Use alongside Anthropic's skill-creator when creating new skills, improving existing skills, or needing guidance on skill content quality. Complements basic skill mechanics with research-driven content development, XML tag structuring, decision frameworks over mechanics, cross-references between skills, and systematic validation.

- Skill: `pyroxin/expert-skill-creator` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add pyroxin/expert-skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pyroxin/expert-skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: Pyroxin (https://skillmd.com/u/pyroxin)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/pyroxin/expert-skill-creator

---


# Expert Skill Creator

<skill_scope skill="expert-skill-creator">
**Related skills:**
- `skill-creator:skill-creator` (Anthropic) - Basic skill mechanics, directory structure, initialization
- `opinionated-software-engineering:software-engineer` - Design principles that inform skill architecture
- `opinionated-software-engineering:test-driven-development` - Validation methodology parallels

**This skill complements Anthropic's `skill-creator:skill-creator` skill.** Load both when creating skills: `skill-creator:skill-creator` provides basic mechanics (e.g., directory structure, initialization scripts, packaging), while this skill provides expert-level guidance on content quality, structure, and validation.

Skills are modular packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tool integrations. They function as **retrieval triggers** that activate and organize Claude's trained knowledge, not as teaching material that explains concepts from scratch.

**Critical insight**: For LLMs, skills activate existing knowledge rather than teaching new content. The risk is that too much detail *constrains* behavior rather than enhancing it. Skills should provide high-level frameworks that trigger trained knowledge, with detailed content reserved for genuinely novel or problematic areas.

**Model calibration:** This skill assumes Opus as the authoring model and targets created skills primarily at Opus and Fable. Fable 5 is new and capacity-limited as of June 2026; treat it as an upgrade path rather than a dependency (see `<model_targeting>`). For skills targeting Sonnet or Haiku tiers, see `references/prompting-sonnet.md` and `references/prompting-haiku.md`.
</skill_scope>

## When to Use This Skill

<when_to_use>
Use this skill when:
- Creating a new skill from scratch
- Improving or refactoring an existing skill (for the staged procedure, see `references/retrofitting-existing-skills.md`)
- Evaluating skill quality against established guidelines
- Needing guidance on skill architecture, structure, or content depth
- Researching content for a skill using agents
- Validating skill content for accuracy and completeness

Do not use this skill for:
- General prompt engineering (this is skill-specific)
- Subagent packaging mechanics (e.g., tool lists, model selection, agent frontmatter fields) — though agent prompt *content* follows similar quality principles; see `<directive_language>`
- Skill frontmatter syntax beyond `name` and `description` — see `skill-creator:skill-creator` for fields like `context`, `agent`, `allowed-tools`, `hooks`, argument substitution, and dynamic context injection
- One-off instructions that don't warrant a reusable skill
</when_to_use>

## Skill vs. Subagent Decision

<skill_vs_subagent_decision>
**Before designing a skill, verify that a skill is the right primitive.** Skills and subagents solve overlapping problems at different layers. A skill that should have been a subagent (or vice versa) is harder to fix later than getting the choice right up front.

### The core discriminator: who writes the task?

| Primitive | Task text from | Reach for it when |
|-----------|----------------|-------------------|
| Subagent | The caller (main agent's delegation message or user's `@mention`) | Task content varies arbitrarily per invocation; value is "handle anything in domain X"; multiple skills or workflows might want it as a worker |
| Skill (inline) | The skill file itself; small parameterization via `$ARGUMENTS` | You have a repeatable procedure; steps are stable; you want `/slash-command` access; material benefits from the main context (e.g., conventions, reference, checklists) |
| Skill with `context: fork` | The skill file, sent as the subagent's task prompt | Skill-shaped procedure *and* one of: it would pollute main context; it needs a specialized environment (e.g., read-only tools, different model, restricted permissions); you want to pin it to a specific subagent type |

**Heuristics:**
- If you describe the task afresh every time you invoke the capability, it's a subagent
- If the task is fixed and only small inputs change, it's a skill
- If it's a fixed task *and* it either pollutes main context or needs a specialized environment, it's a skill with `context: fork`

### Composition, both directions

Skills and subagents compose in two supported patterns[^2]:

| Pattern | System prompt | Task | Also loads |
|---------|---------------|------|------------|
| Skill with `context: fork` + `agent:` | From the selected agent type | `SKILL.md` body, rendered | CLAUDE.md |
| Subagent with `skills:` frontmatter field | Subagent's own markdown body | Caller's delegation message | Preloaded skills + CLAUDE.md |

A "fork skill" composes the two primitives rather than replacing either: the skill supplies a fixed task, the subagent supplies the environment. Both remain independently usable on their own.

**Common confusion to avoid:** "This procedure is long, so let's make it a fork skill rather than a subagent." The procedure's length isn't the discriminator — who writes the task is. A long, fixed procedure is a fork skill. A long, variable task that the caller specifies each time is a subagent with a substantial system prompt.

### Interface contracts between components used together

<composition_contracts>
**When skills and agents are designed to be used together, the interface between them is a contract. A consumer must be able to act on a producer's output without guessing.**

Composition takes several shapes (e.g., a fork skill handing a task to a subagent, a skill that invokes another skill, or a family of skills that pass artifacts down a pipeline). In each, one component's output is another's input, so three things have to agree across the set:

| Contract element | Keep aligned by |
|------------------|-----------------|
| Vocabulary | One term per concept across every component (a concept named two ways reads as two concepts) |
| Locations | Shared file paths and output directories defined once and referenced, not retyped per component |
| Artifact shape | A stated schema for what's handed off, so the consumer parses it deterministically rather than inferring it |

Drift in any of these breaks the handoff at runtime — a downstream component silently misreads or ignores an upstream artifact — rather than failing at authoring time. Define the shared vocabulary, paths, and schema in one canonical place (e.g., a shared reference file or the most upstream component) and have the others point to it, consistent with `<cross_reference_guidelines>`. When you revise one side of a contract, revise the other side in the same change (see `<consistency_validation>`).
</composition_contracts>

Once you've decided a skill is the right primitive, see `<content_patterns>` for choosing between Reference (inline) and Task (fork) content.
</skill_vs_subagent_decision>

## Skill Architecture

<skill_anatomy>
### Directory Structure

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (required)
│   │   ├── name: lowercase-hyphenated (max 64 chars)
│   │   └── description: what + when (max 1024 chars)
│   └── Markdown body with XML-tagged sections
├── scripts/          - Executable code (deterministic operations)
├── references/       - Documentation loaded on-demand
└── assets/           - Files used in output (e.g., templates, icons)
```

### Progressive Disclosure

Skills use three-level loading to manage context efficiently:

| Level | Content | When Loaded | Size Target |
|-------|---------|-------------|-------------|
| 1. Metadata | name + description | Always in context | ~100 words |
| 2. SKILL.md body | Instructions, frameworks | When skill triggers | <5k words |
| 3. Bundled resources | Scripts, references, assets | As needed by Claude | Unlimited |

**Design implication**: Keep SKILL.md lean. Move detailed reference material, schemas, and examples to `references/` files. Information should live in either SKILL.md or references, never both.

### Content Patterns

<content_patterns>
Skills fall into two architectural patterns that require different content approaches:

| Pattern | Frontmatter | Content style | Example |
|---------|-------------|---------------|---------|
| **Reference** (inline) | Default | Knowledge, conventions, decision frameworks Claude applies alongside conversation context | Style guides, API conventions, language idioms |
| **Task** (fork) | `context: fork` | Self-contained task prompt with explicit steps; runs in an isolated subagent with no conversation history | Deployment workflows, research orchestration, batch operations |

**Reference skills** provide context Claude weaves into its responses. Write them as frameworks and principles (as throughout this skill). They run inline with full conversation access.

**Task skills** are complete prompts that drive a subagent. They need explicit instructions because the subagent has no conversation context. Use `context: fork` and optionally `agent:` to select the execution environment (e.g., `Explore` for read-only, `general-purpose` for full tool access). Task skills can launch further agents via the Agent tool, enabling fan-out patterns like parallel research or batch code changes.

Choose the pattern based on whether the skill augments Claude's knowledge (reference) or orchestrates an independent workflow (task).
</content_patterns>
</skill_anatomy>

## Quality Guidelines

<quality_guidelines>
These guidelines emerged from creating 15+ skills and observing their performance in clean context windows.

### XML Tag Structure

<xml_tag_guidelines>
**Skills are prompts—apply XML tagging best practices.[^1]**

**Why XML tags matter:**
- Clarity: Separate different parts of the skill
- Accuracy: Prevent Claude from mixing instructions with examples
- Flexibility: Easy to find, add, remove, or modify sections
- Parseability: Enable structured reasoning about skill content

**Tag naming conventions:**
- Use descriptive `snake_case` names: `<dependency_update_checklist>`, `<error_handling_patterns>`, `<api_versioning_strategy>`
- Avoid generic names—`<remember>` or `<notes>` don't describe what to remember or what the notes contain; prefer names like `<migration_safety_constraints>` or `<version_compatibility_matrix>`
- Maintain consistent names throughout—same concept, same tag name
- Wrap coherent conceptual chunks that could be referenced independently
- Nest tags for hierarchical content: `<platform_differences><macos_specifics>...</macos_specifics></platform_differences>`

**Standard tags:**
- `<skill_scope skill="skill-name">` — Use for the skill's introductory section (e.g., overview, purpose, related skills). The `skill` attribute prevents collision when multiple skills are loaded. Every skill should begin with this tag after the title.

**Explicit tag references:**
Reference tags by name when discussing their content. This reinforces connections between sections and helps readers navigate related guidance.

- Good: "Apply the guidelines in `<release_checklist>` before publishing"
- Weak: "Apply the release checklist guidelines before publishing"
- Good: "Validate inputs at system boundaries (see `<input_validation_rules>` for requirements)"

**Tag attributes:**
- Attributes carry metadata distinct from content: `<example type="good">`, `<quote source="SICP">`
- Use sparingly; content inside tags receives more attention than attributes
- Keep behavioral guidance in tag content rather than attributes; attribute content receives less attention
- Good uses: source attribution, example classification, conditional context markers

**Position matters (primacy bias):**
Content earlier in a tag receives more attention than content later. At the document level, placing long reference material at the top with instructions and queries at the bottom can improve response quality by up to 30% in tests on multi-document inputs.[^3] Within sections, structure accordingly:
- Put the guidance the reader must act on first within each section
- Lead with critical constraints, follow with elaboration
- If ordering a list by priority, highest priority items should come first

**Tag granularity:**
- Every markdown header's content should be wrapped in an XML tag
- This creates 1:1 correspondence between visual structure (headers) and semantic structure (tags)
- Too coarse: One tag wrapping multiple unrelated concepts under different headers
- Too fine: Tagging individual sentences or single list items
- Right-sized: Roughly 10-100 lines of conceptually unified content (approximately one header's worth)

**Combine XML with other techniques:**
- Multishot prompting: `<examples><example>...</example><example>...</example></examples>`
- Chain-of-thought as a manual fallback when API thinking is off: `<thinking>...</thinking><answer>...</answer>`[^3] — avoid in skills that may run on Fable-class models, where instructing the model to reproduce its reasoning as response text can trigger a `reasoning_extraction` refusal (see `<model_targeting>`)
- Conditional sections: `<if_typescript>...</if_typescript>`

**Example structure:**
```markdown
## Section Title

<section_name>
Most important guidance first...

<subsection_name>
Nested content...
</subsection_name>

Elaboration and details follow...
</section_name>
```
</xml_tag_guidelines>

### Content Depth and Philosophy

<content_depth>
**Staff-level insights over junior-level checklists.**

**Include:**
- Philosophical foundations (the "why" behind practices)
- High-judgment principles experienced practitioners recognize
- Trade-offs, context-sensitivity, and when rules should be broken
- Distinctions less experienced practitioners miss
- Systems thinking, emergent behavior, second-order effects

**Avoid:**
- Basic syntax Claude knows from training
- Step-by-step tutorials on fundamental concepts
- Low-level implementation details unless they affect judgment
- Overly granular instructions that constrain rather than guide

**Exception—Safety constraints are valuable even for well-known content:**
Safety guardrails should be included even if Claude "knows" them. These constrain *toward* safety, not away from good behavior. Distinguish "teaching content" (condense) from "safety guardrails" (keep).
</content_depth>

### Directive Language

<directive_language>
**Skills are prompts. Directive intensity directly affects model behavior, and the effect is version-specific — calibrate against the models the skill targets.**

Current documented behavior by model class:

| Class | Documented behavior | Implication for skill prose |
|-------|---------------------|-----------------------------|
| Opus (documented for Opus 4.8) | Takes instructions at face value and applies them only to their stated scope; leans on reasoning before reaching for tools[^4] | State scope and thresholds explicitly — a vague bar like "only report important issues" is followed faithfully, suppressing output you wanted |
| Fable (documented for Fable 5) | A brief instruction steers most behaviors; heavy prescription carried over from older skills can hurt output[^5] | Prefer one condition-framed sentence over enumerating behaviors (see `<model_targeting>`) |

Rows are class defaults. When targeting a newer release, check the model-specific prompting pages rather than trusting parametric recall — class behavior has reversed between adjacent versions before.

Write skill content clearly and directly; assume a capable reader, and avoid all-caps or forceful intensifiers.[^3] More forceful writing does not increase the reader's understanding.

| Instead of | Write |
|------------|-------|
| "CRITICAL: You MUST..." | "Use [tool] when..." |
| "ALWAYS check..." | "Check [condition] before..." |
| "NEVER do X" | Describe the desired behavior instead |
| "If in doubt, use [tool]" | "Use [tool] when it would improve your understanding" |

**Prefer positive framing.** Tell the model what to do instead of what not to do: "Your response should be composed of smoothly flowing prose paragraphs" rather than "Do not use markdown in your response".[^3] Showing examples of the desired behavior tends to work better than prohibiting the undesired one.[^4] This applies at every level of skill content — from high-level behavioral guidance to specific output formatting instructions.

**Include 3-5 few-shot examples** when a skill needs to demonstrate output format, tone, or reasoning patterns.[^3] Wrap them in `<examples><example>...</example></examples>` tags. Choose diverse examples that cover edge cases; quality and variety matter more than quantity. This recommendation currently applies across tiers, Haiku included (see `references/prompting-haiku.md`).

This connects to the "retrieval trigger" philosophy in `<skill_scope>`: if skills activate existing knowledge, aggressive directives are counterproductive. They constrain behavior rather than activating capability. The right prompt intensity is the minimum needed to reliably activate the desired behavior.
</directive_language>

### Literal Language

<literal_language>
**Write skill instructions so that interpreting them correctly does not require knowledge that may be unavailable when the skill is read. Avoid figurative language (for example, metaphor, idiom, or analogy used as instruction) and evaluative language (for example, "elegant", "powerful", or a vague quality term such as "important"), and state conditions, thresholds, and actions directly; on vague quality terms see `<directive_language>`.**

Assume the context available while you author a skill will not be available when it is read (see `<skill_anatomy>` on progressive disclosure, and `<instructional_formulation>` on phrasing this as a directive). Figurative and evaluative language depends on that absent context: a metaphor needs the authoring discussion to interpret, and a term such as "the right approach" needs a shared standard the reader does not have. State conditions and actions literally so the text remains clear without that context.

The rule targets a vague quality term that the reader must apply as a criterion to decide what to do; there, an undefined bar produces miscalibrated behavior (see `<directive_language>` on stating thresholds explicitly). It does not target a quality term that marks a default tendency for the reader to weigh in context, provided you hedge it and supply the concrete basis for the judgment. The hedge signals a default rather than a rule, and the concrete basis carries the decision, so the reader judges from the basis, not from the vague word. For example, "usually useful as a persistent teammate: it retains its context across idle periods, so it can handle follow-ups" is acceptable; "usually" marks the default and the reason after the colon does the work. "Use the most useful agent for the job" is not; "useful" is the criterion and nothing grounds it. Reach for a qualified quality term deliberately, to invite judgment — not as a substitute for a criterion you could state concretely.

Terms of art are acceptable, and often useful, when the term is explained where it is first used or when its meaning matches the ordinary meaning of the word. A term that needs special knowledge to interpret, and that the skill does not supply, has the same defect as a metaphor; define it on first use or replace it. However, don't avoid introducing terms of art when knowing them is necessary for effective use of the knowledge in the skill.

Mark every example and reformulation explicitly, including example tables and sets, so they are not read as a closed or complete specification (see `<open_world_framing>`). The following table gives examples of the substitution; it is not a complete list:

| Figurative or evaluative (avoid) | Literal (prefer) |
|----------------------------------|------------------|
| "This step is a pre-flight check." | "This step verifies preconditions before proceeding." |
| "Spin up an elegant, powerful research team." | "Spawn a research team when [stated condition] holds." |
| "The task list is the team's coordination substrate." | "Teammates coordinate through the shared task list." |

This rule governs the skill's instruction text, not user-facing output the skill produces (for example, a report for a human audience), where figurative or evaluative language may be appropriate.
</literal_language>

### Placeholder Notation

<placeholder_notation>
**Write a placeholder — a token the reader replaces with a value — in braces: `{project-root}`, `{your-name}`, `{timestamp}`. Reserve angle brackets for XML tags, covering both tag definitions and the `` `<tag_name>` `` references described in `<xml_tag_guidelines>`.**

A skill body uses angle brackets as structure, so a placeholder written as `<project-root>` sits in the same notation as a section tag; the reader can't tell from the token alone whether it marks a slot to fill or names a section. Braces carry no structural meaning in a skill body, so a braced token reads as a slot and nothing else.

The ambiguity does the most damage in a prompt template that a skill tells the model to send to another agent, because the placeholder then arrives in a second context that also reads angle brackets as structure. Paths and command templates are the other places placeholders cluster.

Keep one notation throughout a skill. Mixing both inside a single expression is the common failure; for example, `<project-root>/notes/{timestamp}/` asks the reader to resolve two notations for the same kind of token in one path. The following table gives examples of the substitution; it is not a complete list:

| Ambiguous (avoid) | Unambiguous (prefer) |
|-------------------|----------------------|
| `<project-root>/notes/{timestamp}/` | `{project-root}/notes/{timestamp}/` |
| `Report to the lead ('<lead-name>')` | `Report to the lead ('{lead-name}')` |
| `/Users/<name>` | `/Users/{name}` |

Braces here denote a value the reader supplies while following the instruction. Runtime argument substitution, where the harness replaces a token before the skill is read, is a separate mechanism with its own syntax; see `skill-creator:skill-creator` as noted in `<when_to_use>`.

This governs the skill's instruction text and any template it carries. Inside content that reproduces another notation, that notation's meaning holds, in both directions: angle brackets stay as they are in a CLI usage synopsis (`init_skill.py <skill_name>`), a generic type (`List<String>`), an HTML or XML example, or a shell redirect; braces stay as they are in shell expansion (`mkdir -p dir/{a,b}`). Fenced code is the usual home for both, and the fence is what signals the switch.
</placeholder_notation>

### Instructional Formulation

<instructional_formulation>
**When a statement's purpose is to drive behavior, cast it as an instruction the reader can act on. A fact stated as a bare description, with its intended action left implicit, may not produce that action; state the action, or the assumption to adopt, directly.**

The reader of a skill is a model executing it. "A skill loads into a fresh context window" leaves implicit what to do about it; "Assume the context available while you write the skill will not be available when it is read" states the action. The following table gives more examples; it is not a complete list:

| Bare description (action left implicit) | Instructional (prefer) |
|------------------------------------|------------------------|
| "A skill loads into a fresh context window without the context that produced it." | "Assume the context available while you write the skill will not be available when it is read." |
| "Specialists go idle between turns." | "Expect specialists to be idle between turns; do not treat idleness as a failure." |
| "The task list records ownership and status." | "Record ownership and status on the task list as work is claimed and completed." |

This targets bare description, not the descriptive content a judgment framework needs. A decision table, a trade-off analysis, or a "when to use what" comparison is itself an instruction: it tells the model how to judge, and the model needs the stated criteria and context to do so. Keep that content (see `<decision_frameworks>` and `<content_depth>`); do not reduce it to imperatives. A principle is well cast as an assumption the model adopts rather than an imperative — for example, `decision-analysis`'s "treat stated option value as hypothetical until grounded in the situation" is descriptive in subject but instructional in effect, and the model reasons from it. State the criteria, invoke them with an action ("assign a value using this table"), and keep the rationale that lets the model generalize.

This complements `<directive_language>` (how forcefully to phrase a directive) and `<literal_language>` (keeping the directive plain); this guideline is about whether a statement that should drive behavior is phrased to do so.
</instructional_formulation>

### Model Targeting

<model_targeting>
**Author for Opus as the baseline; treat Fable as an upgrade path, not a dependency.**

This section synthesizes and paraphrases Anthropic's model-specific prompting pages.[^4][^5] Fable's safety classifiers can return a `refusal` stop reason with automatic fallback to Opus 4.8,[^5] and this skill assumes Fable access can't be banked on while it's new (an authoring assumption, not a documented limit). A skill that behaves well only on Fable therefore has no guaranteed runtime. Write skills that are correct on Opus; Fable's stronger instruction-following then needs less of the skill's prose, not different prose.

Cautions for skills that may run on Fable-class models:
- Ask for work products (e.g., findings, analysis, recommendations), not a transcript of reasoning. Instructions that have the model restate its internal reasoning as response text can trigger the `reasoning_extraction` refusal category and force fallback; applications needing reasoning visibility should read structured thinking output from the API instead.[^5]
- Trim prescription. Skills inherited from earlier models tend to over-specify for Fable, which can hurt output quality; re-test with instructions removed before assuming they're needed.[^5]
- For task skills that orchestrate agents (see `<content_patterns>`), state the conditions under which delegation is appropriate — Fable reaches for parallel subagents more readily than earlier models did.[^5]

In skills you author, do the same: model classes in guidance, version numbers in evidence (citations, provenance notes, dated status facts).

Skills targeting Sonnet or Haiku (e.g., as subagent workers in multi-tier systems) follow the same general principles; tier-specific calibration lives in `references/prompting-sonnet.md` and `references/prompting-haiku.md`. Anthropic currently publishes model-specific prompting pages only for its top tiers (currently, Fable 5 and Opus 4.8); Sonnet and Haiku guidance comes from the general best-practices page and migration guides, which those references synthesize.
</model_targeting>

### Guidance vs. Invariants

<guidance_vs_invariants>
**A directive is guidance the model can decline to follow. If a behavior must hold, route it to a mechanism, not a sentence.**

Skill content shapes probability, not control flow. Phrasing a requirement more forcefully (e.g., "CRITICAL", "NEVER", "NO EXCEPTIONS") may raise the odds of compliance; it does not guarantee it, and on some tiers it backfires (see `<directive_language>`). So before writing a requirement, classify it:

| Kind | Definition | How to encode it |
|------|------------|------------------|
| Guidance | The model should usually do X; an occasional miss is tolerable | A calm, positively-framed directive |
| Invariant | X must hold for the skill to be correct or safe; a single miss is a defect | A deterministic gate the skill runs (e.g., a script, validator, test, or hook), with the directive as a backstop rather than the sole guard |

**Treat escalating directive intensity as a design smell — a surface symptom of a deeper problem.** The urge to write "you MUST never mark this done unless tests pass" is a signal that the requirement is an invariant the prose cannot enforce; the fix is a gate (for example, run the tests and read the result), not more forceful wording. A model can narrate that it followed an unenforceable rule while not having followed it — only a mechanism observes the actual state.

**Keep the guidance-versus-invariant judgment in your authoring, not in the prompt.** When no mechanism is available and a requirement stays guidance, state it as a plain positive instruction. Do not tell the model that the requirement is not enforced, or that nothing stops it from skipping; that gives the model permission to skip and undercuts the directive, because the model reads "not enforced" as "optional." If a later step can check the behavior, have the model produce the inspectable state that step reads (for example, a record a subsequent gate consults). Whether the check is runtime-enforced is your judgment to hold, not content for the prompt.

This skill's own `<pii_and_secret_scanning>` applies this: it wires the scan "into the same validation gate ... enforced rather than remembered." Generalize it — when a skill defines work that must happen (e.g., a precondition, a format, a check), prefer wiring it into a gate the skill executes over trusting the model to remember.

When the invariant is "the code does what the spec says," the gate is a test; see `opinionated-software-engineering:test-driven-development` (tests as contracts). For the broader principle of pushing correctness into mechanisms rather than convention, see `opinionated-software-engineering:software-engineer`.

This section covers *when* to reach for a gate and *what kind* to reach for; it does not yet cover *how to build one*. Concrete implementation patterns — wiring a hook, structuring a validator script, embedding a test the skill runs — are an open area not yet developed here.
</guidance_vs_invariants>

### Open-World Framing

<open_world_framing>
**Write skill instructions for an open world. The domains skills describe — tools, APIs, options, the model's own capabilities, among others — keep changing, and any one skill sees only part of them.**

A list that reads as complete becomes wrong the moment the world adds a case it didn't enumerate, and it can suppress the model's trained knowledge of cases the list omits (the opposite of the retrieval-trigger goal in `<skill_scope>`). Default to phrasing that stays true as the world changes and as present unknowns surface.

Practices:
- Mark example lists as non-exhaustive: "e.g.,", "for example", "such as", "including but not limited to". Reserve "i.e.," for restating the same thing a different way, not for examples — the two carry different meanings.
- Hedge claims that ride a moving target: "currently", "as of {date}", "tends to", "in most cases". Date-stamp facts that will age.
- Prefer describing the condition over closing the set — "use a feature flag when shipping incomplete work" rather than "always use a feature flag" (this reinforces the positive framing in `<directive_language>`).
- Lead parenthetical example lists with a marker like "e.g.," or "for example,". A bare parenthetical such as "(JSON, YAML, TOML)" reads as the complete set or an "i.e.," restatement; writing it as "(for example, JSON, YAML, TOML)" marks it as open.
- Apply the same marking to example tables and multi-row example sets, not only inline lists. Introduce them with a phrase such as "The following are examples, not a complete list." An unmarked example table can be read as a closed specification of the only acceptable cases.
- Mark reformulations as reformulations, with "that is", "i.e.,", or "in other words". An unmarked restatement can be read as a separate, independent claim rather than a different wording of the prior one.

Closure is sometimes right, and over-hedging is its own failure mode. Assert plainly when the set is genuinely finite and the skill defines it (e.g., an enum the skill itself specifies), when an invariant truly holds, or for safety constraints, where closing *toward* safety is intentional (see `<content_depth>`). The skill is the discriminator: hedge where you describe an open domain, assert where you define a closed one.

| Closed-world phrasing | Open-world rewrite |
|-----------------------|--------------------|
| "The three valid options are X, Y, Z." (when more may arise) | "Options such as X, Y, and Z." |
| "This is the list of supported platforms." | "Supported platforms include …; check current docs for additions." |
| "X always causes Y." | "X usually causes Y; the outcome can depend on <factors>." |
</open_world_framing>

### Decision Frameworks

<decision_frameworks>
**Focus on WHEN/WHY, not WHAT/HOW.**

Skills should help identify when to use patterns, not teach how to write basic syntax. Include:
- Decision trees and trade-off analyses
- "When to use what" tables
- Context-dependent guidance
- Judgment frameworks for ambiguous situations

**Example format:**
```markdown
| Context | Approach | Why |
|---------|----------|-----|
| Short-lived, personal branch | Rebase | Linear history |
| Shared/public branch | Merge | Preserve collaboration |
| Audit requirements | Merge | Full history trail |
```
</decision_frameworks>

### Proportional Engagement

<proportional_engagement>
**When a skill's overhead exceeds what the task needs, say so and point to a lighter alternative.**

A skill that runs its full process on every invocation adds friction to the small cases it never needed to touch. Where a skill carries real overhead (for example, multi-step workflows, heavy upfront planning, or multi-agent orchestration), state the conditions under which a lighter alternative — a simpler sibling skill, the model's native capabilities, or doing the task directly — is the better choice. This extends `<when_to_use>`'s "do not use for" from a fixed boundary into in-flight judgment: not only when not to start, but when to stop partway. Scope the effort to the task; the goal is the result, not completing the full process for its own sake.
</proportional_engagement>

### Common Mistakes Sections

<common_mistakes_guidelines>
**Every skill should include common mistakes organized by background.**

Structure mistakes by where practitioners are coming from:
- `<from_java>` - Mistakes Java programmers make
- `<from_python>` - Mistakes Python programmers make
- `<from_bash>` - Mistakes bash users make
- `<general_anti_patterns>` - Universal mistakes

**Why background matters:** Different backgrounds create different blind spots. A Java programmer learning Clojure makes different mistakes than a Python programmer learning Clojure.

**Format:**
```markdown
### Common Mistakes

<common_mistakes>
#### From Java Users

<from_java>
- **Using class hierarchies**: Clojure prefers composition via protocols
- **Expecting mutable state**: Atoms/refs for coordinated state changes
</from_java>

#### From Python Users

<from_python>
- **Using None for missing values**: Use nil, but prefer explicit optionality
- **Imperative loops**: Use sequence operations (e.g., map, filter, reduce)
</from_python>
</common_mistakes>
```
</common_mistakes_guidelines>

### Recent Changes Sections

<recent_changes_guidelines>
**Give every skill whose subject moves with releases (e.g., a language, framework, or tool skill) a `## Recent Changes` section, tagged `<recent_changes>`, dated against a stated baseline.**

Assume the models that run the skill were trained through a cutoff date, so everything that changed in the subject after that date is unknown to them unless the skill says it. A section titled "new features" with no date can't serve this purpose: the reader can't tell which entries are new relative to its own knowledge, and the author can't tell when an entry has fallen behind the models' knowledge.

**Baseline.** Use the oldest *reliable knowledge cutoff* — Anthropic's term for the date through which a model's knowledge is most extensive and reliable, as distinct from the broader training data cutoff — among the models in the comparison table on Anthropic's models overview page (currently Haiku, Sonnet, Opus, and Fable),[^8] and cite that page. The oldest cutoff, not the newest, because the skill can't know which model is running it: an entry a model with a later cutoff already knows costs a few tokens, while an entry omitted for a model with an earlier cutoff produces stale output. State the baseline date and the versioned model it comes from (e.g., Claude Haiku 4.5, not "Haiku") in the section's first sentence, so a later maintainer can see at a glance whether the baseline is still the oldest.

**Content.** Cover every change after the baseline that bears on the guidance the skill gives or on the output the model would produce with it, not only additions; a change with no such bearing (for example, an internal compiler improvement) stays out. The kinds to look for:
- Additions, grouped by release and dated.
- Behavior changes, i.e., existing code that now does something different (for example, an execution-semantics change behind a feature flag).
- Deprecations and removals.
- Community shifts, i.e., practices, libraries, or references the community is moving away from. Trained knowledge treats whatever was idiomatic at the cutoff as still idiomatic, so a shift the release notes never mention (for example, a style guide going dormant, or a package superseding a standard-library type) is exactly what the model can't know.

Cite each entry to a release announcement, evolution proposal, release note, or other primary source (see `<citation_requirements>`). Where the skill covers a change in depth elsewhere, point to that section rather than restating it; information lives in one place (see `<skill_anatomy>` on progressive disclosure). Keep entries to a sentence or two; details go in references or in local documentation the skill points to.

**Maintenance.** Two events change the section: a new release of the subject adds entries, and a change in the model lineup moves the baseline forward, after which entries older than the new baseline are removed. The retrofit runbook (`references/retrofitting-existing-skills.md`) checks both.

**Format:**
```markdown
## Recent Changes

<recent_changes>
**Baseline: {month} {year}.** This section assumes trained knowledge of {subject} through that date — the reliable-knowledge cutoff of {model-version}, the oldest among the current Claude models[^claude-models] — and lists what has changed since: additions, behavior changes, deprecations, and what {subject} or its community is moving away from. Treat anything older as known.

**Additions**, by release:
- **{subject} {version}** ({date})[^release]: {one-sentence summaries}

**Behavior changes, deprecations, and things being moved away from:**
- **{change}**: {what changed, what to do now}[^source]
</recent_changes>
```
The footnote labels in the template (`[^claude-models]`, `[^release]`, `[^source]`) are suggested keys, not placeholders; rename them to match the skill's own key scheme.
</recent_changes_guidelines>

### Cross-References

<cross_reference_guidelines>
**Reference authoritative skills; briefly restate the principles essential to this skill's domain.**

**Strategy:**
1. **Primary reference**: Point to authoritative skill for detailed guidance
   - For example, "See `opinionated-software-engineering:test-driven-development` skill for general testing philosophy"
2. **Insurance duplication**: Restate essential principles briefly (1-2 sentences)
   - Core philosophy can be restated in case referenced skill not loaded
   - Safety-relevant "avoid X" rules worth repeating
3. **Balance**: Enough context to work standalone, not so much that skill

…(truncated)