Skill

How to Create a Skill

Turn repeatable expertise into a compact package that agents can discover, activate, and execute reliably.

Start from real work

Do not begin with a generic prompt. Start with a task someone has already performed successfully, then extract the decisions, checks, files, and output format that made it work.

Hands-on taskRecord the steps from a real example and remove details that only apply to that one case.

Existing artifactsUse runbooks, SOPs, templates, review notes, scripts, and internal docs as source material.

Example source notes

Turn messy real notes into a reusable workflow. Do not publish the messy notes directly as the Skill.

Raw notes from a real task:
- User pasted PR list.
- Removed internal refactor items.
- Grouped SSO under Highlights.
- Timezone export bug went under Fixes.
- Asked whether billing worker refactor should be mentioned.
- Final format had Highlights, Fixes, Docs, Open questions.

Choose one job

A Skill should have a clear activation boundary. If it handles too many unrelated jobs, the agent will either trigger it too often or ignore it when it matters.

Good scope "Generate a migration risk review for a database schema change" is easier to use and evaluate than "help with databases."

Write operational instructions

Activation guidance

Say exactly when the Skill applies, including common user wording and situations where it should not activate.

Procedure

Describe the workflow as actions the agent can follow, not as abstract advice.

Defaults

Give default assumptions so the agent does not ask the user to choose every minor option.

Output template

Provide the exact report, checklist, table, or file format when the final shape matters.

Before and after

Weak instruction:
"Write good release notes."

Operational instruction:
"Group user-visible changes into Highlights, Fixes, and Docs.
Exclude internal-only refactors unless the user asks for engineering notes.
If a change is ambiguous, list it under Open questions instead of guessing."

Package supporting resources

Keep the core SKILL.md short enough to load comfortably. Put heavy reference material, long examples, templates, or reusable scripts in separate files.

release-notes/
├── SKILL.md
├── assets/
│   └── release-note-template.md
├── references/
│   └── product-taxonomy.md
└── scripts/
    └── collect-changelog.js

Minimal publishable SKILL.md

---
name: release-notes
description: Draft customer-facing release notes from merged PRs, commits, or changelog entries.
---

# Release Notes

Use this skill when the user asks for release notes, changelog copy, or a customer-facing shipped-changes summary.
Do not use it for incident reports, sprint plans, or internal engineering summaries.

## Workflow
1. Extract user-visible changes.
2. Group them into Highlights, Fixes, Docs, and Open questions.
3. Remove internal-only work unless the user asks for it.
4. Write concise bullets in customer-facing language.
5. Ask about ambiguous items instead of inventing product impact.

Write test prompts

A Skill is not done when the file exists. Test it with requests that should activate and requests that should stay unrelated.

should trigger:
- Turn these merged PRs into customer-facing release notes.
- Draft changelog copy for this week's shipped changes.
- Write release notes and flag unclear items.

should not trigger:
- Explain semantic versioning.
- Summarize this outage report.
- Create a sprint planning checklist.

Refine with execution

Run the Skill on realistic examples, inspect where the agent hesitates, then update the instructions. Strong Skills usually emerge from several small edits, not one long authoring session.

Add gotchas where the agent made wrong assumptions.
Move long background into references and load it conditionally.
Tighten the description if the Skill activates too broadly or too rarely.
Add examples only when they change the agent's behavior.