og.cc.cd / guides / how-to-write-skill-md

How to Write a SKILL.md: Agent Skills Format, Fields and Examples

By og.cc.cd · Published · Updated · 4 min read

TL;DR: An Agent Skill is a folder with a SKILL.md whose name and description frontmatter tell the agent when to load it; put detailed instructions in the body so they cost context only when needed.

Updated · All sources ↓

An Agent Skill is a folder with a SKILL.md file that teaches an agent how to do one specific job — fill a PDF form, run a release, follow your API conventions. The agent sees only the short description until the skill is needed, so skills can hold detail that would be too expensive to keep in every prompt.

Generate a SKILL.md →All guides

The anatomy of a skill

The open Agent Skills specification defines a skill as a directory containing at minimum a SKILL.md file:

pdf-processing/
├── SKILL.md          # required: metadata + instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: docs loaded on demand
└── assets/           # optional: templates, schemas, images

SKILL.md is YAML front matter followed by Markdown instructions. Claude Code follows this standard and adds its own extensions.

The two fields that matter most

name

  • 1–64 characters; lowercase letters, digits and hyphens only.
  • Must not start or end with a hyphen, and must not contain --.
  • Must match the parent directory name. pdf-processing ✓, PDF-Processing ✗, -pdf ✗.

description

Required by the spec, 1–1024 characters, and the single most important line you will write: the agent uses it to decide whether to load the skill at all. Say what the skill does and when to use it, with the keywords users actually type.

# Good
description: Extracts text and tables from PDF files, fills PDF forms, and merges
  multiple PDFs. Use when working with PDF documents or when the user mentions
  PDFs, forms, or document extraction.

# Poor
description: Helps with PDFs.

Optional fields in the spec

FieldPurpose
licenseLicense name or bundled license file
compatibilityUp to 500 characters on environment needs, e.g. “Requires git and docker”
metadataFree key-value map (author, version…)
allowed-toolsSpace-separated pre-approved tools; experimental, support varies

Progressive disclosure: why skills are cheap

The spec describes three loading levels: the name and description (about 100 tokens) load at startup for every skill; the full SKILL.md body (under 5,000 tokens recommended) loads when the skill is activated; files in scripts/, references/ and assets/ load only when needed. So: keep SKILL.md under 500 lines, move detailed reference material into separate files, and reference them with relative paths one level deep (for example references/REFERENCE.md).

A complete example

---
name: release-notes
description: Drafts release notes from merged pull requests since the last git tag.
  Use when the user asks for release notes, a changelog entry, or "what shipped".
license: MIT
metadata:
  author: example-team
  version: "1.2"
---

# Release notes

## Steps
1. Find the last tag: `git describe --tags --abbrev=0`.
2. List merged PRs since that tag: `git log <tag>..HEAD --merges --oneline`.
3. Group entries under **Added**, **Changed**, **Fixed**. Skip chores and CI.
4. Write one line per change in the past tense, linking the PR number.
5. Follow the template in [assets/template.md](assets/template.md).

## Edge cases
- No tags yet: use the first commit as the start.
- Breaking changes: put them first under **Breaking**, with migration steps.

## Example
Input: 3 merged PRs (#41 feature, #42 bug fix, #43 CI).
Output: one Added line (#41), one Fixed line (#42); #43 omitted.

Using skills in Claude Code

  • Locations: personal skills in ~/.claude/skills/<name>/SKILL.md; project skills in .claude/skills/<name>/SKILL.md (commit them to share with the team); plugins can ship skills too.
  • Invocation: Claude loads a skill when your request matches its description, or you type /skill-name. Add disable-model-invocation: true for actions with side effects (deploys, sending messages) so only you can trigger them; user-invocable: false hides background-knowledge skills from the menu.
  • Listing budget: in Claude Code’s skill listing, description plus when_to_use is truncated at 1,536 characters — put the key use case first.
  • Portability: claude.ai uploads and the Skills API accept only name, description, license, compatibility, metadata and allowed-tools; Claude Code-only fields such as argument-hint cause an upload error there.

Writing the body: patterns that hold up

  • Write standing instructions. In Claude Code, the rendered SKILL.md enters the conversation once and stays there; it is not re-read on later turns. “Run the tests after every edit” survives a long task better than “Run the tests”.
  • Put the most important rules first. After auto-compaction Claude Code re-attaches the first 5,000 tokens of each invoked skill, within a shared 25,000-token budget.
  • Move deterministic work into scripts. Parsing, validation and file generation are more reliable as a script in scripts/ that the skill tells the agent to run. In Claude Code, ${CLAUDE_SKILL_DIR} resolves to the skill’s folder, and an allowed-tools rule such as Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *) lets it run without a prompt.
  • Show one input and output. A short worked example clarifies more than a paragraph of description.

Skill, CLAUDE.md, rule or hook?

If the guidance is…Put it in
A fact every session needs (build command, layout)CLAUDE.md / AGENTS.md
Only relevant to some filesA path-scoped rule in .claude/rules/
A multi-step procedure used sometimesSKILL.md
Something that must happen every timeA hook or permission rule

Test it like code

  1. Validate the front matter with the reference tool: skills-ref validate ./my-skill.
  2. Write five prompts that should trigger the skill and five that should not; check the hit rate in fresh sessions.
  3. Compare output with and without the skill. If there is no difference, the instructions are too vague or duplicate what the model already does.

Skills complement project files rather than replacing them: facts every session needs belong in CLAUDE.md or AGENTS.md; procedures belong in skills. To scaffold one quickly, choose “SKILL.md” in the generator.

Sources

Vendor features and prices were checked against these official pages on 2026-10-18. Products change; if something here no longer matches, the official page is right.

Related guides