skill-authoring

name	skill-authoring
description	Guides authoring of skills that Claude can discover and apply, covering description optimization, structure patterns by skill type, progressive disclosure, testing, and frontmatter rules. Use when creating, editing, or reviewing a SKILL.md, deciding how to structure a skill, or fixing a skill that isn't being discovered or followed.
version	1.1.0

Skill Authoring Guide

Overview

How to write skills that Claude can discover, understand, and apply effectively. A skill earns its place only if its description gets it loaded at the right moment and its body changes behavior once loaded. Everything here serves those two goals: discovery and application.

Why this matters: A skill Claude never loads is wasted; a skill Claude loads but ignores under pressure is worse: it creates false confidence. Context is a shared resource, so every token must justify itself. This guide eats its own dog food: its description is third-person and trigger-first, its body follows the structure conventions it teaches.

When to Use

• Creating a new skill from scratch
• Editing or restructuring an existing SKILL.md
• Reviewing a skill before publishing
• A skill isn't being discovered (description problem) or isn't being followed (body problem)
• Deciding whether content belongs inline or in a referenced file

When NOT to use: Writing application code, prose documentation, or commit messages. Those have their own conventions.

Related: This skill applies to authoring all other skills in this collection. It pairs with documentation-standards for writing style, design-principles for structure decisions, and testing-strategy for evaluation approaches. Discipline skills authored here should follow the Iron Law / red-flags shape used by debugging-methodology and verification-before-completion.

Core Principles

1. Context is a Shared Resource

• MUST: Challenge every token: "Does Claude need this?"
• MUST: Keep SKILL.md body under 500 lines
• NEVER: Explain what Claude already knows (PDFs, libraries, common patterns)
• SHOULD: Move heavy reference (100+ lines) to separate files

2. Description Enables Discovery

• MUST: Write in third person (injected into system prompt)
• MUST: Include both WHAT it does and WHEN to use it
• MUST: Include specific triggers/symptoms/contexts
• NEVER: Summarize the workflow in description (Claude may follow description instead of reading skill)
• SHOULD: Start with a third-person action verb ("Debugs…", "Traces…", "Guides…")
• SHOULD: One sentence on WHAT it does, then concrete "Use when …" triggers

# WRONG: Summarizes workflow - Claude may skip reading the skill
description: Code review with two passes - first for spec compliance, then for quality

# WRONG: Too vague
description: Helps with testing

# WRONG: First person / no triggers
description: I extract text from PDFs

# CORRECT: Verb-first WHAT, then specific triggers
description: Extracts text and tables from PDF files and fills forms. Use when working with PDFs, forms, or document extraction.

# CORRECT: Discipline skill - verb-first, trigger-rich
description: Debugs failures by gathering evidence before proposing fixes. Use when a test fails, a build breaks, or behavior is unexpected - before changing code.

3. Match Freedom to Fragility

Freedom Level	When to Use	Example
High (heuristics)	Multiple valid approaches	Code review guidelines
Medium (templates)	Preferred pattern exists	Report generation
Low (exact scripts)	Fragile, error-prone	Database migrations

---

Skill Types & Formats

Reference Skills (CLI tools, APIs)

Best format: Command reference + Best practices

## Quick Start
[5-line example showing core workflow]

## Command Reference
[Organized by category with examples]

## Best Practices
[MUST/SHOULD/NEVER rules]

## Examples
[Real workflows]

Example: agent-browser, git commands

Technique Skills (how-to)

Best format: Pattern + Examples + Common mistakes

## Overview
[Core principle in 1-2 sentences + WHY it matters]

## When to Use
[Symptoms and triggers]
**When NOT to use:** [counter-cases]
**Related:** [relative links to sibling skills]

## Core Pattern
[Before/after comparison]

## Implementation
[Steps or code]

## Common Mistakes
[What goes wrong + fixes]

## Verification
[Checklist proving the technique was applied]

Example: code-flow-analysis, result-types

Discipline Skills (rules/requirements)

Best format: Iron Law + Phases + Rationalization prevention

## The Iron Law
[One rule that cannot be violated]

## Phases/Process
[Clear steps with gates]

## Red Flags - STOP
[Signs you're about to violate]

## Common Rationalizations
[Table: Excuse | Reality]

## Verification
[Checklist proving the discipline was followed]

Example: debugging-methodology, verification-before-completion, tdd-workflow

Pattern Skills (mental models)

Best format: Concept + Recognition + Application

## Overview
[What is this pattern?]

## When to Recognize
[Symptoms indicating pattern applies]

## How to Apply
[Steps or guidelines]

## When NOT to Apply
[Counter-examples]

---

The MUST/SHOULD/NEVER Format

When to Use

• Reference documentation (commands, APIs)
• Best practices and guidelines
• Checklists and quality gates
• Any skill where quick scanning matters

Structure

## Section Name

- MUST: Non-negotiable requirements
- SHOULD: Strong recommendations with valid exceptions
- NEVER: Absolute prohibitions
- MAY: Optional enhancements

Writing Effective Rules

# WRONG: Vague
- MUST: Handle errors properly

# WRONG: Too long
- MUST: When an error occurs, you should catch it and then log it with the full stack trace and context

# CORRECT: Specific and scannable
- MUST: Catch errors at boundaries; log with stack trace
- NEVER: Swallow errors silently

Combine with Context

## Forms

- MUST: Use `fill` (clears first) for inputs, not `type`
- MUST: `autocomplete` + meaningful `name`; correct `type` and `inputmode`
- SHOULD: Placeholders end with `…` and show example pattern
- NEVER: Block paste in `<input>`/`<textarea>`

---

Discipline Skills: Rationalization Prevention

For skills that enforce rules (TDD, verification, debugging), Claude will rationalize under pressure.

The Iron Law Pattern

State one unbreakable rule:

## The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed Phase 1, you cannot propose fixes.

Red Flags List

Make it easy to self-check:

## Red Flags - STOP

If you catch yourself thinking:
- "Quick fix for now, investigate later"
- "Just try changing X and see"
- "I don't fully understand but this might work"

ALL of these mean: STOP. Return to Phase 1.

Rationalization Table

Capture excuses with counters:

| Excuse | Reality |
|--------|---------|
| "Too simple to need process" | Simple issues have root causes too |
| "Emergency, no time" | Systematic is faster than thrashing |
| "I'm confident" | Confidence ≠ evidence |
| "Just this once" | No exceptions |

Close Loopholes Explicitly

# WRONG: Just states rule
Write code before test? Delete it.

# CORRECT: Closes loopholes
Write code before test? Delete it. Start over.

**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Delete means delete

---

Progressive Disclosure

SKILL.md as Table of Contents

# PDF Processing

## Quick start
[Inline example]

## Core operations
[Inline patterns]

## Advanced features
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)

Claude loads referenced files only when needed.

When to Split Files

Content Type	Where
Patterns, concepts, quick ref	Inline in SKILL.md
Heavy reference (100+ lines)	Separate file
Reusable scripts	Separate file
Domain-specific schemas	Separate files by domain

Keep References One Level Deep

# WRONG: Nested references
SKILL.md → advanced.md → details.md → actual info

# CORRECT: Flat references
SKILL.md → advanced.md (complete info)
SKILL.md → reference.md (complete info)

---

Testing Skills

Test Before Deploying

• MUST: Test skill with real scenarios before deploying
• MUST: Test with the model(s) you'll use (Haiku needs more guidance than Opus)
• SHOULD: Create 3+ evaluation scenarios
• NEVER: Deploy untested skills

For Discipline Skills: Pressure Testing

1. Run scenario WITHOUT skill, document baseline behavior
2. Note rationalizations Claude uses
3. Write skill addressing those specific violations
4. Run scenario WITH skill, verify compliance
5. Find new rationalizations → add counters → re-test

Evaluation Structure

{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF file",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Uses appropriate PDF library",
    "Extracts from all pages",
    "Saves to output file"
  ]
}

---

YAML Frontmatter

Required Fields

---
name: skill-name-with-hyphens
description: "Third-person description with triggers. Use when [specific conditions]."
version: 1.0.0
---

Constraints

Field	Constraint
name	Max 64 chars, lowercase, letters/numbers/hyphens only
description	Max 1024 chars, non-empty, no XML tags
Reserved words	Cannot use "anthropic", "claude" in name

Optional Fields

---

Common Patterns

Template Pattern

## Report Structure

Use this template:

# [Title]

## Summary
[One paragraph]

## Findings
- Finding 1
- Finding 2

## Recommendations
1. Action 1
2. Action 2

Examples Pattern

## Commit Messages

**Example 1:**
Input: Added user authentication
Output: `feat(auth): implement JWT authentication`

**Example 2:**
Input: Fixed date display bug
Output: `fix(reports): correct timezone in date formatting`

Conditional Workflow

## Workflow

1. Determine type:
   **Creating new?** → Follow Creation workflow
   **Editing existing?** → Follow Editing workflow

2. Creation workflow:
   - Step A
   - Step B

3. Editing workflow:
   - Step X
   - Step Y

---

Anti-Patterns

Content Anti-Patterns

Anti-Pattern	Problem	Fix
Explaining basics	Wastes tokens	Assume Claude knows
Time-sensitive info	Becomes stale	Use "old patterns" section
Inconsistent terminology	Confuses	Pick one term, use throughout
Multiple languages	Dilutes quality	One excellent example
Narrative stories	Not reusable	Extract pattern

Structure Anti-Patterns

Anti-Pattern	Problem	Fix
Nested references	Partial reads	Keep one level deep
Vague descriptions	Poor discovery	Specific triggers
Workflow in description	Claude skips skill	Triggers only
No table of contents	Hard to navigate	Add for 100+ lines
Windows paths	Cross-platform issues	Use forward slashes

---

Checklist

Before Publishing

Frontmatter:

• Name: lowercase, hyphens, no reserved words
• Description: third-person, triggers, no workflow summary
• Version: semantic versioning

Content:

• Under 500 lines (or progressive disclosure)
• Consistent terminology
• No time-sensitive information
• Keywords for search (errors, symptoms, tools)

Structure conventions:

• ## Overview folds in the core principle and states WHY
• ## When to Use includes a **When NOT to use:** line
• **Related:** cross-refs siblings via one-level-deep relative links
• ## Verification checklist present

Format matches type:

• Reference: commands + best practices
• Technique: pattern + examples + mistakes
• Discipline: Iron Law + red flags + rationalization table

Testing:

• 3+ evaluation scenarios
• Tested with target model(s)
• Discipline skills: pressure tested

---

Verification

Before publishing a skill, confirm:

• Description is third-person, verb-first, under 1024 chars, with concrete triggers and no workflow summary
• Body opens with ## Overview (what + why) and ## When to Use (+ when NOT)
• **Related:** links resolve and are one level deep
• Format matches the skill type (reference / technique / discipline / pattern)
• Under 500 lines or split via progressive disclosure
• No time-sensitive info; terminology is consistent throughout
• Tested with target model(s); discipline skills pressure-tested

Integration

Skill	Relationship
testing-strategy	Evaluation and pressure-testing approaches
documentation-standards	Writing style and formatting
design-principles	Structure and abstraction decisions
All skills in this collection	This guide governs how each is authored