Anatomy of an AgentSkill

The File That Teaches an AI Agent New Tricks

What if you could teach your AI agent a new skill the same way you’d write a memo?

That’s exactly what a SKILL.md file is — a Markdown document that tells an AI agent how to do something it doesn’t already know. No coding. No compiling. No special tools. Just a text file with structure.

Simon Willison, the security researcher who’s been tracking AI agent development, called the AgentSkills spec “deliciously tiny.” And he’s right — the entire specification fits on a single page. Two required fields. That’s it.

But that simplicity is deceptive. Behind those two fields is a system powerful enough to create everything from a simple email formatter to a multi-step research assistant.

What You’ll Learn in This Course

Over 8 lessons, you’ll go from understanding the spec to publishing your own secure skill:

What to Expect

This is an intermediate course. You should be comfortable with OpenClaw basics (the “OpenClaw for Everyone” course covers this). You don’t need to code, but familiarity with text editors and file structures helps.

Each lesson builds on the last. The skills you create in early lessons become the foundation for advanced techniques later.

The AgentSkills Standard

Before we look at the format, let’s understand what problem it solves.

Every AI agent platform had its own way of extending capabilities. Claude Code had its own format. VS Code Copilot had another. OpenClaw had yet another. If you built a skill for one platform, it was useless on the others.

In late 2025, Anthropic proposed a universal standard: AgentSkills. A single SKILL.md format that any compliant agent can read. Build once, use everywhere — in Claude Code, VS Code Copilot, Codex CLI, Cursor, OpenClaw, and more.

The design philosophy was radical simplicity. Barry Zhang and the Anthropic engineering team wrote: the spec uses progressive disclosure — start simple, add complexity only when needed.

✅ Quick Check: Why did the industry need a standard skill format? (Answer: Every platform had its own proprietary format. A universal standard means building once and using the skill across Claude Code, VS Code, OpenClaw, Codex, and more.)

The Three Layers of a Skill

Here’s the progressive disclosure model that makes the whole system work:

Layer 1: Metadata (Always Loaded)

When an agent starts up, it reads just the name and description of every available skill. This is lightweight — maybe 100 characters per skill — so loading hundreds of skills doesn’t slow anything down.

---
name: daily-standup-formatter
description: >
  Formats daily standup notes into a consistent template.
  Use when the user asks to format standup notes or prepare
  for a daily team meeting.
---

That’s a complete, valid skill. Two fields. It works.

Layer 2: Full Instructions (Loaded on Demand)

When the agent decides a skill is relevant to your request, it reads the full SKILL.md body — the Markdown content below the frontmatter. This is where you put detailed instructions:

---
name: daily-standup-formatter
description: >
  Formats daily standup notes into a consistent template.
---

# Daily Standup Formatter

Format the user's standup notes using this structure:

## Yesterday
- What was completed

## Today
- What's planned

## Blockers
- Any obstacles (or "None" if clear)

Keep bullet points concise (one line each).
Always ask for missing sections.

Layer 3: Linked Files (Loaded When Needed)

For complex skills, you can include supporting files in the skill directory:

daily-standup-formatter/
├── SKILL.md           # Main instructions
├── scripts/
│   └── parse-jira.py  # Script to pull Jira tickets
├── references/
│   └── team-style-guide.md  # How the team formats standups
└── assets/
    └── template.md    # The output template

The agent reads these files only when it needs them — not at startup, not when the skill is first invoked, but when the instructions reference them.

✅ Quick Check: Your agent has 200 skills installed. How many of those are fully loaded into memory at startup? (Answer: Zero fully loaded. The agent only loads Layer 1 — name and description — for all 200. Full instructions are loaded only for the skill being used.)

The Required Fields (And What They Do)

Only two fields matter in the YAML frontmatter:

name (required, max 64 characters)

• Lowercase letters, numbers, and hyphens only
• This is how the agent identifies the skill: daily-standup-formatter
• If the skill is user-invocable, this becomes the slash command: /daily-standup-formatter

description (required, max 1024 characters)

• The single most important piece of writing in your skill
• This is what the agent reads to decide whether your skill is relevant
• Write it for the AI, not for humans — be explicit about when to use the skill

The description is your skill’s elevator pitch to the AI. A vague description means the agent won’t know when to use your skill. A precise one means it fires exactly when needed.

Bad description: “A useful tool for formatting things”

Good description: “Formats daily standup notes into Yesterday/Today/Blockers template. Use when the user asks to format standup notes, prepare daily meeting updates, or organize what they worked on.”

Optional Fields Worth Knowing

MCP vs. Skills: What’s the Difference?

You might have heard about MCP (Model Context Protocol). How does it relate?

MCP is plumbing. It defines what tools exist — “there’s a calendar tool, an email tool, a GitHub tool.” It handles the connection layer.

Skills are the brain. They define how to use those tools effectively — “when the user asks for a standup summary, read their Jira tickets via the Jira MCP tool, format them into the template, and ask about blockers.”

You can build skills without MCP, and MCP works without skills. But together, they’re powerful: MCP gives the agent hands, and skills give it knowledge about when and how to use them.

Key Takeaways

• AgentSkills is a cross-platform standard — build once, use in Claude Code, VS Code, Codex CLI, OpenClaw, and more
• Only name and description are required — everything else is optional
• Progressive disclosure loads skill content in three layers: metadata → instructions → linked files
• The description is the most important field — it tells the AI when to use your skill
• Skills are the brain; MCP is the plumbing — skills define how to use tools effectively

Up Next

Theory’s done. In the next lesson, you’ll build your first working skill from scratch — a practical tool you’ll actually use. We’ll go from an empty folder to a tested, running skill in 15 minutes.