Writing Plugins

Writing Plugins

Scope: covers plugin design and architecture. The examples use the Claude Code layout (.claude-plugin/plugin.json + auto-discovered commands/, agents/, skills/, hooks/). The same artifact-selection and architecture reasoning maps to the other tools — only the manifest path and packaging differ:

• Codex CLI: .codex-plugin/plugin.json manifest + .agents/plugins/marketplace.json; skills live at .agents/skills/. See [[nlpm:conventions-codex]].
• Antigravity: gemini-extension.json (becoming "Antigravity plugins"); skills at .agent/skills/. See [[nlpm:conventions-antigravity]].
• Cross-tool skills: a SKILL.md collection with no plugin wrapper installs into any tool via npx skills add. See [[writing-skills]].

For individual artifact authoring, see [[writing-skills]], [[writing-agents]], [[writing-hooks]], [[writing-rules]].

1. Plugin = Commands + Agents + Skills + Hooks

A plugin is a collection of NL artifacts that work together. Before writing anything, decide which artifacts you need.

Artifact Selection Guide

Minimum Viable Plugin

The smallest useful plugin has one artifact:

my-plugin/
  .claude-plugin/
    plugin.json
  commands/
    do-thing.md

Don't add agents, skills, or hooks until you need them. Each artifact adds maintenance burden.

2. Architecture Patterns

Pattern: Single Command (simplest)

Command does everything itself. No agents, no orchestration.

Command receives input --> processes --> outputs result

Use when: task is simple, deterministic, single-step. Example: loc-guardian /scan -- counts lines, checks limits, reports.

File structure:

my-plugin/
  .claude-plugin/plugin.json
  commands/do-thing.md

Pattern: Command + Agent

Command parses input and dispatches one agent for heavy work.

Command parses input --> dispatches agent --> formats output

Use when: task requires AI judgment but has a clear entry point. Example: /nlpm:score dispatches a scorer agent.

File structure:

my-plugin/
  .claude-plugin/plugin.json
  commands/analyze.md
  agents/analyzer.md

Pattern: Command + Multiple Agents (parallel)

Command dispatches 2–6 agents in parallel, synthesizes results.

Command --> agent-1 (security)
        --> agent-2 (performance)    --> synthesize --> output
        --> agent-3 (architecture)

Use when: multiple independent analyses of the same input. Example: grill dispatches 6 review agents in parallel.

File structure:

my-plugin/
  .claude-plugin/plugin.json
  commands/review.md
  agents/
    security-agent.md
    performance-agent.md
    architecture-agent.md

Pattern: Command + Agent Pipeline (sequential)

Each agent feeds into the next. Stages have different model requirements.

Command --> parse (haiku) --> analyze (sonnet) --> QC (sonnet) --> output

Use when: multi-phase processing where each phase depends on the previous. Example: reading-assistant's 4-phase pipeline.

File structure:

my-plugin/
  .claude-plugin/plugin.json
  commands/process.md
  agents/
    parser.md       # haiku
    analyzer.md     # sonnet
    qc-agent.md     # sonnet

Pattern: Hooks Only (no commands)

Plugin enforces policy silently via hooks. No user-facing commands.

Event fires --> hook checks --> allow/deny/advise

Use when: enforcement should be automatic, not user-initiated. Example: tdd-guardian's pre-commit quality gate.

File structure:

my-plugin/
  .claude-plugin/plugin.json
  hooks/hooks.json
  scripts/check.sh

Pattern Selection Matrix

3. The plugin.json Manifest

Required Fields

Only name is strictly required:

{
  "name": "my-plugin"
}

Recommended Fields

Ship with these for discoverability and marketplace listing:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "What this plugin does in one sentence",
  "author": { "name": "your-name" },
  "license": "MIT",
  "keywords": ["relevant", "search", "terms"]
}

category is not a manifest field: it belongs to the plugin's entry in a marketplace.json (see §9 and nlpm:conventions-claude §1). Claude Code ignores it in plugin.json.

Field Reference

4. File Structure

Full Plugin Layout

my-plugin/
  .claude-plugin/
    plugin.json              # manifest (required)
    marketplace.json         # for marketplace publishing
  commands/                  # auto-discovered by Claude Code
    do-thing.md              # user-invocable: /plugin:do-thing
    advanced-thing.md
    shared/                  # non-invocable partials
      common-logic.md        # user-invocable: false
      format-output.md
  agents/                    # auto-discovered
    worker.md
    reviewer.md
  skills/                    # auto-discovered
    my-plugin/
      domain-knowledge/
        SKILL.md
      advanced-topic/
        SKILL.md
        references/
          deep-dive.md
  hooks/
    hooks.json               # hook definitions
  scripts/                   # hook scripts, utilities
    check.sh
    validate.sh
  AGENTS.md                  # developer notes and architecture (for the model); no root CLAUDE.md
  README.md                  # user documentation (for humans)
  LICENSE

Directory Conventions

Naming Conventions

5. Versioning

Semver Rules

Four-Place Update

When bumping version, update in four places:

Order: push plugin repo first, then update central marketplace. The marketplace points to the repo -- if the repo isn't updated yet, users pull stale code.

6. AGENTS.md for Plugins

Your plugin's AGENTS.md is for the model (Claude, Codex), not the user. It tells the model how the plugin's artifacts relate to each other. Claude Code 2.1.277+ reads AGENTS.md natively. Do not put a CLAUDE.md at the plugin root: it is not loaded as plugin context, claude plugin validate warns about it, and while it exists Claude Code skips AGENTS.md in that directory (see nlpm:conventions-claude §10).