Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/trailofbits/skills/llms.txt

Use this file to discover all available pages before exploring further.

​
What are Skills?

Skills are structured guidance files that teach Claude how to perform specific tasks. Unlike traditional documentation, skills provide behavioral guidance - they explain the WHY and WHEN, not just the WHAT.
Skills should provide guidance Claude doesn’t already have, not duplicate reference material. Focus on judgment calls, decision criteria, and anti-patterns.

​
Skill Structure

skills/
  <skill-name>/
    SKILL.md          # Entry point with frontmatter
    references/       # Optional: detailed reference docs
    workflows/        # Optional: step-by-step guides
    scripts/          # Optional: utility scripts
    templates/        # Optional: output templates

​
Example Structures

skills/ask-questions-if-underspecified/
  SKILL.md          # All guidance in one file

skills/constant-time-analysis/
  SKILL.md
  references/
    compiled.md     # C/C++/Rust guidance
    javascript.md   # JavaScript-specific
    python.md       # Python-specific
    ruby.md         # Ruby-specific

skills/interpreting-culture-index/
  SKILL.md
  references/
    primary-traits.md
    secondary-traits.md
    motivators.md
    anti-patterns.md
  workflows/
    analyze-team.md
    detect-burnout.md
    interview-debrief.md
  scripts/
    extract_pdf.py
    pyproject.toml
  templates/
    individual-report.md
    team-report.md

​
Frontmatter Format

Every SKILL.md must begin with YAML frontmatter:
SKILL.md
---
name: skill-name
description: "Third-person description of what it does and when to use it"
allowed-tools:  # Optional: restrict to needed tools only
  - Read
  - Grep
  - Bash
---

​
Frontmatter Fields

​
name
string
required
Skill name in kebab-case. Maximum 64 characters. Must be unique within the plugin.
​
description
string
required
Third-person description that triggers correctly. Include specific use cases and keywords.Good: “Detects timing side-channels in cryptographic code. Use when auditing constant-time implementations.”Bad: “Helps with security analysis”
​
allowed-tools
array
Optional list of tool names to restrict Claude’s access. Only list tools the skill actually needs.Common tools: Read, Grep, Glob, Bash, Write, Edit

​
Writing Effective Descriptions

Your skill competes with 100+ others. The description determines when Claude invokes it.

Third-person voice

✅ “Analyzes timing side-channels”❌ “I help analyze timing”

Include triggers

✅ “Use when auditing Solidity contracts”❌ “Smart contract analysis tool”

Be specific

✅ “Detects reentrancy vulnerabilities”❌ “Helps with security”

State the domain

✅ “for cryptographic code”❌ “for code”

​
Required Sections

Every SKILL.md must include these sections:

​
When to Use

Specific scenarios where this skill applies: 
## When to Use

Use this skill when a request has multiple plausible interpretations or key 
details (objective, scope, constraints, environment, or safety) are unclear.

​
When NOT to Use

Scenarios where another approach is better: 
## When NOT to Use

Do not use this skill when the request is already clear, or when a quick, 
low-risk discovery read can answer the missing details.

​
Additional Requirements for Security Skills

Security and audit skills must also include: 
## Rationalizations to Reject

Common shortcuts or rationalizations that lead to missed findings:
- "This code looks safe because it uses a well-known library"
- "The test suite passes, so there are no issues"
- "The code review was approved, nothing to worry about"

​
Content Organization

1

Keep SKILL.md under 500 lines

If content exceeds 500 lines, split into references/ and workflows/ directories.
2

Use progressive disclosure

Put essential quick-start guidance in SKILL.md. Link to detailed references for advanced users.
3

One level deep

SKILL.md can link to files, but those files shouldn’t chain to more files.✅ Nested folders: references/guides/topic.md❌ Reference chains: SKILL.md → file1.md → file2.md

​
Progressive Disclosure Pattern

SKILL.md
## Quick Start

[Core instructions here - the 80% case]

## Advanced Patterns

For complex scenarios involving X, see [ADVANCED.md](references/ADVANCED.md)

## Language-Specific Guidance

- [Python](references/python.md)
- [JavaScript](references/javascript.md)
- [Rust](references/rust.md)

## API Reference

Complete method documentation: [API.md](references/API.md)

​
Using Python Scripts

Skills can include Python scripts with dependencies using PEP 723 inline metadata:
scripts/process.py
# /// script
# requires-python = ">=3.11"
# dependencies = ["requests>=2.28", "pydantic>=2.0"]
# ///

import requests
from pydantic import BaseModel

# Your script here
Invoke with uv run for automatic dependency resolution:
SKILL.md
To extract data from the PDF:

```bash
uv run {baseDir}/scripts/extract_pdf.py input.pdf output.json


<Tip>
Include `pyproject.toml` in the `scripts/` directory for development tooling (ruff, mypy, etc.)
</Tip>

## Value-Add Guidelines

Skills should provide guidance Claude doesn't already have:

<CardGroup cols={2}>
  <Card title="Behavioral Guidance" icon="compass">
    Don't paste entire specs. Teach when and how to look things up.
  </Card>

  <Card title="Explain WHY" icon="lightbulb">
    Include trade-offs, decision criteria, and judgment calls.
  </Card>

  <Card title="Document Anti-patterns" icon="triangle-exclamation">
    Say why something is wrong, not just that it's wrong.
  </Card>

  <Card title="Provide Context" icon="book-open">
    Connect concepts to real-world security implications.
  </Card>
</CardGroup>

### Example: DWARF Expert Skill

The DWARF skill doesn't include the full DWARF specification. Instead, it:

- Teaches Claude how to use `dwarfdump`, `readelf`, and `pyelftools`
- Explains judgment about when each tool is appropriate
- Shows how to look up what's needed from the spec
- Provides decision criteria for analysis approaches

## Scope Boundaries

Prescriptiveness should match task risk:

<Tabs>
  <Tab title="Strict (High Risk)">
    **Use for fragile tasks:**
    - Security audits
    - Cryptographic implementations
    - Compliance checks
    - Data migration
    
    Provide rigid step-by-step enforcement with quality gates.
  </Tab>

  <Tab title="Flexible (Low Risk)">
    **Use for variable tasks:**
    - Code exploration
    - Documentation
    - Refactoring
    - Feature development
    
    Offer options and judgment calls. Trust Claude's reasoning.
  </Tab>
</Tabs>

## Real Examples

<AccordionGroup>
  <Accordion title="ask-questions-if-underspecified (Basic)">
    Clarifies requirements before implementing when requests have multiple interpretations.

    **When to Use:** When key details (objective, scope, constraints) are unclear.

    **Workflow:**
    1. Decide if the request is underspecified
    2. Ask must-have questions first
    3. Restate requirements before starting work
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="constant-time-analysis (Intermediate)">
    Main SKILL.md provides core workflow and links to language-specific guidance for C/C++/Rust, Python, JavaScript, and Ruby. Each reference file contains deep technical details for that language.
  </Accordion>

  <Accordion title="interpreting-culture-index (Advanced)">
    Interprets Culture Index surveys and behavioral profiles with comprehensive support for individual profiles, team composition, burnout detection, and hiring.

    **Includes:**
    - 9 reference files for trait details
    - 11 workflow files for specific use cases
    - Python package for PDF extraction
    - 6 template files for report generation
  </Accordion>
</AccordionGroup>

## Quality Checklist

Before submitting a skill:

<AccordionGroup>
  <Accordion title="Technical (CI validates)">
    - [ ] Valid YAML frontmatter with `name` and `description`
    - [ ] Name is kebab-case, ≤64 characters
    - [ ] All referenced files exist
    - [ ] No hardcoded paths (`/Users/...`, `/home/...`)
    - [ ] Uses `{baseDir}` for all plugin paths
  </Accordion>

  <Accordion title="Quality (reviewers check)">
    - [ ] Description triggers correctly (third-person, specific)
    - [ ] "When to use" and "When NOT to use" sections present
    - [ ] Examples are concrete (input → output)
    - [ ] Explains WHY, not just WHAT
    - [ ] No duplication of reference material
  </Accordion>

  <Accordion title="Content">
    - [ ] SKILL.md under 500 lines (split if larger)
    - [ ] Progressive disclosure pattern used
    - [ ] Clear workflow steps
    - [ ] Anti-patterns documented with explanations
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Learn by Example" icon="graduation-cap">
    Study the reference skills:
    - Basic: `ask-questions-if-underspecified`
    - Intermediate: `constant-time-analysis`
    - Advanced: `culture-index`
  </Card>

  <Card title="Test Descriptions" icon="flask">
    Verify your description triggers correctly. Ask: "Would Claude invoke this for the right tasks?"
  </Card>

  <Card title="Minimize Dependencies" icon="minimize">
    Only include `allowed-tools` that are actually needed. Fewer restrictions = more flexibility.
  </Card>

  <Card title="Iterate Based on Use" icon="arrows-rotate">
    Skills improve with real-world usage. Update based on what works and what doesn't.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Commands" icon="terminal" href="/concepts/commands">
    Create slash commands that invoke skills
  </Card>

  <Card title="Agents" icon="robot" href="/concepts/agents">
    Build autonomous agents that use skills
  </Card>

  <Card title="Create Your First Skill" icon="code" href="/contributing/getting-started">
    Learn how to author skills
  </Card>
  
  <Card title="Skill Examples" icon="book" href="/contributing/examples">
    Browse real-world skill implementations
  </Card>
</CardGroup>