/expert-skill-creator

name: expert-skill-creator
description: Expert-level guidance for creating high-quality Claude Code skills, complementing Anthropic's skill-creator, which covers basic skill mechanics. Covers research-driven content development, XML tag structuring, decision frameworks over mechanics, model targeting, cross-references between skills, citations, and systematic validation. Invoke when creating a new skill, improving, refactoring, or upgrading an existing skill (e.g., after a new Claude model release), evaluating or validating a skill's content, deciding a skill's architecture, structure, or content depth, or researching content for a skill, even if the request does not use the word "skill".

Expert Skill Creator

<skill_scope skill="expert-skill-creator"> **Related skills:**

• `skill-creator:skill-creator` (Anthropic) - Basic skill mechanics (e.g., directory structure, packaging) and an evaluation loop for testing skills
• `opinionated-software-engineering:software-engineer` - Design principles that inform skill architecture
• `opinionated-software-engineering:test-driven-development` - Validation methodology parallels

**Load this skill together with Anthropic's `skill-creator:skill-creator` when creating skills.** `skill-creator:skill-creator` covers basic mechanics (e.g., directory structure and packaging) and an evaluation loop for testing skills; this skill covers content quality, structure, and validation.

A skill is a modular package that extends Claude's capabilities with specialized knowledge, workflows, and tool integrations. It functions as a *retrieval trigger* that activates and organizes Claude's trained knowledge, not as teaching material that explains concepts from scratch. Because a skill activates existing knowledge, too much detail *constrains* behavior rather than enhancing it: give high-level frameworks that trigger trained knowledge, and reserve detailed content for areas that are novel to the model or where the model makes mistakes.

**Model calibration:** By default, skills written with this skill target the Opus and Fable lines; write an agent or skill that runs on a Sonnet or Haiku model for that line. Target the fewest lines a skill needs (see `<model_targeting>`), and before writing guidance that depends on how a model behaves, read the per-line reference files listed in `<reference_files>`.

**Out of scope.** If this skill was invoked for one of the following, use the resource named or proceed without this one:

• General prompt engineering (this skill covers skills only)
• Subagent packaging mechanics (e.g., tool lists, agent frontmatter fields); agent prompt *content* follows similar quality principles (see `<directive_language>`), and choosing a worker's model is covered in `references/choosing-worker-models.md`
• Skill frontmatter syntax beyond `name` and `description` (this skill notes only which fields work outside Claude Code); for fields and features such as `context`, `agent`, `allowed-tools`, `hooks`, argument substitution, and dynamic context injection, see Claude Code's skills documentation[^20]
• One-off instructions that don't warrant a reusable skill

</skill_scope>

Reference Files

<reference_files> Guidance used at specific steps is in `references/`. Read each reference file in full, from its first line to its last, when the step that names it begins. A partial read (e.g., a `head` preview or a limited line range) can miss rules later in the file, and nothing in the part read indicates what was skipped.

| Read this file | When | Sections it holds | |----------------|------|-------------------| | `references/creating-skills.md` | Starting a new skill | `<creation_process>` (steps 1-7), `<research_phase>` | | `references/retrofitting-existing-skills.md` | Upgrading or refactoring an existing skill | The staged retrofit procedure | | `references/composition.md` | Designing a skill used together with other skills or agents | Composition patterns, `<composition_contracts>` | | `references/citations.md` | Adding sources, citations, or a Resources section | `<citation_format>`, `<citation_accuracy>`, `<source_verification>`, `<citation_mistakes>`, `<resources_guidelines>` | | `references/recent-changes.md` | Writing or updating a Recent Changes section | `<recent_changes_guidelines>` | | `references/validation.md` | Before reporting a skill complete, and before committing | `<validation_phase>`: `<content_validation>`, `<positive_control>`, `<empirical_validation>`, `<plagiarism_validation>`, `<pii_and_secret_scanning>`, `<per_commit_publication_gate>`, `<consistency_validation>` | | `references/prompting-fable.md`, `references/prompting-opus.md`, `references/prompting-sonnet.md`, `references/prompting-haiku.md` | Before writing guidance that depends on how a model behaves, for each model line the skill will run on | Documented behavior of that line, by version, with retired claims | | `references/choosing-worker-models.md` | Designing a skill or agent that spawns subagents | How a worker's model is set; what each model line is good and bad for |

A tag named in this skill but not found in the file being read is in the file this table lists for it.

This SKILL.md body is longer than the soft target in `<content_organization>` because its writing rules (e.g., `<directive_language>`, `<literal_language>`, `<model_targeting>`) apply to every instruction an author writes, so they stay in the body rather than in a reference file read at one step. </reference_files>

Skill vs. Subagent Decision

<skill_vs_subagent_decision> **Before designing a skill, use the table below to confirm that the task calls for a skill and not a subagent.** Skills and subagents can do overlapping work but differ in who writes the task and in whether the work runs in the main conversation or in an isolated context, and converting one into the other later costs more than choosing correctly at the start.

The core discriminator: who writes the task?

<task_autho