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

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

markdown
## Decision: [What to Decide]

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

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

If uncertain:
→ [Default action]

Process Steps

markdown
### Step 1: [Action]

[Detailed explanation]

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

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

Code Examples

typescript
// 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:

yaml
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