Skip to main content

​
What are Plugins?

Plugins are the fundamental packaging unit in Trail of Bits Skills. A plugin is a directory containing one or more of the following components:
  • Skills - Knowledge and guidance that Claude can invoke
  • Commands - Slash commands that trigger specific workflows
  • Agents - Autonomous agents that handle complex multi-step tasks
  • Hooks - Event listeners that intercept and modify tool execution
Plugins can contain any combination of these components. A plugin might have only skills, only commands, or a mix of all four.

​
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
Component directories (skills/, commands/, agents/, hooks/) must be at the plugin root, NOT inside .claude-plugin/. Only plugin.json belongs in .claude-plugin/.

​
Plugin Metadata

Every plugin must include a plugin.json file in the .claude-plugin/ directory:
.claude-plugin/plugin.json
{
  "name": "constant-time-analysis",
  "version": "0.1.0",
  "description": "Detect compiler-induced timing side-channels in cryptographic code",
  "author": {
    "name": "Scott Arciszewski",
    "url": "https://github.com/trailofbits"
  }
}

​
Required Fields

​
name
string
required
Plugin name in kebab-case. Must be unique across the repository.
​
version
string
required
Semantic version (e.g., “0.1.0”). Increment when making substantive changes - clients only update when version numbers increase.
​
description
string
required
Brief description of what the plugin provides.
​
author
object
required
Author information with name and optional url fields.

​
Plugin Examples by Complexity

​
Basic Plugin

ask-questions-if-underspecified - Minimal frontmatter, simple guidance Structure:
  • Single skill with straightforward workflow
  • No scripts or complex dependencies
  • Clear when-to-use guidance

​
Intermediate Plugin

constant-time-analysis - Python package, references/, language-specific docs Structure:
  • Skill with multiple reference files
  • Python scripts with PEP 723 inline metadata
  • Slash command integration
  • Language-specific guidance files

​
Advanced Plugin

culture-index - Scripts, workflows/, templates/, PDF extraction, multiple entry points Structure:
  • Complex skill with 10+ reference files
  • Multiple workflow files for different use cases
  • Python package with dependencies
  • Template files for report generation
  • Advanced PDF extraction scripts

​
Naming Conventions

Always use kebab-case for plugin and component names:
  • ✅ constant-time-analysis
  • ❌ constantTimeAnalysis
  • ❌ constant_time_analysis
Use verbs ending in -ing to describe actions:
  • ✅ analyzing-contracts
  • ✅ processing-pdfs
  • ❌ contract-analyzer
  • ❌ pdf-processor
Be specific about what the plugin does:
  • ❌ helper
  • ❌ utils
  • ❌ tools
  • ❌ misc
Don’t use brand names or reserved keywords:
  • ❌ anthropic
  • ❌ claude

​
Path Handling

Never hardcode absolute paths in plugin files. Always use {baseDir} for dynamic path resolution.
Correct: 
See the full guide at `{baseDir}/references/ADVANCED.md`
Incorrect: 
See the full guide at `/home/user/plugins/my-plugin/references/ADVANCED.md`
Path conventions:
  • Use forward slashes (/) even on Windows
  • Use {baseDir} for all paths to plugin resources
  • {baseDir} resolves to the plugin root directory at runtime

​
Development Workflow

1

Create plugin directory

mkdir -p plugins/my-plugin/.claude-plugin
2

Add plugin.json

Create .claude-plugin/plugin.json with metadata:
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "What your plugin does",
  "author": {
    "name": "Your Name",
    "url": "https://github.com/yourusername"
  }
}
3

Add components

Create one or more component directories:
  • skills/ for knowledge and guidance
  • commands/ for slash commands
  • agents/ for autonomous agents
  • hooks/ for event interception
4

Document the plugin

Add a README.md explaining what the plugin does and how to use it.

​
Publishing and Distribution

Plugins in the Trail of Bits Skills repository are registered in the root .claude-plugin/marketplace.json: 
{
  "plugins": [
    {
      "name": "constant-time-analysis",
      "version": "0.1.0",
      "path": "plugins/constant-time-analysis"
    }
  ]
}
Version numbers must match between the plugin’s plugin.json and the root marketplace.json. Clients only download updates when version numbers increase.

​
Best Practices

Modular Design

Keep plugins focused on a single domain or task. Split large functionality across multiple plugins.

Progressive Disclosure

Start with essential guidance in SKILL.md, link to detailed references for advanced users.

Clear Documentation

Include README.md with examples, use cases, and setup instructions.

Version Control

Increment versions for substantive changes. Document breaking changes clearly.

​
Next Steps

Skills

Learn how to create knowledge and guidance for Claude

Commands

Create slash commands that trigger workflows

Agents

Build autonomous agents for complex tasks

Quick Start

Build your first plugin in 5 minutes