SKILL.md Explained: Format, Frontmatter, and Examples

What SKILL.md Does

A SKILL.md file is both a trigger and an operating manual. The frontmatter helps an agent understand whether the skill is relevant. The Markdown body tells the agent what to do after the skill is loaded. That split matters because agents should not load every detailed instruction file for every task.

A skill file is not just documentation. It is operational context that changes how an agent behaves.

The best SKILL.md files are specific, compact, and easy to maintain. They name one workflow, describe when to use it, define the output standard, and point to supporting files only when those files are actually needed.

The Basic SKILL.md Format

A practical SKILL.md has two parts: YAML frontmatter at the top, then Markdown instructions below it. The frontmatter is wrapped in triple dashes. The body can use headings, lists, examples, and links to nearby files.

---
name: support-reply-review
description: Review customer support replies for clarity, empathy, accuracy, and next-step quality before they are sent.
---

# Support Reply Review

Use this skill when the user asks for a review of a customer support reply,
an escalation update, or a resolution message.

## Process

1. Identify the customer's core issue and emotional state.
2. Check whether the reply acknowledges the issue directly.
3. Flag any promise that may be too specific or unsupported.
4. Rewrite the reply only if the user asks for a rewrite.

## Output

- Readiness: ready, needs edits, or risky
- Main issue: one sentence
- Suggested edits: concise bullets
- Optional rewrite: only when requested

This file is intentionally plain. It does not try to encode every support scenario. It gives the agent enough structure to run the review consistently, while leaving detailed policies or tone examples to optional reference files.

Frontmatter: What Each Field Should Do

Frontmatter should help the agent decide whether the skill belongs in the current task. Treat it like a precise search result, not a marketing blurb. The description should include the action, the object, and the trigger conditions.

The description is the most important line in the file. If it is vague, the agent may miss the skill when it should load it, or load it when the task needs something else.

Weak vs Strong SKILL.md Descriptions

A useful description answers three questions quickly: what task does this skill handle, what input does it expect, and what output should it produce? Here are common before-and-after patterns.

Good skill descriptions are narrow enough to trigger correctly and concrete enough to prevent the agent from guessing.

How to Structure the Markdown Body

The body should explain the workflow in the order an agent needs it. Start with use conditions, then process steps, then output expectations, then edge cases. Do not lead with background unless the background changes the work.

1. Use conditions: Say when to use the skill and when not to use it.
2. Inputs: List what the agent needs from the user, repo, document, or current context.
3. Process: Give the repeatable steps the agent should follow.
4. Output format: Specify headings, bullets, tables, code blocks, or final answer shape.
5. Quality checks: Add the few rules that prevent common failures.
6. References: Point to supporting files when detailed material should be loaded only as needed.

The skill body should make the right behavior easy, not describe every possible behavior. If a section does not change what the agent does, cut it or move it into a reference file.

When SKILL.md Should Point to Other Files

Multi-file skills are useful when the workflow needs reference material but the main instruction file should stay lean. Common supporting files include templates, example outputs, brand voice guides, API notes, rubric documents, and scripts.

client-recap/
|-- SKILL.md
|-- references/
|   |-- recap-rubric.md
|   `-- account-health-signals.md
`-- templates/
    `-- qbr-recap.md

Inside SKILL.md, tell the agent when to open each file. Do not simply list every file. For example: "Use templates/qbr-recap.md only when the user asks for a client-ready recap." That keeps the skill efficient and prevents irrelevant context from crowding out the actual task.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude, so your setup follows you across every machine, repo, and tool.

This portability matters because SKILL.md files often start as local experiments. One skill lives in a repo, another on your old laptop, and another in a teammate's notes. A managed library keeps those working instructions from becoming scattered artifacts you have to rebuild later.

A Complete SKILL.md Example

This example shows a realistic skill for turning meeting notes into an internal decision memo. Notice that it includes use conditions, output requirements, and a quality check, but avoids writing a full essay inside the skill.

---
name: decision-memo
description: Convert rough meeting notes, Slack threads, or call transcripts into a concise internal decision memo with context, options, decision, rationale, risks, and next steps.
---

# Decision Memo

Use this skill when the user provides messy notes and wants a clear decision
record. Do not use it for external announcements or customer-facing updates.

## Required Inputs

- Raw notes, transcript, or thread
- Audience, if known
- Decision owner, if known

If the decision is unclear, state the ambiguity before drafting.

## Process

1. Extract the decision being made.
2. Separate facts from opinions and unresolved questions.
3. Identify the options considered.
4. Capture rationale without overstating certainty.
5. Flag risks, dependencies, and follow-up owners.

## Output

Use these sections:

- Context
- Options considered
- Decision
- Rationale
- Risks and open questions
- Next steps

Keep the memo under 700 words unless the user asks for more detail.

This format works because it is reusable without being rigid. It gives the agent enough constraints to produce a consistent memo while still letting the user supply different notes, teams, and decisions.

Common SKILL.md Mistakes

Most broken skills fail quietly. They do not throw an error; they simply produce vague outputs or trigger at the wrong time. These are the problems worth checking first.

• Vague descriptions: If the description could apply to twenty workflows, rewrite it around one job.
• Too much background: Replace long context with the actual rule the agent should follow.
• Mixed responsibilities: Split a skill that writes sales emails, reviews contracts, and plans launches.
• No negative conditions: Say when not to use the skill if the boundary is easy to confuse.
• Missing output shape: Agents perform better when the expected deliverable is explicit.
• Unversioned local copies: Skills improve over time, so keep the working copy somewhere durable.

SKILL.md Review Checklist

Before you share a skill or rely on it every day, run a short review. The goal is to make the skill easy to discover, cheap to load, and hard to misuse.

• The file has valid YAML frontmatter wrapped in triple dashes.
• The name is stable, readable, and close to the folder name.
• The description says what task the skill handles and when to use it.
• The body starts with practical guidance instead of generic background.
• The process has concrete steps, not broad advice.
• The output format is clear enough to test against real work.
• Long references, examples, and templates live outside SKILL.md when they would bloat the main file.
• The skill does not overlap heavily with another skill in the same library.

A good SKILL.md should be boring to read and reliable to run. Clever wording matters less than clear triggers, crisp steps, and a maintainable shape.

Related Resources

For the broader concept, read what Claude Skills are. If you want to turn a rough instruction into a usable first draft, try the free Claude Skill Creator. You can also browse the resources hub for more AI workflow guides, or use the raw-to-pro prompt workflow before converting a prompt into a skill.

People Also Ask About SKILL.md