/expert-skill-creator

name: expert-skill-creator
description: 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.

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 sever