SKILL.md Template

A SKILL.md template gives you the structure for an Agent Skill: a short file that teaches an AI agent how to do one specific job, and tells it when that job applies. Use this free SKILL.md template (it works as a Claude skill template too) to write the name, description, and instructions, then point to any scripts or reference files the agent needs.

Use this template in HelpDocsDownload for Word

AI prompt

Copy prompt

Open in

ClaudeChatGPTHelpDocs AI Copies a version with formatting tips

I need to write a SKILL.md. Act as an expert technical writer and draft one for me.

Use this structure, keeping each section clear, concise, and genuinely useful to the reader:

1. Frontmatter
2. Purpose
3. When to use it
4. Inputs and prerequisites
5. Instructions
6. Rules and constraints
7. Examples
8. Bundled files
9. Output
10. Ownership and changes

Before you begin, ask me for the details you need: the product, team, or audience this is for, and anything specific I should include. Then write the full SKILL.md in clean, well-formatted Markdown.

Connected HelpDocs over MCP? Add "save this as an unpublished HelpDocs article" to the prompt and the draft lands in your knowledge base, ready to review.

## The SKILL.md template

### 1. Frontmatter

This is the YAML section at the very top of your file. Agents read these fields first, so they decide whether your skill ever gets used.

| Field | Required | What to write |
| --- | --- | --- |
| name | Yes | A short, lowercase, hyphenated name for the skill (for example, `release-notes`) |
| description | Yes | What the skill does and when to use it, in one or two sentences |

Write this description for the agent rather than for a human reader. Spell out the task, the inputs it expects, and the phrases or situations that should trigger it.

### 2. Purpose

Use a sentence or two to say what job this skill handles and what a good outcome looks like. One skill, one job. If you catch yourself writing "and also," that's your cue to split the skill into separate pieces.

### 3. When to use it

Spell out when the agent should reach for this skill and when it shouldn't. Name the concrete signals: what the request looks like, which file types are involved, and which tools are at play.

### 4. Inputs and prerequisites

Spell out what the agent requires before beginning: files, access, tools, or details you need to request from the user. Then say what happens when something is missing.

### 5. Instructions

List what the agent does, one step after another. Make each step a straightforward instruction.

1. **Step name.** What the agent does, and where it does it.
2. **Step name.** Any choice the agent needs to make, plus the rule that guides it.
3. **Step name.** How to confirm the outcome before going to the next step.

### 6. Rules and constraints

The must-do and never-do rules for the agent while using this skill: which formats to follow, which files to leave alone, how far it can go, and when it should pause and ask.

### 7. Examples

Give one or two quick examples pairing a request with the result you want. An agent learns from examples far quicker than from descriptions.

### 8. Bundled files

Write down every script, reference document, template, and asset that lives in the skill folder, and note when the agent should use each one. If a reference runs long, keep it in its own file so the agent doesn't read it until the task calls for it.

| File | What it contains | When to use it |
| --- | --- | --- |
| TODO | TODO | TODO |

### 9. Output

Spell out what the final deliverable looks like. Cover its format, where it gets saved or handed back, and what the agent needs to tell you when it's done.

### 10. Ownership and changes

Name the owner of the skill and the date of its most recent review. Log any changes worth calling out, so you can figure out what made the agent behave differently.

| Version | Date | Owner | Change |
| --- | --- | --- | --- |
| 1.0 | TODO | TODO | Initial version |

The SKILL.md template

Give your skill its own folder, then put a SKILL.md file inside it. Follow the layout below, swapping the guidance in each section for details on the task your agent should handle.

TemplateCopy as MarkdownDownload for Word

1. Frontmatter

This is the YAML section at the very top of your file. Agents read these fields first, so they decide whether your skill ever gets used.

Field	Required	What to write
name	Yes	A short, lowercase, hyphenated name for the skill (for example, release-notes)
description	Yes	What the skill does and when to use it, in one or two sentences

Write this description for the agent rather than for a human reader. Spell out the task, the inputs it expects, and the phrases or situations that should trigger it.

2. Purpose

Use a sentence or two to say what job this skill handles and what a good outcome looks like. One skill, one job. If you catch yourself writing “and also,” that’s your cue to split the skill into separate pieces.

3. When to use it

Spell out when the agent should reach for this skill and when it shouldn’t. Name the concrete signals: what the request looks like, which file types are involved, and which tools are at play.

4. Inputs and prerequisites

Spell out what the agent requires before beginning: files, access, tools, or details you need to request from the user. Then say what happens when something is missing.

5. Instructions

List what the agent does, one step after another. Make each step a straightforward instruction.

1. Step name. What the agent does, and where it does it.
2. Step name. Any choice the agent needs to make, plus the rule that guides it.
3. Step name. How to confirm the outcome before going to the next step.

6. Rules and constraints

The must-do and never-do rules for the agent while using this skill: which formats to follow, which files to leave alone, how far it can go, and when it should pause and ask.

7. Examples

Give one or two quick examples pairing a request with the result you want. An agent learns from examples far quicker than from descriptions.

8. Bundled files

Write down every script, reference document, template, and asset that lives in the skill folder, and note when the agent should use each one. If a reference runs long, keep it in its own file so the agent doesn’t read it until the task calls for it.

File	What it contains	When to use it
TODO	TODO	TODO

9. Output

Spell out what the final deliverable looks like. Cover its format, where it gets saved or handed back, and what the agent needs to tell you when it’s done.

10. Ownership and changes

Name the owner of the skill and the date of its most recent review. Log any changes worth calling out, so you can figure out what made the agent behave differently.

Version	Date	Owner	Change
1.0	TODO	TODO	Initial version

Tip

Skills deliver their best results when the knowledge behind them stays current. Start a free HelpDocs trial and give the documentation your agents lean on one searchable home.

How to fill in this SKILL.md template

Your skill won’t do much good if the agent can’t find it and follow along. These habits help:

• Give the description the most attention. That’s what determines whether the skill loads at all. State the task and what sets it off, in plain terms.
• Scope each skill to a single job. Tight skills fire more reliably and stay simpler to keep up with.
• Give steps, not prose. Brief, direct directions outperform rambling explanations.
• Push the heavy content into bundled files. Leave SKILL.md brief and have it point to reference files for the details, so the agent only reads those when necessary.
• Run it against actual requests. Have an agent tackle the task several different ways and correct anything it gets wrong.
• Leave the source of truth somewhere else. Link to documentation that stays current instead of copying it in, so the skill doesn’t go stale.

Agent instructions for your repository start with our AGENTS.md template. To see how agents put documentation to work, check out how AI uses your knowledge base.