how-to

# How To: Create a New Skill

A walkthrough for building a new Claude Code skill from scratch with [`/skill-builder`](../skills/han-plugin-builder/skill-builder.md): describe what the skill should do, answer the interview that walks the skill's design tree decision-by-decision, and end with a real skill on disk that has already passed a guidance-conformance review. This is the recipe for *using* the builder; the [skill-building guidance](../../han-plugin-builder/skills/guidance/references/skill-building-guidance/) is canonical for the rules the builder enforces.

> See also: [How-to index](./README.md) · [`/skill-builder`](../skills/han-plugin-builder/skill-builder.md) · [`/guidance`](../skills/han-plugin-builder/guidance.md) · [Create a new agent](./create-a-new-agent.md)

The happy path below builds a skill into a plugin that already exists, because that is the common case: you have a plugin and you want to add a slash command to it. When the skill belongs in a brand-new plugin, the [Variations](#variations) section covers the one extra thing the builder does for you.

## Before you begin

- You have installed the opt-in `han-plugin-builder` plugin. The `han` meta-plugin does not bundle it, so install it on its own first with `/plugin install han-plugin-builder@han`. See [Choosing a Han plugin](../choosing-a-han-plugin.md) for where it sits in the suite.
- You know roughly what the skill should do and what should trigger it. You do not need a finished design; the interview walks the tree for you. But a sharp one-line request ("a skill that turns a changelog into release notes, triggered when I say 'draft release notes'") lets the builder start walking immediately, where a thin one ("build a skill") makes it ask for this first.
- You have a sense of whether this is a skill at all. A skill is a deterministic, flowchartable process. If the work is a judgment layer that reasons over messy input rather than following steps, it is an agent, and the builder will stop and redirect you to [`/agent-builder`](../skills/han-plugin-builder/agent-builder.md). [Create a new agent](./create-a-new-agent.md) is the matching guide. When you are not sure which you want, [`/guidance`](../skills/han-plugin-builder/guidance.md) answers "is this better as a skill or an agent?" before you start.

## What you'll end up with

- A skill written into the target plugin at `{plugin}/skills/{skill-name}/SKILL.md`: frontmatter with a `name` matching the directory, a four-component `description` under 1024 characters, scoped `allowed-tools`, and a body of numbered process steps following the workflow pattern the interview settled.
- Any `references/`, `scripts/`, or `assets/` the skill needs, created only when a use case justified them. No empty or speculative folders.
- A closing summary from the builder: which decisions it settled by evidence versus which it asked you, the fixes the review pass applied with the guidance document behind each, and the triggering and functional tests derived from your use cases.

## The happy path

The workflow runs as one continuous interview, but it moves through three natural stages: you frame the skill, the builder walks the design tree with you, and then it writes and reviews the files. Each stage is a place you can stop and look at what you have.

### Stage 1: Frame the skill and name the plugin

1. **Run [`/skill-builder`](../skills/han-plugin-builder/skill-builder.md) with one or two sentences on what the skill does and what triggers it.** Lead with the trigger and the outcome, not the mechanism. Two examples that give the builder enough to start:

    > `/skill-builder` *"I want a skill that summarizes the day's merged PRs into a standup update."*

    > `/skill-builder` *"Add a skill to han-github that closes stale issues after confirming with me."*

2. **Name the target plugin, or let the builder infer it.** If you name one ("add a skill to han-github"), the builder confirms it ships skills and reads its existing siblings. If you do not, it infers candidates from the repository and confirms with you before writing anywhere.

3. **Bring the two or three concrete use cases, or let the builder derive them.** These are the spine of the whole design: they drive the description's trigger phrases and become your test cases at the end. The sharper they are going in, the less the interview has to ask. If you only have a vague idea, the builder derives candidates and confirms them with you.

### Stage 2: Walk the design tree

1. **Answer one question at a time, in dependency order.** The builder never batches questions, because later answers routinely make earlier ones moot. It settles foundational decisions (which plugin, the use cases) before identity (name, description), before workflow (the pattern and the steps), before capabilities (tools, dispatch, scripts) and layout (body versus references versus scripts versus assets).

2. **Take the recommendation, or redirect it.** Every question comes with a recommended answer and the evidence behind it. Anything the repository can answer (sibling descriptions, conventions, the target `plugin.json`, the guidance documents) the builder answers by exploring, so you are only asked the questions evidence cannot settle. When a recommended workflow pattern or tool set is wrong for your case, say so; the builder resolves the dependent decisions from your redirect rather than starting over.

3. **Let it disambiguate the description against the siblings.** When the skill joins a plugin that already has skills, the description has to trigger for your cases and *not* trigger for the neighbors'. The builder reads the sibling descriptions and writes the new one to draw a clean line between them. This is the step that keeps two skills in the same plugin from fighting over the same prompts.

### Stage 3: Write, review, and test

1. **Let the builder write the files and run the conformance review.** Writing the `SKILL.md` is not the last step. The builder