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

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