Building your first custom skill.

What a skill actually is on disk CORE

A Claude Code skill is a folder. That is the whole story. The folder lives at one of three addresses — user-scope ~/.claude/skills/✓, project-scope <project>/.claude/skills/, or inside a plugin’s skills/ folder. Inside, the only file that is strictly required is SKILL.md. Everything else — example inputs, scripts, templates, reference data — is optional, and lives alongside SKILL.md in the same folder.

SKILL.md has two sections. The frontmatter is a YAML block at the top bounded by --- lines. It carries structured fields the agent reads before it reads anything else — minimally name and description, optionally model (which model this skill prefers), allowed-tools (a list naming which tools this skill may use, for students who want to lock a skill to a narrow tool surface), and a handful of other conventional fields. The body is the prose that follows the frontmatter — the actual instructions the agent consults once it has decided this skill applies.

Concretely, a minimal SKILL.md looks like this — frontmatter on top, body underneath:

---
name: research-sweep
description: One sentence about what this skill does and when to use it.
---

(The body goes here — the step-by-step the agent follows once this skill fires.)

The two --- lines are the fences that mark the frontmatter; everything between them is structured fields the agent reads first. Everything after the closing --- is the body. That is the entire shape; the rest of this lesson is about authoring each half well.

The split is important because the agent reads the frontmatter before it reads the body. When the agent is deciding which of the (possibly dozens of) installed skills to reach for, it reads descriptions — not bodies. A skill whose body is a masterpiece of prompt design but whose description is vague will never fire. A skill whose description is tight but whose body is thin will fire and then do the job badly. Both halves have to be good; they are good for different reasons.

Two corollaries worth naming:

• The description field is a prompt. It is not a blurb for a directory page. Every word in it is consumed by a model making a routing decision. Write it as if you were giving a smart intern instructions for when to pull this folder off the shelf.
• The body is also a prompt. Once the skill fires, the agent reads the body and uses it as instructions for how to do the work. The same rules apply as everything you have learned about prompting — be specific, name the input shape, name the output shape, name the failure modes, show an example.

A useful mental model is that a skill is a two-layer prompt. The outer layer (description) answers “does this job belong to me?” The inner layer (body) answers “given that it does, how do I do it?” A well-authored skill has distinct, honest answers at both layers.

Description as a classifier: three failure modes CORE

Module 7’s headline technical insight is that the description field is not decoration; it is a live classifier. Three predictable ways students write descriptions that fail:

Mode 1 — Vague description, never fires. “Helps with research.” The agent will almost never reach for this skill because nothing distinctive is claimed. Every time the student asks for research help, the agent decides the skill is no more relevant than any other generic option and produces a generic chat response. The student concludes “skills are mysterious” and stops building them.

The fix is specificity: “Runs a multi-source research sweep on a named topic. Use when the user asks to triangulate sources, check citations, produce a sources.md, or build a competitive landscape. Inputs: a topic string. Outputs: a sources.md file with at least three independent sources, one fabrication-risk callout, and a one-paragraph synthesis.”

Mode 2 — Overfit description, fires on adjacent wrong work. “Runs when the user talks about research.” Too broad. The agent will fire this skill on any research-adjacent request — a single summarization, a casual question about a paper, a quick curiosity lookup — whether or not the skill’s actual body is the right tool for that request. The student gets a heavy-weight triangulation procedure applied to a one-line question and wastes tokens, time, and attention.

The fix is bounding: include an explicit exclusion block. “Do not use for single-article summaries, casual curiosity lookups, or when the user has already named sources and only wants you to read them. For those, prefer in-session prompting or the quick-summary skill.”

Mode 3 — Honest-about-inputs, silent-about-triggers. “This skill produces a sources.md with three independent sources and a fabrication-risk callout.” Technically accurate, but the agent reads this and does not know when to use it. It sounds like a description of output, not a trigger for when the skill applies. The agent reaches for it rarely, and when it does, it is by luck rather than design.

The fix is an explicit triggering phrase list: “Use when the user asks for: a research sweep, source triangulation, a sources.md, a competitive landscape, or a fabrication check. Use when the user names a topic and wants independent sources. Do not use when the user wants a single article read or a casual summary.”

A good description is descriptive + inclusive + exclusive, in roughly that order. It describes what the skill does in one sentence, lists the phrases that should invoke it, and names the adjacent cases it explicitly does not cover. The order matters because the description is read top-down by the model; put the description first so the model knows what the skill is before it decides whether to reach for it.

Anatomy of the body: what goes where CORE

The body is the part of SKILL.md that runs once the skill has been chosen. Five sections, in order, have proven to work well across the skills students write in this module:

1. Purpose paragraph (2–4 sentences). A tight restatement of what the skill does and who it is for. Yes, this overlaps the description. It is worth the overlap; the body is the first thing the agent reads as instruction, and starting with purpose re-aligns the model before it does the work.

2. Inputs (one section). List what the skill expects from the user. If the skill takes a topic, say so. If it takes a path to a file, say so. If it tolerates an empty input and will ask a clarifying question, say so. A skill that is silent about inputs will, over many runs, do inconsistent things; describing inputs makes the behavior reproducible.

3. Procedure (the longest section). The step-by-step the agent should follow when the skill fires. Numbered steps. Every step should be concrete — “read the topic, search three source types (academic, news, primary), triangulate disagreements, flag any source that lacks a verifiable link as a fabrication risk, write sources.md with the schema in Appendix A.” Generic steps produce generic output. Specific steps produce the kind of output the description promised.

4. Output contract (one section). What the skill produces. File name conventions, section headings, any required fields. If the skill writes multiple files, name each one. If the skill writes nothing and only returns a chat response, say that and describe the response shape. The output contract is what students use later, in the invocation trace, to verify the skill did the named job.

5. Failure modes (one short section). The predictable ways this skill can go wrong, and what the skill should do when each occurs. “If no independent sources are found, say so and produce a sources.md with only the primary source and an explicit lowconfidence: true flag.” “If the topic cannot be narrowed to a single research question, pause and ask the user to narrow before searching.” This is the section students most commonly skip and most commonly wish they had written when the skill misfires in week three.

Optional sections worth adding when relevant: Examples (one concrete input/output pair is worth more than many abstract sentences), Appendices / schemas (if the output contract references a specific file schema, keep it here), Supporting scripts (if the procedure calls a script for deterministic formatting, the script lives in the same folder and the body refers to it by name).

A good body is short enough to read in one sitting. A skill body that does not fit comfortably in one read is usually two skills.

Walkthrough: the research-sweep skill RECIPE

---
name: research-sweep
description: Runs a multi-source research sweep on a named topic.
  Use when the user asks to triangulate sources, run a research
  sweep, produce a sources.md, check citations, or build a
  competitive landscape on a specific topic. Inputs: a topic
  string. Outputs: a sources.md file with at least three
  independent sources, one fabrication-risk callout, and a
  one-paragraph synthesis. Do not use for single-article
  summaries, casual lookups, or when the user has already named
  sources and only wants them read.
---

1. Read the topic string. If it is unambiguous, proceed. If it
   is broad (e.g., "climate change"), ask one clarifying
   question to narrow to a specific sub-question.

2. Search three source types: academic (Google Scholar, JSTOR
   if available, or the student's library), news (the last 90
   days of major outlets), and primary (government documents,
   official reports, organization statements).

3. Produce at least three independent sources from distinct
   author/institutional bases. A single author's blog post from
   three different dates is one source, not three.

4. Triangulate disagreements explicitly. If sources disagree on
   a fact, name the disagreement and the position of each
   source.

5. Flag any source that does not have a verifiable link or a
   stable identifier as a fabrication-risk with `risk:
   unverified`.

6. Write sources.md with the schema in Appendix A, including a
   one-paragraph synthesis at the bottom.

The three-round tuning loop RECIPE

A skill that passes the smoke test is not a finished skill. It is a candidate. Run the three-round tuning loop before freezing anything. Each round produces a dated entry in CHANGELOG.md so future-you can see what changed and why.

Three rounds is the discipline. Students who skip rounds produce skills that look fine in the first week and quietly misfire by week three. The changelog — even three short entries — is how future-you knows what you learned by tuning.

Freezing the skill into /capstone/ RECIPE

Once the skill has passed all three tuning rounds and produced two real-use traces, freeze it.

Folder layout under /capstone/custom-skill-v1/:

custom-skill-v1/
├── SKILL.md          (frontmatter + body; the only required file)
├── README.md         (2-3 paragraphs: what this skill is, why
│                      you built it, how to install)
├── CHANGELOG.md      (dated entries from your three tuning rounds)
├── appendices/
│   └── schema.md     (output contract schema if your body
│                      references one)
├── scripts/
│   └── (any helper scripts)                    (optional)
└── traces/
    ├── 2026-04-XX-real-run-1.md
    └── 2026-04-XX-real-run-2.md

Not every folder is required. A skill that uses no scripts does not need scripts/. A skill with no schema does not need appendices/. The SKILL.md, README.md, CHANGELOG.md, and traces/ are required.

Register row. In /capstone/extension-register-v1-draft.md, fill in the custom-skill row using the template from /resources/module-07/extension-register-row-template.md. Key fields:

• Type: Claude Code skill, authored.
• What it does: one sentence, in the same shape as your frontmatter description.
• Where it lives: both the live install path (~/.claude/skills/<name>/) and the frozen path (/capstone/custom-skill-v1/).
• Invocation: two or three phrases that reliably trigger it.
• Audience: only me.
• Budget / model: rough per-invocation cost estimate + the model family the skill is written against.
• Next review: a date sooner than the standard 90-day cadence. Authored skills drift faster in your first year of authoring, so they earn a tighter review window.
• Keep/retire: the condition that would make you retire (e.g., “retire if I stop doing project-based research for a full semester”).