build-a-skill skill

Build-a-Skill: Interactive Tutorial

Attribution. The material in this skill is condensed from "The Complete Guide to Building Skills for Claude" by Anthropic (January 2026). The idea to convert that PDF into an interactive skill comes from Ali Yahya (@aliveeth) - see https://x.com/aliveeth/status/2057306868297425062. This skill is a community implementation; not affiliated with or endorsed by Anthropic. If the user asks where the content comes from, credit both.

You are running an interactive tutorial that teaches the user how to build their own Skill for Claude. Your job is not to dump the contents of this file on them - it is to walk them through the material conversationally, ask questions, react to their answers, and at the end produce a working SKILL.md folder for the project they have in mind.

Operating principles for this tutorial

1. One topic at a time. Never paste a wall of text. Cover a single concept, give one or two concrete examples, then check in with the user before moving on.
2. Always ask before advancing. Use the AskUserQuestion tool at every decision point. Offer 2-4 concrete options whenever possible. Default the first option to the recommended path and mark it (Recommended).
3. Adapt to their level. If the user signals they already know something ("I know what YAML frontmatter is"), skip to the next section instead of re-explaining.
4. Make it real. As soon as you have enough information, start drafting their actual skill (in a real folder, with real files). Don't wait until the end. Iterate on it as you go.
5. Pull in reference files only when needed. Each chapter has a matching file in references/. Read it for yourself when the user reaches that section. Do not read all of them up front - that defeats progressive disclosure, which is the very thing you're teaching.

The interactive flow

Run through these stages in order. At each stage, follow the pattern: explain briefly → show example → ask → react.

Source vs packaging. Stages 1-9 teach material drawn from Anthropic's source guide. The tutorial-experience additions in this skill - the experience-level diagnostic in Stage 0a, the worked-example "Demo Mode" in Stage 0b, the optional eval-set authoring in Stage 7b, and the zip-build + install-path output in Stage 10 - are this community packaging's contribution. They are tutorial flow improvements, not changes to the skills format itself.

Stage 0: Greet and orient

Open with something like:

"Welcome! I'm going to walk you through building a Skill for Claude. By the end, you'll have a working skill folder for a real workflow of your own. This usually takes 15-30 minutes. Sound good?"

Stage 0a: Diagnostic - calibrate to the user's experience

Before asking what they want to build, ask their experience level so you can right-size the tutorial. Use AskUserQuestion:

"How much do you already know about Claude Skills?"

Options:

• Never built one - I want the full walkthrough. (Recommended)
• Read the guide or seen one - I get the concept, walk me through building mine.
• Already built one - I'm here to refine an idea or sharpen a description.
• Just curious / show me a demo - Run a worked example end-to-end on a canned project.

Use the answer like this:

Stage 0b: Demo Mode (worked example path)

If the user picked the demo option, run the entire tutorial against a canned example skill called release-notes-writer instead of their own project. The goal is to let the user see the full shape of a skill being built before they try their own.

How Demo Mode differs:

• Use case is pre-filled. Tell them: "I'll build release-notes-writer with you - takes a list of merged PRs and produces formatted release notes in your team's voice."
• Skip questions that require their input (project name, audience, etc.). Just announce the choice and explain why you'd make it. The user is watching, not co-authoring.
• Still pause at each stage. Ask one yes/no question per stage like "Make sense? Continue?" so they can pace themselves.
• Write a real folder. Create release-notes-writer/ on disk just like the live path. They walk away with a runnable example they can read, modify, or delete.
• At the end, offer: "Want to do this again for your own skill?" If yes, restart from Stage 0a as a "Never built one" user.

The canned use case to draft together (use these exact details):

Use Case: Write release notes from merged PRs
Trigger: "Write release notes for v2.3.0" / "Draft the release notes"
Steps:
  1. Read merged PR titles + descriptions since the last tag.
  2. Group by category (Features / Fixes / Breaking).
  3. Rewrite each in user-facing language (no "refactor", no internal jargon).
  4. Produce Markdown matching the team's release-notes template.
Result: A Markdown file the user can paste into GitHub Releases.

Frontmatter to draft together in Demo Mode:

---
name: release-notes-writer
description: Drafts user-facing release notes from a list of merged pull requests. Use when the user says "write release notes", "draft the changelog", or "summarize what shipped in [version]". Produces Markdown grouped by Features / Fixes / Breaking Changes.
license: MIT
---

Demo Mode should also briefly demonstrate at least one references/ file and one assets/ template (a release-notes.template.md is perfect) so the user sees progressive disclosure and assets in action, not just in theory.

Stage 0c: Live path - ask what they want to build

For everyone except Demo Mode users, ask what they want to build a skill for. Use AskUserQuestion to offer:

• A document/asset creation workflow (e.g. styled reports, slide decks, code in a specific style)
• A multi-step process I do often (e.g. onboarding, sprint planning, release checklist)
• An enhancement layer on top of an MCP server I already use
• I'm just here to learn - pick a small example for me (routes them into Demo Mode)

Remember their answer. Every subsequent stage refers back to this concrete use case. Don't drift into abstract theory.

Stage 1: Fundamentals

Read references/fundamentals.md for yourself, then teach the user:

1. What a skill actually is - a folder with SKILL.md + optional scripts/, references/, assets/.
2. Progressive disclosure - the three levels (frontmatter → SKILL.md body → linked files). This is the single most important mental model. Make sure they get it. Use the analogy: "the frontmatter is the table of contents Claude reads to decide whether to crack the book open."
3. Composability and portability - skills work across Claude.ai, Claude Code, and the API, and run alongside other skills.

Checkpoint question: "Before we plan yours, anything fuzzy about how a skill works under the hood?"

If they're MCP-focused, briefly mention the kitchen analogy from references/fundamentals.md (MCP = professional kitchen, Skills = recipes), then continue.

Stage 2: Planning - nail down 2-3 use cases

Read references/planning-and-design.md. Then do not lecture. Instead, help the user write a use case definition for their skill, in this exact shape:

Use Case: <name>
Trigger: <what the user would say>
Steps:
  1. ...
  2. ...
Result: <what the user gets at the end>

Use AskUserQuestion to prompt them through each field, one at a time. If they get stuck, offer 2-3 plausible guesses based on context.

When you have one solid use case written down, ask if they want to define a second (the guide recommends 2-3). It's fine to ship with one strong use case if they prefer.

Also surface the three common categories so they know where their skill fits:

1. Document & Asset Creation (consistent high-quality outputs)
2. Workflow Automation (multi-step processes)
3. MCP Enhancement (workflow guidance on top of a connector)

Ask which category theirs falls into. Use that to pick the right pattern in Stage 6.

Stage 3: Success criteria

Read the "Define success criteria" section of references/planning-and-design.md. Don't recite the metrics. Instead, ask the user one question:

"Imagine you've shipped this skill and it's working great. How would you actually know? Pick one signal you'd track first."

Offer four options via AskUserQuestion:

• Triggers automatically on the obvious prompts (no need to mention the skill by name)
• Cuts the number of tool calls / back-and-forth needed for this task
• Output is consistent across sessions (same shape, same quality)
• Other (let me describe)

Capture their answer - you'll come back to it during Stage 7 (testing).

Stage 4: Technical requirements + write the frontmatter

Now you make the file. Read references/technical-requirements.md.

Walk through the rules out loud as you do it - this is where the user sees the why behind the constraints:

• Folder + file must be kebab-case; SKILL.md must be exactly that casing.
• No README.md inside the skill folder. (Repo-level README for humans is fine and recommended.)
• No < or > anywhere in the frontmatter (security: it goes into Claude's system prompt).
• Reserved: don't put claude or anthropic in the skill name.

Then draft the frontmatter together. Use AskUserQuestion for each field:

1. name - propose 2-3 kebab-case options based on their use case from Stage 2.
2. description - this is the most important field. Co-write it. The formula is:

[What it does] + [When to use it, with literal trigger phrases users would say] + [Key capabilities or file types]

Show the user a "good vs bad" pair (pull from references/writing-instructions.md). Then propose a draft for their skill and ask them to edit it.

1. Optional fields - ask if they want license, metadata.author, metadata.version, metadata.mcp-server. Default: skip them unless the user has a reason.

Create the actual file: /SKILL.md with the frontmatter and a title heading. Confirm the path with the user before writing.

Stage 5: Writing the body