Plugin Structure

plugins/
  <plugin-name>/
    .claude-plugin/
      plugin.json         # Plugin metadata (required)
    skills/               # Optional: knowledge/guidance
    commands/             # Optional: slash commands
    agents/               # Optional: autonomous agents
    hooks/                # Optional: event hooks
    README.md             # Plugin documentation (required)

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Human-readable description of what the plugin does",
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "https://github.com/yourusername"
  }
}

skills/
  <skill-name>/
    SKILL.md              # Entry point with frontmatter (required)
    references/           # Optional: detailed documentation
    workflows/            # Optional: step-by-step guides
    scripts/              # Optional: utility scripts
    templates/            # Optional: file templates

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

# Skill Content

## When to Use
[Specific scenarios]

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

references/
  ADVANCED.md           # Advanced usage
  API.md               # API reference
  TROUBLESHOOTING.md   # Common issues

workflows/
  audit-workflow.md    # Audit process
  review-workflow.md   # Review process

scripts/
  analyze.py          # Analysis script
  report.py           # Report generator
  pyproject.toml      # Development tooling

templates/
  report-template.md  # Report structure
  config-template.yml # Configuration template

commands/
  command-name.md      # Command definition

---
name: /command-name
description: What the command does
---

# Command Implementation

When the user types `/command-name`, perform these actions:

1. Step one
2. Step two
3. Step three

agents/
  agent-name.md        # Agent definition

---
name: agent-name
description: What the agent does
---

# Agent Behavior

This agent autonomously:
- Task one
- Task two
- Task three

## Trigger Conditions

Activate when:
- Condition A
- Condition B

hooks/
  pre-tool-use/
    hook-name.sh      # Pre-execution hook
  post-tool-use/
    hook-name.sh      # Post-execution hook

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests>=2.28",
#     "pydantic>=2.0",
# ]
# ///

import requests
from pydantic import BaseModel

# Script code here

uv run {baseDir}/scripts/analyze.py input.txt

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

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.pytest.ini_options]
testpaths = ["tests"]

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

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

ask-questions-if-underspecified/
  .claude-plugin/
    plugin.json
  skills/
    ask-questions-if-underspecified/
      SKILL.md
  README.md

constant-time-analysis/
  .claude-plugin/
    plugin.json
  skills/
    constant-time-analysis/
      SKILL.md
      references/
        compiled.md
        javascript.md
        python.md
  ct_analyzer/
    analyzer.py
    tests/
      test_analyzer.py
  pyproject.toml
  README.md

culture-index/
  .claude-plugin/
    plugin.json
  skills/
    interpreting-culture-index/
      SKILL.md
      workflows/
        individual-analysis.md
        team-analysis.md
      templates/
        report-template.md
  scripts/
    extract_pdf.py
    pyproject.toml
  README.md

# Plugin Name

Brief description of what the plugin does.

## Installation

\`\`\`bash
/plugin marketplace add trailofbits/skills
/plugin menu
\`\`\`

## Features

- Feature 1
- Feature 2
- Feature 3

## Usage

### Skill Name

Description and usage example.

## Contributing

See [CONTRIBUTING.md](../../CLAUDE.md) for guidelines.

## License

License information.