How to build a skill in Claude: anatomy of 8 real ones

Anthropic's official guide covers the format. This page covers what the format looks like in the wild — we dissected the structure of every skill package we tested, from a 43k-star official pack to a 103-star solo project, and the good ones converge on the same skeleton.

The minimum viable skill

my-skill/
  SKILL.md        # frontmatter (name, description) + instructions

That is genuinely all a skill is: a markdown file whose frontmatter identifies it and whose body instructs the agent. defuddle, the smallest skill in our batch, is 41 lines total and ships inside kepano's five-pack doing exactly one job. Start here; the rest of this page is what to add when you need it, not a checklist.

The frontmatter is your activation surface

Two required fields, one of which does all the work:

---
name: kill-ai-slop
description: >-
  Find and remove AI slop ... Use when the user asks to "kill AI slop",
  "de-slop", "remove the AI look", "make this not look AI-generated" ...
---

Every well-triggering skill we tested writes its description as an enumerated trigger list — the phrases users actually type, the file formats, the app names. The description is what the model sees before deciding to load your skill; the body is only read after. Budget your best writing there. (More on this mechanism in our activation guide.)

The three-layer pattern the good ones share

my-skill/
  SKILL.md          # layer 1: routing — short, points to references
  references/       # layer 2: deep knowledge, loaded on demand
  scripts/          # layer 3: deterministic helpers the agent runs

This is progressive disclosure, and it appears independently in almost every mature skill we opened: kill-ai-slop routes to detection.md/fixes.md/taxonomy.md and ships a scanner script with its own tests; obsidian-bases keeps a large format reference out of the initial load; CodeDrobe's SKILL.md is explicitly "instruction-only," routing to per-app references. The principle: keep SKILL.md short enough to be cheap every time, push bulk into references the agent opens only when relevant, and make anything that must be exact — scanning, parsing, applying — a script rather than prose. Judgment in markdown, determinism in code.

Two architectures beyond the single skill

The multi-skill repo: a skills/ directory with one skill per subfolder (kepano ships five; Remotion ships ten). The installer handles it natively — users pick with -s or take all. Split when the jobs are separable; our obsidian test showed why it matters that four of five skills work without the app installed.

The skill-plus-runtime: CodeDrobe's pattern — the skill is a thin workflow layer driving a published npm package, so logic updates ship through npm without touching the skill. The moment your scripts/ folder starts feeling like a product, this is the graduation path.

Ship it like the ones people actually install

Everything we tested installs via npx skills add owner/repo — put that one-liner at the top of your README (with the https form, not ssh: we watched kepano's ssh-first instructions fail on a keyless machine). Version your SKILL.md frontmatter (hallmark carries version: 1.1.0), and test your own install instructions in a clean directory — the single most common failure mode we see in the wild is instructions that only work on the author's machine. The agentskills spec keeps your skill portable to Codex, Cursor and the rest for free.

FAQ

Skill, slash command, or MCP server?

Skill: knowledge and workflow the model applies with judgment. Slash command: an explicit entry point you type. MCP server: tools and live data access. GSD Core, notably, installs all three kinds at once — commands for entry, agents and skills for behavior.

How do I test a skill before publishing?

Clean-room it: fresh directory, install from your public repo exactly as your README says, fresh session, then try the natural phrasings you claim to handle — not just the skill's name. That loop (which is this site's entire methodology) catches both broken installs and non-firing descriptions before your users do.