skill-authoring

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

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:

• ✅ "Write the test first"
• ✅ "You are implementing TDD"
• ❌ "The developer should..." (passive)
• ❌ "It is recommended that..." (wordy)