Skill

Skill Quickstart

Build a small Skill folder, write SKILL.md, and test whether an agent can activate it.

1. Create the folder

Use the cross-client convention .agents/skills/ when you want a project Skill that multiple tools can discover.

.agents/
└── skills/
    └── release-notes/
        └── SKILL.md

2. Write SKILL.md

Start with a narrow description and a short workflow. Add more only after real tests show the agent needs it.

---
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 summary of shipped changes.
Do not use it for internal sprint planning or engineering-only incident reports.

## Workflow
1. Identify user-visible changes.
2. Group changes by feature, fix, docs, and internal.
3. Write concise customer-facing bullets.
4. Exclude purely internal changes unless the user asks for them.
5. List unclear items as open questions.

## Output format
### Highlights
- ...

### Fixes
- ...

### Docs
- ...

### Open questions
- ...

3. Add a reference file

References keep the main Skill short. This example adds a tone guide that only loads when the user asks for customer-facing copy.

.agents/
└── skills/
    └── release-notes/
        ├── SKILL.md
        └── references/
            └── customer-tone.md

# references/customer-tone.md

Write in clear product language.
Avoid internal project names, ticket ids, and implementation details.
Use active voice.
Prefer "You can now..." when describing user-facing improvements.
Keep each bullet under 25 words.

4. Test activation

Ask a request that should clearly match the description, then confirm that the agent loaded the Skill and followed the workflow.

Test prompt Draft customer-facing release notes from these changes: "Add SSO login", "Fix invoice export timezone bug", "Refactor billing worker", "Update help docs for API keys". Flag anything unclear.

5. Expected output

A good result follows the Skill's grouping rules and avoids exposing internal-only changes as product updates.

### Highlights
- You can now sign in with SSO.

### Fixes
- Invoice exports now use the correct timezone.

### Docs
- API key setup docs have been updated.

### Open questions
- Should the billing worker refactor be excluded as internal-only?

6. Improve from behavior

If the Skill does not activate, rewrite the description with more realistic task language.
If the output is vague, add a concrete template.
If the agent guesses too much, add defaults and open-question rules.
If the file grows large, split references into separate files and load them conditionally.