How to Create an Agent Skill (SKILL.md): A Practical Walkthrough
7 min read · Updated 2026-06-06
To create an Agent Skill, make a folder named after the skill and add a SKILL.md file. Start with YAML frontmatter containing a lowercase, hyphen-separated name and a description of what the skill does and when to use it. Then write clear Markdown instructions: an overview, when to use it, step-by-step instructions, inputs, expected output, and notes.
Step 1: Define the workflow
Start with a process you already repeat. The clearer the workflow, the better the skill. Write down the goal, the inputs you need, the steps you take, and what a finished result looks like. This becomes the raw material for your SKILL.md.
Step 2: Write the frontmatter
The frontmatter sits at the top of SKILL.md between two lines of three dashes. It needs a name and a description. The name should be lowercase with hyphens (for example, weekly-report-builder). The description should state, in one paragraph, what the skill does and when an agent should use it — this is how the agent decides whether the skill is relevant.
Step 3: Write the instructions
Below the frontmatter, write the Markdown body. Useful sections include an Overview, "When to use this skill," ordered Instructions, Workflow steps, Inputs, Output, Success criteria, and Notes. Keep instructions specific and actionable, and avoid referencing tools or data the agent will not actually have.
- Overview — what the skill accomplishes.
- When to use this skill — the triggers that make it relevant.
- Instructions and workflow steps — the ordered process.
- Inputs and output — what goes in and what comes out.
- Success criteria — how to know the task is done well.
Step 4: Generate it automatically (optional)
If you would rather not write the file by hand, the PromptVibe Skill Generator turns a plain-language workflow description into a complete, well-structured SKILL.md you can download and refine. Either way, review the final skill and test it before relying on it.
Frequently Asked Questions
What goes in the SKILL.md frontmatter?
At minimum a name (lowercase, hyphen-separated) and a description that explains what the skill does and when to use it. The description helps the agent decide when the skill applies.
Where do I put the skill so an agent can use it?
Place the folder containing SKILL.md in the skills directory of your Agent Skills–compatible tool. Check that tool's documentation for the exact location.
Can a skill include scripts or templates?
Yes. A skill can bundle supporting files — scripts, reference docs, or templates — alongside SKILL.md, which the agent loads when the skill is active.
Put this into practice
Generate a structured prompt or turn your workflow into a reusable Agent Skill — both free.