All instructional content in this skill comes from Anthropic. It is a community-built interactive packaging of "The Complete Guide to Building Skills for Claude" (Anthropic, January 2026). Every concept, example, pattern, and best practice originates from that guide. This repository is not affiliated with, endorsed by, or sponsored by Anthropic. Please read the original PDF for the canonical, authoritative material.
An interactive Claude Skill that walks you through designing, writing, testing, and distributing your own Skill for Claude - the way most "guides" should work now that you have a world-class educator in your pocket.
Instead of reading a 33-page PDF, you load this skill and your agent teaches you conversationally: it asks what you want to build, helps you nail down use cases, drafts the YAML frontmatter and instructions with you, walks you through testing, and runs a pre-flight checklist before you ship.
Mid-tutorial: the agent walks you through the concepts and checks understanding with multiple-choice prompts before moving on.
- Source material — owned by Anthropic: "The Complete Guide to Building Skills for Claude" (January 2026). All conceptual content, examples, patterns, and best practices in this skill come from that guide.
- Idea to convert the PDF into a skill: Ali Yahya (@alive_eth) — "Why is this a PDF?? We now all have a genius world class educator in our pocket. This 'guide' should be a skill file that gets your agent to walk you through everything you need to know interactively. That is how most education should work going forward."
- This packaging: a transformative derivative work under MIT license. It does not re-license Anthropic's underlying guide, which remains their property.
build-a-skill/
├── SKILL.md # Interactive tutorial flow (entry point)
└── references/
├── fundamentals.md # What a skill is, progressive disclosure, MCP + skills
├── planning-and-design.md # Use cases, success criteria, the three categories
├── technical-requirements.md # Folder/file rules, frontmatter fields
├── writing-instructions.md # SKILL.md body: structure, specificity, examples
├── scripts.md # When to bundle code, invocation, security (community-expanded)
├── assets.md # Templates and static reference files (community-expanded)
├── patterns.md # Five workflow patterns to choose from
├── testing-and-iteration.md # The three lightweight tests every skill should pass
├── evals.md # Optional 5-prompt eval set for regressions (community addition)
├── distribution.md # Individual / team / world / API
├── troubleshooting.md # Common failure modes and fixes
├── checklist.md # Pre-flight checklist before shipping
└── resources.md # Links to the original guide and further reading
The skill itself is a small example of progressive disclosure: SKILL.md is the lean entry point, and the chapter-by-chapter material lives in references/ so Claude only loads what's needed for the user's current stage. Files marked "community-expanded" or "community addition" go beyond the source guide; see the per-file scope notes at the top of each one for details on what's source-derived vs. practitioner convention.
Two-step install (this is the path the official guide recommends):
- From Releases (recommended): grab the latest
build-a-skill-vX.Y.Z.zipfrom github.com/egalano/build-a-skill/releases/latest. The zip extracts to abuild-a-skill/folder containingSKILL.md. - Or clone the repo:
git clone https://github.com/egalano/build-a-skill.git.
For Claude.ai (web or desktop):
- Open Claude.ai → Settings → Capabilities → Skills.
- Click Upload skill.
- Select
build-a-skill-vX.Y.Z.zip(or zip thebuild-a-skill/folder yourself if you cloned). - Toggle the skill on.
For Claude Code:
# After cloning or unzipping
cp -r build-a-skill ~/.claude/skills/Start a new conversation and say one of:
- "Walk me through building a skill"
- "Teach me how to make a Claude skill"
- "/build-a-skill"
The skill should load automatically and the tutorial will begin.
If you'd rather skim the source material than be tutored through it, the chapter files under build-a-skill/references/ are condensed, human-readable summaries of the original guide.
Total time: about 15-30 minutes for a working first skill. The agent will:
- Calibrate to your level. A quick diagnostic up front - never built one? Already shipped one? - lets the tutorial skip what you already know.
- Ask what you want to build, or run Demo Mode on a canned
release-notes-writerexample if you're just here to see the shape. - Cover fundamentals (what a skill is, progressive disclosure, how it composes with MCP) - briefly, and only the parts you don't already know.
- Help you write 1-3 concrete use cases.
- Pick a success signal you actually care about.
- Draft your YAML frontmatter with you (especially the
descriptionfield, which is the single most important thing). - Co-write the body of
SKILL.md. Addscripts/,assets/, or anevals/set if your skill needs them. - Pick the workflow pattern that fits your category.
- Walk you through triggering tests, functional tests, a quick before/after comparison, and optionally build a tiny eval set for regression protection.
- Show you how to distribute it (just yourself, your team, the world, or via API).
- Run a pre-flight checklist.
- Build a real
.zipand print the absolute install paths, ready to paste into Claude.ai orcpinto~/.claude/skills/.
At the end you'll have a real folder and a real zip on disk - both immediately installable.
Each tagged release ships as a single build-a-skill-vX.Y.Z.zip on the Releases page. The zip is the exact shape Claude.ai's Upload skill dialog and Claude Code's ~/.claude/skills/ directory expect - no repackaging needed.
Release notes are generated by .github/workflows/release.yml from three sources:
- The matching section in
CHANGELOG.md(the curated narrative). - The git commit list since the previous tag.
- Auto-appended install instructions for Claude.ai and Claude Code.
If you're contributing a change, add an entry under ## [Unreleased] in CHANGELOG.md. At release time it gets moved into a versioned section and ends up in the release notes verbatim.
These are improvements to the tutorial experience, not changes to the underlying skills format taught by the source guide.
- Experience-level diagnostic up front so the tutorial right-sizes itself (skips Fundamentals if you already know them, etc.).
- Demo Mode that runs the whole flow against a canned
release-notes-writerexample, so you can watch a skill being built before doing your own. - End-of-tutorial deliverable: the agent builds a real
.zipand prints absolute install paths for both Claude.ai and Claude Code. - New reference chapters:
scripts.md,assets.md, andevals.md(the first two expand on optional folders the source guide mentions; the third adds a regression-protection layer on top of the source guide's three lightweight tests). - Pre-flight checklist updated with scripts/assets/evals checks and a zip-listing sanity check.
Initial release - condensed, conversational packaging of The Complete Guide to Building Skills for Claude (Anthropic, January 2026) as an interactive skill.
MIT. See LICENSE. Adapt freely.
The MIT license covers this packaging only. The underlying conceptual content - examples, patterns, and best practices - is owned by Anthropic and quoted/summarized here under fair use for educational purposes. If you redistribute or adapt this skill, preserve attribution to both the original guide and this packaging.
If you find a chapter that's missing, a pattern that's wrong, or a question the tutorial doesn't handle well, open an issue or a PR. When adding material that goes beyond the source guide, please flag it with a "community contribution" scope note at the top of the file (as scripts.md, assets.md, and evals.md do) so readers can tell source-derived material from practitioner convention.