Skill Lab

Learn what an AI agent skill is, how people use and write them, how skills fit into automated workflows, and compare your own skills side by side.

1. What is a skill?

An AI agent skill is a folder of instructions (and optionally scripts and reference files) that an agent loads when a task matches the skill's description. Think of it as an onboarding guide for a new hire: you don't retrain the model, you hand it a written procedure for one kind of job.

Without a skill

You paste the same 40-line instructions into every chat, or the agent guesses your preferences every time.

With a skill

The agent sees a one-line description, recognizes when it applies, and loads the full procedure on its own.

Portable

The format is an open standard (agentskills.io), so the same folder can work in Claude Code, other coding agents, and more.

Sources: Anthropic engineering post, Agent Skills specification.

2. Anatomy of a skill

Startup: name + description loaded
→
Task matches: full SKILL.md loaded
→
Needed only: scripts/ references/ assets/

This is progressive disclosure: the agent pays a small token cost for every skill (metadata), a bigger cost only for the skill it actually uses (body), and loads extra files only when a step needs them.

Metadata (always)
~100 tokens
SKILL.md body
< 5,000 tokens recommended
Bundled files
unbounded, loaded on demand
my-skill/
├── SKILL.md        # Required: frontmatter + instructions
├── scripts/        # Optional: code the agent can run
├── references/     # Optional: long docs loaded only when needed
└── assets/         # Optional: templates, sample files

The frontmatter (the only required part)

---
name: weekly-kpi-report
description: Builds the weekly KPI dashboard summary from the sales CSV. Use when the user asks for a weekly report, KPI summary, or dashboard update.
---

# Weekly KPI report
1. Read the CSV in data/ ...
FieldRequiredRule
nameYes1–64 chars, lowercase letters, digits, hyphens. No leading/trailing or double hyphens. Must match the folder name.
descriptionYes1–1024 chars. Say what it does AND when to use it, with keywords the user would say.
license, compatibility, metadataNoExtra info for other people and tools.
allowed-toolsNoExperimental. Pre-approved tools for the skill.

Source: agentskills.io/specification

3. How people use skills

IndividualPersonal workflow

Writing style, code review checklist, your company's report format. Stored in ~/.claude/skills/ or similar.

TeamShared in a repo

Committed to .claude/skills/ so every teammate gets the same deploy or test procedure.

CommunityInstalled from a hub

Browse skills.sh or GitHub, install a skill like a package. Popular examples: writing-plans, systematic-debugging, test-driven-development.

Rough mix of skill categories (illustrative, not measured)

Dev workflow / planning
Testing & debugging
Documents (PDF, Word, Excel)
Browser automation
Your own domain (dashboards, reports)

The bar lengths are a rough illustration of the category mix, not measured data. Use them as a sense of the landscape.

4. Write your first skill (step by step)

1

Pick one repeatable task

Good: "turn meeting notes into action items". Too broad: "help me with work". A skill should be something you do again and again.

2

Do the task once with the agent, then write down what you corrected

Your corrections are the most valuable part. They are the rules your skill needs.

3

Write the SKILL.md

Keep the body short. Claude is already smart; only add what it does not know: your format, your tools, your rules.

4

Test with 3 real prompts

Anthropic's guide recommends at least three evaluations. Test with the models you actually use.

5

Iterate from failures

When the agent misses, add the missing rule. When it over-applies, narrow the description.

Example: a small, good skill

---
name: meeting-action-items
description: Turns meeting notes into a table of decisions, owners and due dates. Use when the user pastes meeting notes or asks for action items, follow-ups or a recap.
---

# Meeting action items

1. List decisions first, one per line, in past tense.
2. For each action: owner (name, or "UNASSIGNED"), task (verb first), due date (or "NONE").
3. If a date is relative ("next Friday"), convert it using today's date and state the exact date.
4. End with a list of open questions. Do not invent owners or dates.

## Output format
| # | Owner | Task | Due |
|---|-------|------|-----|

Why it works: the description contains the words the user will say ("meeting notes", "action items"), the steps are specific, and it forbids the one mistake people hate (invented owners).

Good vs. weak description

Weak
description: Helps with meetings.

The agent cannot tell when to load it.

Strong
description: Turns meeting notes into action items with owners and due dates. Use when the user pastes notes or asks for a recap.

Says what, when, and which keywords trigger it.

5. How to grow a skill over time

Most good skills are not written in one go. They evolve through a loop:

Use it
→
Notice a correction
→
Add the rule
→
Test on past cases
→
Move big parts to references/
Stage A: Plain prompt. One Markdown file, a few rules. Fine for a week of use.
Stage B: Structured skill. Clear steps, output template, examples of good and bad output.
Stage C: Skill with resources. Scripts for fragile steps (e.g. a validator), references for long specs.
Stage D: Tested and shared. Eval cases, versioned in git, used by a team or published.

Design principles to check against

Sources: Skill authoring best practices, Agent Skills specification.

6. Skills in automated workflows

A skill tells the agent how to do a task. Automation decides when it runs and what happens around it. Claude Code's docs and Anthropic's guide describe several layers that work together:

Skill (know-how). Loaded when relevant or invoked by name like /deploy. Holds the procedure.
Subagent (isolation). Runs the skill in its own context and returns only a summary. Good for parallel work and keeping the main chat clean.
Hook (deterministic trigger). A shell command, HTTP call or prompt that runs on a lifecycle event (e.g. after an edit, before a command). Always runs; the model does not have to choose it.
Scheduler / script (time trigger). A cron job or managed agent that runs the skill every day, like a daily digest.
MCP (connection). Gives the agent access to external services (Notion, Gmail, databases). Skills tell it what to do with those tools.

Example pipeline: weekly KPI report

Cron: Monday 9am
→
Skill: weekly-kpi-report
→
Subagent: pull CSV
→
Hook: validate output
→
Publish via MCP

Automation patterns people use

PatternWhat it looks likeRole of the skill
Plan → execute → verifywriting-plans, then executing-plans, then a verification passEach step is a skill with a checklist
Parallel fan-outSeveral subagents each handle one part of a taskDefines the job each subagent does
Scheduled digestCron searches sources and writes a summary to a pageHolds the format, sources and rules for the digest
Event-driven checkA hook runs a linter after every file editThe hook is deterministic; the skill explains how to fix the errors
Autonomous loopAgent works through a task list, commits passing work, retries failuresEach item follows the same skill; verification gates completion

Rule of thumb

Use a skill for procedures you want the model to follow with judgment. Use a hook for things that must always happen. Use a subagent for work that should not flood your main context. Put a schedule around the skill when it should run without you.

Sources: Claude Code: extend features overview, Claude Code hooks guide, Steering Claude Code: skills, hooks, rules, subagents, skills.sh: agent workflow skills.

7. Compare tool: check your SKILL.md against the spec

Want to take a skill apart and rebuild it? Open the Skill Canvas: it breaks a SKILL.md into cards you can drag, edit and export as a new skill.

Paste two SKILL.md files, or load one from a GitHub URL. The tool checks the rules from the spec, then compares size, structure and description quality. Everything runs in your browser; nothing is uploaded.

Skill A

Skill B

8. Case study: a design skill taken apart

frontend-design is Anthropic's public skill for building interfaces that do not look templated. It is a useful one to study because it has no scripts and no reference files: everything it does, it does with words. Open it in the Skill Canvas →

Size71 lines, about 1,500 words

Roughly 2,350 tokens, about half of the 5,000 recommended for a body. One file plus a license.

ShapeA brief, not a checklist

Five sections of prose. The only numbered list is a catalogue of looks to avoid, not a procedure.

FreedomHigh, on purpose

Design is a judgment call, so the skill gives reasons and priorities and leaves the choices to the agent (see "match freedom to risk" in section 5).

Where the words go (measured)

Title & role
67 words
Ground in the subject
110 words
Design principles
426 words
Process
460 words
Restraint & self-critique
126 words
Writing in design
255 words

Word counts per section of the file as of November 2026. Six in ten words sit in two sections: the principles and the process.

What each section does

Section in the fileCanvas card typeJob
Title and opening paragraphTitle & overviewSets a role (design lead at a studio) and the stakes: the client has already rejected templated work.
Ground your designs in the subject matterNotesBefore designing, name the subject, the audience and the page's main job. Distinctive choices come from the subject's own world.
Design principlesRulesPositions on the hero, typography, structure, motion and copy. Each names the default treatment and says when it is justified.
Process: plan, review, build, critiqueStepsLists five looks that generated designs cluster around, then sets a two-pass method: write a token plan, test it against the brief, only then write code.
Restraint and self-critiqueNotesBe bold in one place only. Sets a quality floor (responsive, keyboard focus, reduced motion) and asks for screenshot reviews.
More on writing in designNotesInterface copy rules: name things the user's way, buttons say what happens, errors explain the fix.

Card types are what the Skill Canvas assigns from each heading. Three of five land in "Notes" because the headings describe ideas, not the usual Steps / Rules / Output slots.

Techniques worth copying

Name the default, then ask for a choice. "Be distinctive" gives a model nothing to act on. The skill lists the exact looks a model drifts to (specific hex values, the rounded-card kit, numbered 01 / 02 / 03 markers), so the agent can recognize them in its own draft.
A gate before the expensive step. The plan is a short token list: 4–6 named colors, typefaces and their roles, a layout sketch, principles. The agent must check that plan against the brief and revise it before writing any code.
A clear order of authority. The brief always wins, even when it asks for one of the listed defaults. The skill only governs what the brief leaves open, so it does not fight the user.
Rules come with reasons. Numbered markers are allowed only if the content really is a sequence. A reason lets the agent handle cases the author did not list.
A quality floor, stated once. Accessibility and responsiveness are a single sentence of non-negotiables, kept apart from the taste guidance.

What this site's checks say

Flagged
  • The description says what the skill does but has no "Use when …" clause. At 29 words it is still specific enough to trigger on UI work.
  • No examples section (a Skill Canvas tip). The skill describes looks in words and never shows one.

Compare tool score: 88 / 100. The Canvas does not flag missing steps, because it counts the numbered catalogue of looks as steps. The real method is written as paragraphs.

Passes
  • Name format, description length (204 of 1,024 characters) and body length (well under 500 lines).
  • No vague filler phrases. Even the taste guidance is concrete enough to test.

Paste it into the Compare tool above to see the score next to your own skill.

What to take from it

For judgment-heavy work, write the skill as a brief: a role, the failure you want to avoid described in detail, a checkpoint before the costly step, and a rule for who wins when instructions conflict. Save numbered steps and scripts for tasks where one wrong move breaks things.

Source: anthropics/skills: frontend-design (Apache 2.0). The analysis is this site's own reading of the file.

9. Videos and articles to learn from

Official docs and articles

Videos

Video titles and channels are as listed on YouTube at the time of research. Check the length and date before watching.