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

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:

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

Structure Guidelines

1. Start with context — What is the agent doing and why
2. State the core principle — Most important rule upfront
3. Provide process — Step-by-step guidance
4. Include examples — Concrete illustrations
5. Add a checklist — Verification criteria
6. End with integration — How this connects to other skills

Directive Language

Strength	Examples
Strong (critical rules)	"You MUST…", "ALWAYS…", "NEVER…", "Do NOT…"
Soft (recommendations)	"Prefer…", "Consider…", "When possible…"

Content Patterns

Decision Trees

## Decision: [What to Decide]

If [condition A]:
→ [Action for A]

If [condition B]:
→ [Action for B]

If uncertain:
→ [Default action]

Process Steps

### Step 1: [Action]

[Detailed explanation]

**Verification:** [How to know step is complete]

### Step 2: [Action]
...

Code Examples

// BAD
const result = doTheThing(badInput);

// GOOD
const validated = validate(input);
const result = doTheThing(validated);

Anti-Patterns to Avoid

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

Skill Testing

Before publishing, verify:

1. Trigger test — Does it activate on expected phrases?
2. Completeness test — Can the agent follow it without external info?
3. Clarity test — Is every instruction unambiguous?
4. Contradiction test — No conflicting guidance?
5. Edge case test — Handles unusual situations?

Pack Organization

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

Skill Maintenance

See MAINTENANCE.md for detailed versioning policy. Quick reference:

Version increments:

• Patch (1.0.x): Typos, clarifications, minor fixes
• Minor (1.x.0): New sections, examples, capabilities
• Major (x.0.0): Breaking changes, fundamental rewrites

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.

Publication Checklist

Before publishing, confirm:

• Frontmatter is complete and valid (name, description, version)
• Description includes concrete actions and a "Use when…" clause
• Triggers are natural-language phrases, specific but not over-fitted
• Core principle is clear and prominent
• Content uses headers, lists, or tables — no walls of text
• Code examples demonstrate correct vs. incorrect usage
• Verification criteria are included
• Related skills are linked where applicable
• No spelling/grammar errors
• Tested with target agents against all trigger phrases