mcp-trailofbits

id	mcp-trailofbits
name	mcp-trailofbits
version	1.0.0
description	MCP bundle package
category	prompt
tags	["mcp","bundle"]

Contributing Skills

Resources

Official Anthropic documentation (always check these first):

• Claude Code Plugins
• Agent Skills
• Best Practices
• Skill Authoring Best Practices — progressive disclosure, degrees of freedom, workflow checklists
• The Complete Guide to Building Skills (text) — evaluation-driven development, iterative testing

Reference skills - learn by example at different complexity levels:

Complexity	Skill	What It Demonstrates
Basic	ask-questions-if-underspecified	Minimal frontmatter, simple guidance
Intermediate	constant-time-analysis	Python package, references/, language-specific docs
Advanced	culture-index	Scripts, workflows/, templates/, PDF extraction, multiple entry points

When in doubt, copy one of these and adapt it.

Deep dives on skill authoring:

• Claude Skills Deep Dive - Comprehensive analysis of skill architecture

Example plugins worth studying:

• superpowers - Advanced workflow patterns, TDD enforcement, multi-skill orchestration
• compound-engineering-plugin - Production plugin structure
• getsentry/skills — Production Sentry skills; security-review is a standout routing + progressive disclosure example

For Claude: Use the claude-code-guide subagent for plugin/skill questions - it has access to official documentation.

Technical Reference

Codex Compatibility

This repository now supports both Claude plugin discovery and Codex-native skill discovery.

Rules:

• If a plugin adds skills/<name>/SKILL.md, it must also remain reachable through .codex/skills/<name>.
• If a plugin is command/hook/agent-only and has no skills/ directory, add an explicit Codex wrapper skill under .codex/skills/<plugin-name>/SKILL.md or document why no Codex equivalent is intended.
• Before submitting, run:

python3 .github/scripts/validate_codex_skills.py

• If this check fails in CI, the remediation path should be local and mechanical: run the installer or update the .codex/skills/ mapping, then commit the resulting changes.

Plugin Structure

plugins/
  <plugin-name>/
    .claude-plugin/
      plugin.json         # Plugin metadata (name, version, description, author)
    commands/             # Optional: slash commands
    agents/               # Optional: autonomous agents
    skills/               # Optional: knowledge/guidance
      <skill-name>/
        SKILL.md          # Entry point with frontmatter
        references/       # Optional: detailed docs
        workflows/        # Optional: step-by-step guides
        scripts/          # Optional: utility scripts
    hooks/                # Optional: event hooks
    README.md             # Plugin documentation

Important: Component directories (skills/, commands/, agents/, hooks/) must be at the plugin root, NOT inside .claude-plugin/. Only plugin.json belongs in .claude-plugin/.

Frontmatter

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

Naming Conventions

• kebab-case: constant-time-analysis, not constantTimeAnalysis
• Gerund form preferred: analyzing-contracts, processing-pdfs (not contract-analyzer, pdf-processor)
• Avoid vague names: helper, utils, tools, misc
• Avoid reserved words: anthropic, claude

Path Handling

• Use {baseDir} for paths, never hardcode absolute paths
• Use forward slashes (/) even on Windows

Python Scripts

When skills include Python scripts with dependencies:

1. Use PEP 723 inline metadata - Declare dependencies in the script header:

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

2. Use uv run - Enables automatic dependency resolution:

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

3. Include pyproject.toml - Keep in scripts/ for development tooling (ruff, etc.)

4. Document system dependencies - List non-Python deps (poppler, tesseract) in workflows with platform-specific install commands

Hooks

PreToolUse hooks run on every Bash command—performance is critical:

• Prefer shell + jq over Python—interpreter startup (Python + tree-sitter) adds noticeable latency
• Fast-fail early - exit 0 immediately for non-matching commands so most invocations are instant
• Favor regex over AST parsing - accept rare false positives if performance gain is significant and Claude can rephrase
• Anticipate false positive patterns - diagnostic commands (which python), search tools (grep python), and filenames (cat python.txt) shouldn't trigger interception
• Document tradeoffs in PR descriptions so reviewers understand deliberate design choices

Quality Standards

These are Trail of Bits house standards on top of Anthropic's requirements.

Description Quality

Your skill competes with 100+ others. The description must trigger correctly.

• 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"

Value-Add

Skills should provide guidance Claude doesn't already have, not duplicate reference material.

• 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 - Say why something is wrong, not just that it's wrong

Example: The DWARF skill doesn't include the full DWARF spec. It teaches Claude how to use dwarfdump, readelf, and pyelftools to look up what it needs, plus judgment about when each tool is appropriate.

Scope Boundaries

Prescriptiveness should match 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

Required Sections

Every SKILL.md must include:

## When to Use
[Specific scenarios where this skill applies]

## When NOT to Use
[Scenarios where another approach is better]

Security Skills

For audit/security skills, also include:

## Rationalizations to Reject
[Common shortcuts or rationalizations that lead to missed findings]

Content Organization

• Keep SKILL.md under 500 lines - split into references/, workflows/
• Use progressive disclosure - quick start first, details in linked files
• One level deep - SKILL.md links to files, files don't chain to more files

Note: Directory depth is fine (references/guides/topic.md). Reference chains are not (SKILL.md → file1.md → file2.md where file1 references file2). The problem is chained references, not nested folders.

Progressive Disclosure Pattern

## 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.

PR Checklist

Before submitting:

Technical (CI validates these):

• Valid YAML frontmatter with name and description
• Name is kebab-case, ≤64 characters
• All referenced files exist
• No hardcoded paths (/Users/..., /home/...)
• python3 .github/scripts/validate_codex_skills.py passes

Quality (reviewers check these):

• 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

Documentation:

• Plugin has README.md
• Added to root README.md table
• Registered in root .claude-plugin/marketplace.json (repo-level, not the plugin's own .claude-plugin/)
• Added to CODEOWNERS with plugin-specific ownership (/plugins/<name>/ @gh-username @dguido)
  • To find the GitHub username: run gh api user --jq .login (most reliable — uses authenticated GitHub identity)

Version updates (for existing plugins):

• Increment version in both plugins/<name>/.claude-plugin/plugin.json and the root .claude-plugin/marketplace.json when making substantive changes (clients only update plugins when the version number increases)
• Ensure version numbers match between the plugin's plugin.json and its entry in the root .claude-plugin/marketplace.json