Skip to content

How to Build an Agent Skill: A Step-by-Step Guide

Build an Agent Skill to automate specialized workflows across Claude surfaces. Learn to create portable directories with YAML metadata and instructions.

Tuan Tran Van
7 min read
Contents (11 sections)
  1. Step 1 — Pick the repeated task worth packaging as a Skill
  2. Step 2 — Write the evaluations before you write any instructions
  3. Step 3 — Scaffold the Skill in your skills directory
  4. Step 4 — Write the name and description that decide when the Skill fires (for members)
  5. Step 5 — Write the body and pick the right degree of freedom (for members)
  6. Step 6 — Test with Claude and iterate on what you observe (for members)
  7. Step 7 — Install it for the project or share it with your team (for members)
  8. Checklist before you share a Skill (for members)
  9. Common problems when a Skill does not fire (for members)
  10. What to do next (for members)
  11. References (for members)

By following this guide, you will finish with a working, portable Agent Skill that automates specialized tasks across Claude surfaces.

This architecture lets you package procedural knowledge into modular directories, so you can build an Agent Skill that scales from simple text heuristics to complex, script-driven operations.

Before you start, you need a terminal to run commands, a local directory to work in, and access to a Claude product — the Claude API, Claude Code, or the claude.ai web interface.

A .claude/skills/ directory open in an editor, showing the SKILL.md file inside an Agent Skill

Step 1 — Pick the repeated task worth packaging as a Skill

Identify a manual, multi-step workflow or a set of domain-specific rules you keep pasting into chat windows. If a task requires deterministic execution or consistent formatting — where "hallucination" in the procedure is unacceptable — it belongs in a Skill. High-value candidates include PDF manipulation such as complex form filling, checking marketing copy against brand guidelines, or running multi-layered, domain-specific code reviews. If your CLAUDE.md has grown into a procedure rather than a set of facts, that section is the candidate.

Step 2 — Write the evaluations before you write any instructions

Define your success criteria before drafting a single line of instruction. Create at least three representative test cases that reflect the varied inputs your Skill will handle. Run these prompts against Claude without a Skill active to get a performance baseline; that shows the specific failure points where Claude's native reasoning needs the explicit guardrails your Skill will provide.

The evaluations-first loop: run the task with no Skill to get a baseline, write the Skill, run again, then compare against that baseline

Step 3 — Scaffold the Skill in your skills directory

Agent Skills are filesystem-based directories, not standalone files. This structure lets the Skill include secondary reference materials and executable scripts without bloating the primary context. Create the Skill directory and the required entry point:

bash
mkdir my-skill && touch my-skill/SKILL.md

Verify the directory exists. Claude looks specifically for SKILL.md to bootstrap the Skill's logic.

Read more

Agent Skills: Structure, How They Work, and Where to Use Them

Agent Skills extend AI agents with modular, reusable procedural knowledge and workflows, using a filesystem-based format that keeps token use low.

Share this article

X / TwitterFacebookLinkedIn
← All tools