SKILL.md Examples
Four patterns that show up in well-written skills, with annotated walkthroughs of each. Steal these structures — they work.
1. A minimal skill that works
The simplest useful skill you can write.
Sometimes all you need is 15 lines. This teaches an agent your team's commit message format. No scripts, no reference files, just clear instructions.
Description names the trigger ("when committing code"). This is how the agent knows to activate it.
The instructions are short and specific. The agent already knows how to write commits — it just needs your format.
No explanation of what a commit message is. The agent knows. Only adds what’s unique to your team.
2. A skill with progressive disclosure
Main file stays lean. Details live in reference files loaded on demand.
This pattern keeps the initial context cost low. The agent reads the overview on activation, then dips into reference files only when it actually needs the details.
The main SKILL.md is a routing document. It gives the agent the workflow and tells it where to find details.
Reference files aren’t loaded until the agent actually needs them — zero context cost until accessed.
Numbered workflow steps. Agents follow sequential instructions far more reliably than freeform paragraphs.
3. A skill with input/output examples
Few-shot patterns work in skills too.
Showing the agent what you expect is often clearer than explaining it. This pattern is especially useful when the output format matters.
The example shows the transformation clearly: raw git log in, polished user-facing notes out.
Notice the output uses plain language ("Dark mode is now available"), not developer jargon ("feat: add dark mode toggle").
One example is often enough. Two is better if the format is complex. More than three is usually overkill.
4. A skill with a feedback loop
Validate, fix, repeat.
The most common quality improvement is adding a validation step. Without explicit instructions to loop, agents tend to validate once and move on regardless of the result.
disable-model-invocation: true — you don’t want the agent auto-triggering database migrations. Manual invoke only.
Steps 3-4 create an explicit loop. "Return to step 3" is the key instruction most skill authors forget.
$ARGUMENTS gets replaced with whatever follows the slash command: /schema-migration add-user-roles
What these all have in common
- •Specific descriptions with triggers. Every description says what the skill does and when to use it.
- •No unnecessary context. None of them explain concepts the agent already knows.
- •Numbered steps. Sequential instructions, not freeform paragraphs.
- •Under 30 lines. You can read each one in 15 seconds. That’s the point.
Find more examples
Browse real skills on mdskills.ai to see how the community structures them. The top-installed skills are a good starting point — they’ve been tested by thousands of developers.