SKILL.md Template and Examples for Plugin Capabilities

A copy-paste SKILL.md template plus annotated examples for Skills inside Agent Plugins, including frontmatter, body structure, scripts, and reference files.

This page gives you a copy-paste SKILL.md template and real examples you can adapt for capabilities inside your Agent Plugin. A SKILL.md is the single required file of an agent Skill - the instructions an AI agent loads to do a job.

The minimal SKILL.md template

---
name: your-skill-name
description: >
  Use this skill when the user asks to "<phrase one>", "<phrase two>",
  or "<phrase three>". <One sentence on what it does.>
---
 
# <Skill title>
 
<One line on what this skill produces.>
 
## Steps
1. <First action.>
2. <Second action.>
3. <Produce the output; state what it must NOT do.>

Two rules carry most of the weight:

name — lowercase, hyphenated, unique.
description — third person, with the literal phrases a user would say. This is what makes the Skill trigger.

Full template with scripts and references

your-skill/
├── SKILL.md
├── scripts/
│   └── transform.py
└── references/
    └── detailed-rules.md

---
name: monthly-report
description: >
  Use this skill when the user asks to "build the monthly report",
  "summarize last month's numbers", or "prepare the month-end pack".
  Pulls the period's data, computes the standard metrics, and renders
  a report. Reads references/detailed-rules.md for edge cases.
---
 
# Monthly report
 
Produce a review-ready monthly report from the period's data.
 
## Steps
1. Confirm the period and locate the data source.
2. Run `scripts/transform.py` to normalize the inputs.
3. Compute the standard metrics. For unusual cases, load
   `references/detailed-rules.md`.
4. Render the report. Never overwrite source data.

Example: a documentation Skill

---
name: api-doc-writer
description: >
  Use this skill when the user asks to "document this endpoint",
  "write API docs", or "create a reference for this route".
  Produces consistent reference docs from code.
---
 
# API doc writer
 
## Steps
1. Read the route handler and its types.
2. Produce: summary, params, request/response, and one example.
3. Match the style of existing docs in the repo.

Example: a data-quality Skill

---
name: data-quality-check
description: >
  Use this skill when the user asks to "check data quality",
  "validate this dataset", or "find data issues". Runs a fixed
  set of checks and reports failures with row references.
---
 
# Data quality check
 
## Steps
1. Run `scripts/checks.py` over the dataset.
2. Report each failing check with counts and example rows.
3. Rank issues by severity. Propose fixes; do not modify data.

Tips that make templates work

Keep the body short; move long rules into references/.
Put deterministic logic in scripts/, not prose.
Say explicitly what the Skill must not do (e.g. "never modify source data").

Frequently asked questions

What goes in frontmatter vs. the body? Frontmatter is always-in-context metadata (name, description). The body loads only when the Skill triggers.

Can a SKILL.md be just frontmatter and a few steps? Yes — many effective Skills are a single short file.