Skill Authoring Guide

Overview

Skills provide Claude with domain-specific knowledge and workflows. This guide covers everything you need to know to create high-quality skills.

Frontmatter Requirements

Every SKILL.md file must start with YAML frontmatter:

---
name: skill-name              # kebab-case, max 64 chars
description: "Third-person description of what it does and when to use it"
allowed-tools:                # Optional: restrict to needed tools only
  - Read
  - Grep
---

Name Requirements

Format: kebab-case only
Length: Maximum 64 characters
Preferred form: Gerund (verb + -ing)
- Good: analyzing-contracts, processing-pdfs
- Avoid: contract-analyzer, pdf-processor
Avoid vague names: helper, utils, tools, misc
Avoid reserved words: anthropic, claude

Description Requirements

Your description must trigger correctly since skills compete with 100+ others:

The description is critical for skill discovery. Claude uses it to decide when to invoke your skill.

Best practices:

Third-person voice: “Analyzes X” not “I help with X”
Include triggers: “Use when auditing Solidity” not just “Smart contract tool”
Be specific: “Detects reentrancy vulnerabilities” not “Helps with security”

Examples:

---
name: constant-time-analysis
description: "Detects timing side-channel vulnerabilities in cryptographic code. Use when implementing or reviewing crypto code, encountering division on secrets, secret-dependent branches, or constant-time programming questions."
---

Allowed Tools (Optional)

Restrict the skill to only the tools it needs:

---
name: read-only-analyzer
description: "Analyzes code without making changes"
allowed-tools:
  - Read
  - Grep
  - Glob
---

Available tools include: Read, Write, Edit, Bash, Grep, Glob, Task, and others.

Required Sections

Every SKILL.md must include these sections:

When to Use

Specify concrete scenarios where the skill applies:

## When to Use

- User implements signature, encryption, or key derivation
- Code contains `/` or `%` operators on secret-derived values
- User mentions "constant-time", "timing attack", "side-channel"
- Reviewing functions named `sign`, `verify`, `encrypt`, `decrypt`

Make triggers concrete and specific. Think about what keywords or patterns should activate your skill.

When NOT to Use

Specify scenarios where another approach is better:

## When NOT to Use

- Non-cryptographic code (business logic, UI, etc.)
- Public data processing where timing leaks don't matter
- High-level API usage where timing is handled by the library

This helps Claude avoid false positive skill invocations.

Security Skills: Rationalizations to Reject

For audit/security skills, also include:

## Rationalizations to Reject

- "This code is internal-only" - Internal attackers exist
- "Performance matters more" - Security is non-negotiable for crypto
- "The compiler will optimize it" - Never rely on compiler optimizations for security

This section helps Claude maintain rigor and avoid common shortcuts that lead to missed findings.

Content Organization

Keep SKILL.md under 500 lines

If your skill grows beyond 500 lines, split it into supporting files:

references/ - Detailed documentation
workflows/ - Step-by-step guides
scripts/ - Utility scripts

Use progressive disclosure

Start with quick start, then link to details:

## Quick Start
[Core instructions here]

## Advanced Usage
See [ADVANCED.md](references/ADVANCED.md) for detailed patterns.

## API Reference
See [API.md](references/API.md) for complete method documentation.

Keep references one level deep

SKILL.md can link to files, but those files shouldn’t chain to more files:

✅ Good: SKILL.md → file1.md (one level)
❌ Bad: SKILL.md → file1.md → file2.md (chained references)

Directory depth is fine (references/guides/topic.md). The restriction is on reference chains, not nested folders.

Path Handling

Never hardcode absolute paths. Always use {baseDir} for portability.

Good:

uv run {baseDir}/scripts/process.py input.pdf

Bad:

uv run /Users/yourname/plugins/myplugin/scripts/process.py input.pdf

Rules:

Use {baseDir} for paths relative to the skill directory
Use forward slashes (/) even on Windows
Claude will automatically replace {baseDir} with the actual path at runtime

Python Scripts

When skills include Python scripts with dependencies:

Use PEP 723 inline metadata

Declare dependencies in the script header:

# /// script
# requires-python = ">=3.11"
# dependencies = ["requests>=2.28", "pydantic>=2.0"]
# ///

import requests
from pydantic import BaseModel

# Your script code here

Use uv run for execution

This enables automatic dependency resolution:

uv run {baseDir}/scripts/process.py input.pdf

No need for separate pip install or virtual environment setup!

Include pyproject.toml

Keep in scripts/ for development tooling (ruff, pytest, etc.):

[project]
name = "my-skill-scripts"
version = "1.0.0"
requires-python = ">=3.11"

[tool.ruff]
line-length = 100

Document system dependencies

List non-Python dependencies in workflows with platform-specific install commands for macOS (brew), Ubuntu (apt-get), and other platforms.

Writing Effective Workflows

Workflows should provide step-by-step guidance for complex tasks:

Scope Boundaries

Match prescriptiveness to task risk:

Strict for fragile tasks: Security audits, crypto implementations, compliance checks need rigid step-by-step enforcement
Flexible for variable tasks: Code exploration, documentation, refactoring can offer options and judgment calls

Workflow Format

## Workflow

### 1) Decide whether the request is underspecified

Treat a request as underspecified if after exploring how to perform the work:
- Define the objective (what should change vs stay the same)
- Define "done" (acceptance criteria, examples, edge cases)
- Define scope (which files/components/users are in/out)

### 2) Ask must-have questions first

Ask 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.

Make questions easy to answer:
- Optimize for scannability (short, numbered questions)
- Offer multiple-choice options when possible
- Suggest reasonable defaults

### 3) Pause before acting

Until must-have answers arrive:
- Do not run commands or edit files
- Do perform clearly labeled, low-risk discovery steps

Value-Add: Behavioral Guidance Over Reference Dumps

Skills should provide guidance Claude doesn’t already have:

Don’t paste entire specs. Teach when and how to look things up.

Behavioral guidance over reference dumps:

Don’t paste entire specs; teach when and how to look things up
Explain WHY, not just WHAT
Include trade-offs, decision criteria, judgment calls
Document anti-patterns WITH explanations

Example: The DWARF skill doesn’t include the full DWARF spec. Instead, it teaches Claude:

How to use dwarfdump, readelf, and pyelftools to look up what it needs
Judgment about when each tool is appropriate
What patterns indicate problems vs normal behavior

Examples and Concreteness

Make examples concrete with actual input → output:

## Example: Detecting Timing Leaks

Input code:
\`\`\`c
int compare_secret(const char *a, const char *b, size_t len) {
    for (size_t i = 0; i < len; i++) {
        if (a[i] != b[i]) return 0;  // Early exit leaks position
    }
    return 1;
}
\`\`\`

Analysis output:
\`\`\`
Line 3: TIMING LEAK - early return on first mismatch
  Impact: Leaks secret position through execution time
  Fix: Use constant-time comparison (e.g., memcmp_ct)
\`\`\`

Decision Criteria and Trade-offs

Help Claude make judgment calls:

## When to Use Strict Mode vs Permissive Mode

**Use strict mode when:**
- Auditing third-party code
- Reviewing cryptographic implementations
- Compliance-critical code

**Use permissive mode when:**
- Exploring unfamiliar codebases
- Quick sanity checks
- Internal utility code

**Trade-off:** Strict mode has higher false positive rate but catches more edge cases.

Testing Your Skill

Before submitting:

Test triggering: Does the description cause the skill to load at the right times?
Test workflows: Do the step-by-step instructions work as expected?
Test scripts: Do all scripts run successfully with uv run?
Test references: Do all referenced files exist and load correctly?
Test paths: Does {baseDir} resolve correctly across different systems?

Next Steps

Best Practices

Learn Trail of Bits quality standards

Plugin Structure

Understand required directory layout

Examples

See real-world skill examples

Getting Started

Start creating your first skill

Development

Reference

Overview

Frontmatter Requirements

Name Requirements

Description Requirements

Allowed Tools (Optional)

Required Sections

When to Use

When NOT to Use

Security Skills: Rationalizations to Reject

Content Organization

Path Handling

Python Scripts

Writing Effective Workflows

Scope Boundaries

Workflow Format

Value-Add: Behavioral Guidance Over Reference Dumps

Examples and Concreteness

Decision Criteria and Trade-offs

Testing Your Skill

Next Steps

Best Practices

Plugin Structure

Examples

Getting Started

Build docs developers (and LLMs) love

Development

Reference

​Overview

​Frontmatter Requirements

​Name Requirements

​Description Requirements

​Allowed Tools (Optional)

​Required Sections

​When to Use

​When NOT to Use

​Security Skills: Rationalizations to Reject

​Content Organization

​Path Handling

​Python Scripts

​Writing Effective Workflows

​Scope Boundaries

​Workflow Format

​Value-Add: Behavioral Guidance Over Reference Dumps

​Examples and Concreteness

​Decision Criteria and Trade-offs

​Testing Your Skill

​Next Steps

Best Practices

Plugin Structure

Examples

Getting Started

Build docs developers (and LLMs) love

Overview

Frontmatter Requirements

Name Requirements

Description Requirements

Allowed Tools (Optional)

Required Sections

When to Use

When NOT to Use

Security Skills: Rationalizations to Reject

Content Organization

Path Handling

Python Scripts

Writing Effective Workflows

Scope Boundaries

Workflow Format

Value-Add: Behavioral Guidance Over Reference Dumps

Examples and Concreteness

Decision Criteria and Trade-offs

Testing Your Skill

Next Steps