Module 3 · Skills

Your First Skill

A skill is astonishingly simple: a folder with one Markdown file. Let's dissect that file, then build one live in the browser.

7 min read

Lesson 2.1

A folder and a file

A skill is a directory containing a single required file, SKILL.md. That's the whole requirement. Where the directory lives decides who can use the skill:

  • Personal: ~/.claude/skills/<name>/, available in all your projects.
  • Project: .claude/skills/<name>/, checked into the repo, shared with your team.
  • Plugin / enterprise: distributed or centrally managed.

The name you'll care about most is the directory name, because that becomes the command you type. A folder called design-guide/ gives you /design-guide. We'll see that mapping happen live in a moment.

Lesson 2.2

Anatomy of a SKILL.md

Every SKILL.md has two parts: a small block of YAML frontmatter (metadata) and a Markdown body (the actual instructions). Here's the first version of our running example. Tap any numbered line to see what it's doing.

---
name: design-guide
description: Apply the team's design system when building or
  changing UI. Use when creating a component, page, or
  screen, or reviewing a change for visual consistency.
---
 
# Design Guide
 
Apply the house design system so every screen looks like
one product, not a patchwork.
 
## Steps
1. Pull colors, type, and spacing from the design tokens.
2. Compose from existing components before adding new ones.
3. Check text on its background meets AA contrast.
 
Every color and size comes from a token; never a raw hex value.

↑ Tap the numbered lines. There are 6.

1
The frontmatter fences. Everything between the two --- lines is YAML metadata. This block is Tier 1: it's the only part loaded at startup so the agent can decide whether the skill is relevant.
2
name: lowercase, digits and hyphens only. This (and the folder name) is what becomes the command: /design-guide.
3
description: the single most important line in the file. It's how the agent decides to use the skill at all. Note it says what it does AND when to use it. Module 4 is devoted to getting this right.
4
The body begins after the closing fence. This is Tier 2: read only once the skill is judged relevant, so it doesn't cost anything until it's needed.
5
A simple workflow. Numbered steps give the agent a clear procedure to follow. Keep the body focused; it stays in context across turns once loaded.
6
A guardrail. One concrete constraint is worth more than a paragraph of vague guidance. We'll say much more about calibrating this in the advanced track.

That's a complete, working skill. No configuration, no registration: dropping this folder in place is enough for the agent to discover it.

Different AI tools have their skills in differently named folders. For example claude uses .claude/skills whereas codex uses .codex/skills. If you are unsure just ask the agent to create and save a skill and it will find the correct folder

Lesson 2.3 · Interactive

Build one live

Here's the skeleton: a folder with an empty SKILL.md inside it. Fill in the frontmatter and body on the left, then name the folder to match the skill's name. The folder stays grey until they match; get it right and it turns green. Watch the right update in real time: the derived /command, the card the agent sees, and a live validity check.

Your skill foldername it
/
└ SKILL.md
SKILL.mdeditable
What the agent seeslive

Try this: set name: design-guide in the frontmatter, then type design-guide into the folder above. When they match, the folder turns green and the /command settles. Mismatch them (capitalize one, or misspell it) and watch the folder check go red.

Your skill folder is named styleguide/ but the frontmatter says name: design-guide. In Claude Code, what command does it create?

Lesson 2.4 · Interactive

See it invoked

You built the skill; now watch it run. Below is a scripted terminal session simulating an interaction with a claude agent: the agent starts, the request matches your design-guide skill by its description, and only then does it load the full SKILL.md body. Press run to type it out. (It's a playback, not a live shell — deterministic and offline by design.)

~/documents $ claudeClaude Code · 3 skills loaded (design-guide, git-workflow, jira)> Build a settings page for the dashboard.⏺ Matched skill: design-guide — its description fits the request ⎿ Loaded SKILL.md body into context (only now, on match)⏺ Pulling colors, type, and spacing from the design tokens…⏺ Composing from existing components · checking AA contrast…✓ SettingsPage created — on-brand, tokens only, first try.

Notice the order: the skill is matched first (from its one-line description), and the body is loaded after. That timing is the whole point of the next module.

Lesson 2.4 · Interactive

What the skill actually changes

Same agent, same request: “Build a settings page for the dashboard.” The only difference is whether the design-guide skill exists. Press run and watch both agents work. Notice when the skilled agent pulls in its instructions: not at startup, but the moment the request matches; it gathers the context it needs, only when it needs it.

User “Build a settings page for the dashboard.”
Without the skill
In context at startup
General knowledge only
  1. Request arrives. No house style on hand; the agent improvises from generic defaults.
  2. Asks you to fill the gaps. “Which colors? What spacing? Should it match anything?”
  3. Guesses a look. Hardcodes raw hex values and invents its own spacing scale.
  4. Off-brand output. Looks nothing like the rest of the app; you send it back.
Works, eventually, but it leans on you for the design rules and the result drifts screen to screen.
With the design-guide skill
In context at startup
description (1 line · Tier 1) SKILL.md body, loaded on match
  1. Request arrives. Only the one-line description is loaded, just enough to judge relevance.
  2. Match → pull the guide. The description fits, so the agent loads the full SKILL.md body now, dynamic context.
  3. Follows the guide. Pulls colors and spacing from tokens, reuses existing components, checks AA contrast.
  4. On-brand output. Looks like the rest of the app first try, no back-and-forth needed.
The design rules live in the skill, loaded only when the request matches: cheap at rest, reliable on demand.

This is Dynamic Context, and it's the whole reason skills scale: the agent carries thousands of one-line descriptions cheaply, then pulls the full instructions into context only for the one skill a request actually needs. Module 3 goes deep on it.

Recap

Takeaways

Takeaways

1. A skill is a folder with a SKILL.md; its location decides its scope.
2. The file is frontmatter (name, description) + a Markdown body of instructions.
3. The directory / name becomes the /command; keep it kebab-case.
4. The description is what the agent matches on; treat it as the most important line.

Built your first skill?

Mark it done and move on to keeping skills cheap.