Contribute your creativity
Guides

How to Write an Agent Skill (SKILL.md): A Beginner's Guide

Write your first Agent Skill: the folder layout, the SKILL.md fields, a template and tips for descriptions the agent will actually match.

Published October 23, 2026Updated October 23, 2026

An Agent Skill is a reusable set of instructions an AI agent loads when a task needs it. Anthropic says it is donating the open standard to the Agentic AI Foundation, so the format below comes from the public specification at agentskills.io. Support differs between products, so check your tool’s docs.

The folder layout

A skill is a directory with at least one file, SKILL.md. The spec lists optional folders: scripts/ for code, references/ for extra documentation and assets/ for templates or data. The name must match the directory name.

The SKILL.md fields

The file starts with YAML frontmatter, then Markdown instructions.

  • name (required): up to 64 characters, lowercase letters, numbers and single hyphens, not starting or ending with a hyphen.
  • description (required): up to 1024 characters. It should say what the skill does and when to use it, with keywords that help the agent recognise relevant tasks.
  • license, compatibility, metadata, allowed-tools (optional). The spec marks allowed-tools as experimental.

A template (our own example)

---
name: weekly-newsletter-draft
description: Drafts a weekly newsletter from bullet notes in our house style. Use when the user asks for a newsletter, a weekly update or a recap email.
---
# Weekly newsletter draft

1. Ask for the bullet notes if none were given.
2. Group them under at most three headings.
3. Write a two-sentence opener, then one short paragraph per heading.
4. End with one clear call to action.

## Edge cases
- If the notes are under five bullets, write a short note instead.

Tips for skills that work

  1. Write the description as a trigger. “Helps with PDFs” is a poor description; name the actions and the situations, as the spec’s good example does.
  2. Keep the body short. The spec recommends instructions under 5,000 tokens and a SKILL.md under 500 lines, with detail moved to separate files.
  3. Use progressive disclosure. Agents load only name and description at startup, the full body when the skill is activated, and other files only when needed.
  4. Add examples and edge cases. The spec recommends step-by-step instructions, example inputs and outputs, and common edge cases.
  5. Validate it. The spec points to a skills-ref validate command to check your frontmatter.
  6. Be careful what you install. Anthropic’s roadmap includes security guidance for people who write and install skills; read a skill before you add it.
stay in the loop

New guides, prompts and AI model news by email