You are authoring a SKILL.md for an AI coding agent. A well-written skill provides clear, actionable guidance that agents can follow consistently.
A skill's description triggers it; the body teaches it.
The description tells the agent WHEN to use the skill. The content tells the agent HOW to execute it.
---
name: [lowercase-hyphenated-name]
description: [Concrete actions + "Use when..." clause]
version: [Semantic version]
triggers:
- [keyword 1]
- [keyword 2]
tags:
- [tag 1]
---
# [Skill Title]
[Introduction paragraph explaining purpose]
## Core Principle
**[Single most important rule in bold]**
## [Main Content Sections]
## [Decision Points]
## [Verification Checklist]
| Field | Required | Constraints |
|---|---|---|
| name | Yes | Lowercase alphanumeric + hyphens, 1–64 chars |
| description | Yes | Must include "Use when..." clause; 1–1024 chars |
| version |
| Yes |
Semantic version (e.g. 1.0.0) |
| triggers | Recommended | Natural-language phrases that activate the skill |
| tags | Recommended | Categorization tags |
Triggers should be phrases users naturally type.
Good triggers:
Bad triggers:
Use second person, present tense, active voice:
| Strength | Examples |
|---|---|
| Strong (critical rules) | "You MUST…", "ALWAYS…", "NEVER…", "Do NOT…" |
| Soft (recommendations) | "Prefer…", "Consider…", "When possible…" |
## Decision: [What to Decide]
If [condition A]:
→ [Action for A]
If [condition B]:
→ [Action for B]
If uncertain:
→ [Default action]
### Step 1: [Action]
[Detailed explanation]
**Verification:** [How to know step is complete]
### Step 2: [Action]
...
// BAD
const result = doTheThing(badInput);
// GOOD
const validated = validate(input);
const result = doTheThing(validated);
| Anti-pattern | Problem | Fix |
|---|---|---|
| The Encyclopedia | Too much info, agent gets lost | Focus on actionable guidance only |
| The Vague Guide | "Consider best practices" | Be specific: "Use Arrange-Act-Assert" |
| The Constraint-Free Skill | No clear rules, agent improvises | Include explicit constraints |
| The Monologue | Wall of text | Use headers, lists, tables, code blocks |
| The Outdated Skill | References deprecated patterns | Version skills and review periodically |
Before publishing, verify:
Group related skills under a named pack directory. See PACKS.md for full pack manifest format and filesystem conventions.
packs/
├── testing/
│ ├── pack.json
│ ├── red-green-refactor/
│ │ └── SKILL.md
│ └── test-patterns/
│ └── SKILL.md
See MAINTENANCE.md for detailed versioning policy. Quick reference:
Version increments:
Deprecation frontmatter:
deprecated: true
deprecatedReason: "Superseded by skill-v2"
deprecatedSince: "2024-01-15"
Add a visible notice at the top of the body: > **DEPRECATED:** Use [skill-v2] instead.
Before publishing, confirm:
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).