Skill authoring· Learn
How to Create Your First Skill
A step-by-step guide to designing a focused agent skill, writing SKILL.md, and testing whether it triggers correctly.
beginner8 min readUpdated May 4, 2026
Short answer
Create a good skill by choosing one narrow repeatable job, writing a clear SKILL.md description, adding only the scripts or references the workflow needs, and testing the trigger with realistic prompts.
Start with one job
The fastest way to create a weak skill is to start with a broad category. Start with a job instead: review billing PRs, QA checkout, update release notes, or investigate flaky tests.
- Good: Use this skill when a branch needs browser QA before release.
- Good: Use this skill when changelog and README updates must match a code diff.
- Weak: Use this skill to make coding better.
- Weak: Use this skill whenever the user asks for help.
Write the minimal SKILL.md
The description is the trigger surface. It should say when the skill applies, what outcome it produces, and where its boundaries are.
---
name: release-notes-helper
description: Use when a merged branch or release needs concise release notes, user impact, risk notes, and follow-up checks. Do not use for deep code review.
---
Follow these steps:
1. Inspect the commit range or PR list.
2. Group changes by user-visible impact.
3. Identify operational risks and rollout notes.
4. Draft release notes in plain language.
5. List any claims that still need human verification.Add resources only when they pay for themselves
| Resource | Use it when | Keep out when |
|---|---|---|
| scripts/ | A check must run the same way every time. | The workflow is judgment-heavy. |
| references/ | The skill needs long examples or policies. | A short checklist is enough. |
| assets/ | The workflow uses templates or starter files. | The asset is decorative. |
| agents/openai.yaml | You need UI metadata or dependency declarations. | Local authoring is enough. |
Test the trigger
- Write three prompts that should invoke the skill.
- Write three prompts that should not invoke the skill.
- Tighten the description until the boundary is obvious.
- Run the workflow on a disposable repo or branch before using it on production work.
A useful skill is boring in the best way
It should trigger predictably, produce the same kind of output each time, and make its assumptions visible.