Skill Authoring

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](../documentation-standards/SKILL.md) for writing style, [design-principles](../design-principles/SKILL.md) for structure decisions, and [testing-strategy](../testing-strategy/SKILL.md) for evaluation approaches. Discipline skills authored here should follow the Iron Law / red-flags shape used by [debugging-methodology](../debugging-methodology/SKILL.md) and [verification-before-completion](../verification-before-completion/SKILL.md).

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

---

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](../testing-strategy/SKILL.md) | Evaluation and pressure-testing approaches | | [documentation-standards](../documentation-standards/SKILL.md) | Writing style and formatting | | [design-principles](../design-principles/SKILL.md) | Structure and abstraction decisions | | All skills in this collection | This guide governs how each is authored |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jagreehal
• Source: jagreehal/jagreehal-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.