Skill Authoring Guide

You are authoring a SKILL.md for an AI coding agent. A well-written skill provides clear, actionable guidance that agents can follow consistently.

Core Principle

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.

Skill Anatomy

SKILL.md Structure

---
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]

Frontmatter Fields

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

Writing Effective Triggers

Triggers should be phrases users naturally type.

Good triggers:

• "write tests first"
• "tdd"
• "test driven development"

Bad triggers:

• "testing methodology" (too vague)
• "red-green-refactor-cycle-for-test-driven-development" (too specific)
• "skill-123" (not natural language)

Trigger Guidelines

1. Natural language, How would a human ask for this?
2. Multiple variations, Different ways to say the same thing
3. Specific enough, Don't trigger on too many queries
4. Common terms, Use terms people actually use

Writing Skill Content

Voice and Tone

Use second person, present tense, active voice: