How to Write Your First Agent Skill

A practical, accurate walkthrough of Agent Skills: the SKILL.md format, why the description is the trigger, and how to test one before you ship it.

Give an agent a folder with a name, a description, and a set of instructions, and it can learn to do something new — without you rewriting its system prompt. That's an Agent Skill, and it's a small idea with an outsized effect on how far an agent can go before it needs a human back in the loop.

This piece covers what a skill actually is, how an agent decides to reach for one, and how to write and test your first one. If you haven't built an agent at all yet, start with how to build your first AI agent — this is the natural next step once you have something running.

What an Agent Skill is

An Agent Skill is a packaged, reusable capability that an agent can discover and load on demand. Concretely, it's a directory containing a SKILL.md file — plain Markdown with a small YAML frontmatter block up top — plus, optionally, scripts, templates, or reference documents the skill needs to do its job.

Anthropic introduced this as an open format for Claude, and other agent platforms have since adopted it — this isn't a Claude-only quirk, it's becoming a shared convention for packaging agent expertise.

The frontmatter requires exactly two fields:

  • name — a unique identifier, lowercase with hyphens
  • description — what the skill does, and when the agent should use it

Everything below the frontmatter is the instruction body: the steps, the format, the constraints, what done looks like. That's it. No special runtime, no new API — just a folder an agent can read.

The anatomy of a skill

Here's a minimal, realistic skill for turning rough meeting notes into a structured summary:

---
name: meeting-notes-summarizer
description: Summarizes raw meeting notes or transcripts into a structured
  format with decisions, action items, and owners. Use when the user pastes
  meeting notes, a transcript, or asks to "summarize this meeting" or
  "turn these notes into action items."
---

# Meeting Notes Summarizer

Given raw meeting notes or a transcript, produce a structured summary with
three sections: Decisions, Action Items (with an owner and, if stated, a
due date), and Open Questions.

## Steps

1. Read the full input before summarizing anything — decisions made late
   in a meeting sometimes reverse earlier ones.
2. Attribute action items to a named owner. If no owner is stated, write
   "unassigned" rather than guessing.
3. Keep each bullet to one sentence. Do not include filler or small talk.
4. If the notes contain no clear decisions or action items, say so
   explicitly rather than inventing them.

## Output format

Use three `##` headings — Decisions, Action Items, Open Questions — each
with a bullet list. Omit a section entirely if it has no content.

That's a complete, usable skill — nothing mandates a bundled script, and plenty of real skills are instructions only. Scripts and reference files come in when the task needs deterministic logic (parsing a specific file format, running a fixed command sequence) that you don't want to leave to the model's judgment on every run.

The description is the highest-leverage sentence you'll write

Here's the part that's easy to underrate: at startup, the agent doesn't load the full instruction body of every installed skill. It loads only the name and description of each one — a small footprint, often cited around 100 tokens per skill — into its context. When a task comes in, the agent matches that task against the descriptions it has in view. Only once a skill looks relevant does it read the rest of SKILL.md into context.

That makes the description a routing rule, not documentation. It has to do two jobs in one or two sentences: say what the skill does, and say when to reach for it, ideally in the language a real request would use (when the user pastes meeting notes, not for note processing). A vague description (helps with meetings) either never triggers or triggers on the wrong things. A precise one, written in the vocabulary of the trigger phrases you actually expect, does most of the work before the agent has read a single instruction line. If you write nothing else in a skill carefully, write the description carefully.

Why a skill should do one thing

Skills compete for the agent's attention at match time, and an overloaded skill is harder to trigger correctly and harder to trust once it's running. A skill named office-tasks that tries to handle emails, spreadsheets, and calendar invites has a mushy description by necessity — more likely to fire when it shouldn't, less likely to fire when it should.

The fix is the same discipline you'd apply to a well-designed function or a single-purpose tool: one skill, one clear responsibility, one crisp trigger condition. If you find yourself writing and in the description to cover unrelated jobs, that's a sign you need two skills, not one. A focused skill also stays short, which means it fits comfortably in context and doesn't leave the agent guessing which half of the job applies right now.

Skills, tools, and MCP servers aren't the same thing

These three get conflated constantly, worth being precise about:

  • A tool is a single callable action with a defined input/output contract — send an email, query a database, run a search. See how to design tools your AI agent can actually use for how to shape those well.
  • An MCP server is a live connection that exposes tools and data to an agent at request time — it's the plumbing that makes external systems reachable. If you haven't seen how that piece fits together, what MCP is and why it matters covers it.
  • A skill is procedural knowledge — instructions for how and when to use tools (including MCP-provided ones) to get a specific job done well.

Put plainly: MCP gives an agent access, tools give it actions, and a skill gives it judgment — the know-how of how to actually do this task, including the parts that are easy to get subtly wrong. A skill can call MCP tools as part of its instructions; it isn't a substitute for them, and they aren't a substitute for it.

Writing your first skill, end to end

  1. Pick one narrow, recurring task — something you or your agent redoes often enough that writing it down once pays for itself, not a one-off.
  2. Write the description first. Draft the exact phrases a real request would use to ask for this, and build the description to match them.
  3. Write the instructions as if briefing a competent contractor with zero context on your conventions: the steps, the constraints, the output format, and what to do when the input is ambiguous.
  4. Add resources only if the task needs them — a reference file for a schema, a script for something that must be deterministic. Don't bundle files just in case; every file the skill loads is context the agent has to reconcile against the instructions.
  5. Keep the body tight. If it's sprawling, the skill is probably trying to do more than one job — split it.

Testing a skill

A skill fails in exactly two places, so test both:

  • Does it trigger correctly? Run the exact phrases you expect real requests to use, plus near-miss phrases that should not trigger it. If a skill fires when it shouldn't (or stays silent when it should catch something), the fix is almost always in the description, not the instructions.
  • Does it do the job once triggered? Run it against a handful of real inputs, including messy edge cases — the meeting with no clear owner, the transcript with no decisions at all. Judge the output against what a careful human would produce, not just whether it ran without error.

Iterate on both independently. A skill with perfect instructions and a vague description never gets used; one with a great description and sloppy instructions gets used at the wrong moments and produces bad output when it does.

Where this fits

A single skill is a small unit of leverage. The payoff compounds once an agent has a library of them — each narrow, each precisely triggered, each doing one job well — alongside a well-designed toolset and the right MCP connections behind it. That's the fuller picture in how to build your first AI agent: skills are a lever you pull once the agent's basic loop is working, not a replacement for getting that loop right first.

← Back to Articles