Skills: Teaching an AI Agent Processes

What problem do they solve?

An agent without special instructions does what it can with what it knows. When a task has its own steps (reviewing a form against your accessibility guide, preparing an article in your format, deploying in a fixed order), you have to teach it those steps.

You could write all of them in the permanent instructions file, but that has a cost: every session loads that whole file, even when the task has nothing to do with it. Skills resolve that tension. The procedure lives in its own folder and enters the context only when needed.

Skills are also an open format, created by Anthropic and published as a standard at agentskills.io. Other tools have adopted it, such as Cursor, Codex, Gemini CLI and GitHub Copilot. A well-written skill is not tied to a single product.

How is a skill written?

A skill is a folder. The only required file is SKILL.md; it can also include scripts, references or templates:

check-contrast/
├── SKILL.md          # required: metadata + instructions
└── references/
    └── wcag-summary.md

A SKILL.md has two parts. The YAML frontmatter holds the name and the description. The Markdown body holds the procedure:

---
name: check-contrast
description: Checks text contrast on a screen against WCAG. Use it when the user asks to review color accessibility.
---

Below the frontmatter come the steps: what to read, what to check, how to report. In Claude Code every field is optional, but the documentation recommends at least description; the name defaults to the folder name and is what you type to invoke it (/check-contrast).

What separates a good skill from a mediocre one:

• Small scope. One procedure, not an entire library.
• Description with concrete verbs. It says what the skill does and when to use it, with the main case first. In Claude Code, the description is cut off at 1,536 characters in the skill listing, so the important part goes first.
• Clear input and output. The body starts with what it needs (which file or which screen) and ends with the report format.
• A stopping rule. It says when to ask instead of continuing to guess.
• Tested on real cases. Try it on two or three before you share it.

If the procedure is a long task that should not fill your conversation, Claude Code can run it in a subagent with its own context window (context: fork). That subagent does not see your conversation, so the skill must carry explicit instructions.

Where does it live and how is it loaded?

According to the Claude Code documentation, a skill can live in several scopes. The three you will use most:

For a team, the project path is the most useful: the documentation recommends committing it so everyone gets it, and the version sits in git next to the code.

Loading is progressive. The description of each skill is in the context from the start. The body loads only when the skill is invoked, and from then on it stays in the conversation. Support files, such as a long reference, are read only if the SKILL.md says when to read them. The documentation recommends keeping the main file under 500 lines and moving detail into separate files.

When to use a skill and when to use CLAUDE.md?

The Claude Code documentation suggests creating a skill when a section of CLAUDE.md “has grown into a procedure rather than a fact.” In its memory guide it adds that a multi-step procedure should move to a skill. In practice:

If you put a procedure in CLAUDE.md, you pay for it in every session. If you put it in a skill, you pay only when you use it.

A skill is not a good fit in these cases:

• The instruction is a short fact. A paragraph in CLAUDE.md is enough.
• The procedure changes so much that the skill is outdated within a week. That judgment is still reviewed by hand.
• The action has side effects and there is no approval step. For publishing or deploying, use disable-model-invocation: true so only you launch it.

Why does it matter to a designer?

Because skills turn a design judgment into a repeatable process, and they are part of context engineering: deciding what enters the context and when. A person who knows how they review a screen can write it as a procedure, and the whole team runs the same review. Some design tasks that fit well in a skill:

• A screen review checklist with its “done” criteria.
• A procedure for writing microcopy that follows the tone guide.
• A flow that turns an interview into findings with evidence.

Example

Illustrative example: a team has a 300-line CLAUDE.md with accessibility rules, tone rules and a screen review procedure. The agent ignores part of the rules because the file is overloaded. The team moves the review into a skill called review-screen, with a clear description and a five-point checklist. CLAUDE.md shrinks to the rules that always apply. When someone asks for a screen review, the agent loads the skill and follows the full checklist; the rest of the time, that text takes up no context.

A minimal body for that skill could look like this:

## Input
A screen (file or screenshot) and the flow it belongs to.

## Steps
1. List the texts and colors used.
2. Check contrast, text size and focus states.
3. Report each finding with: where it is, why it matters and how to fix it.

## If information is missing
Ask which component it is before proposing changes.

Common mistakes

• Writing a vague description such as “helps with design.” The agent does not know when to use it.
• Putting huge procedures in the body without support files.
• Duplicating the same rule in the skill and in CLAUDE.md, and letting them contradict each other. Keep one source for each rule.
• Letting the agent launch a skill with side effects, such as deploying, on its own.
• Creating skills for every task at once. Start with the ones the team repeats.

Sources

• Extend Claude with skills, Claude Code documentation
• How Claude remembers your project, Claude Code documentation
• Create custom subagents, Claude Code documentation
• Agent Skills: open format, agentskills.io