/claude-code-plugin-reference

name: claude-code-plugin-reference
description: Explain plugin, skill, command, agent, and hook mechanics used here. Use when authoring or debugging plugins. Do not use for ops; use night-market-operations.

Claude Code Plugin Reference (night-market edition)

This is the domain pack for how Claude Code plugin machinery works in this repository. It covers manifests, skills, commands, agents, hooks, and the marketplace registry, with the local conventions layered on top. Every contract below was checked against a shipped plugin (mostly `plugins/imbue`, `plugins/abstract`, and `plugins/herald`) on 2026-07-02 at repo v1.9.15. When another night-market skill says "see the plugin reference for what a hook payload is," this is the file it means.

Vocabulary

Each term is defined once here and used without redefinition below.

| Term | Meaning in this repo | |------|----------------------| | Plugin | A directory under `plugins/` shipping skills, commands, agents, and hooks, with its own tests, Makefile, and pyproject.toml. Independently deployable (ADR-0001). | | Skill | A directory `skills/<name>/` containing `SKILL.md`. Loaded by the model on demand, invoked as `Skill(plugin:name)`. | | Module | A file under a skill's `modules/` subdirectory. Loaded only when the hub `SKILL.md` routes to it (progressive loading). | | Command | A markdown file under `commands/`. Surfaces as a slash command the user types. Repo docs refer to the namespaced form, e.g. `/sanctum:sync-capabilities`. | | Agent | A markdown file under `agents/` defining a dispatchable subagent: frontmatter plus a system-prompt body. | | Hook | An executable script Claude Code runs on a lifecycle event, registered in the plugin's `hooks/hooks.json`. | | Hook event | The lifecycle point a hook fires on: `PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `UserPromptSubmit`, and others (full table below). | | Manifest | `.claude-plugin/plugin.json`: the file Claude Code reads to register a plugin's components. | | Marketplace | The root `.claude-plugin/marketplace.json` registry listing all plugins, installed via `/plugin marketplace add`. | | Plugin cache | The directory Claude Code copies installed plugins into and executes them from. It is NOT the repo checkout. | | `${CLAUDE_PLUGIN_ROOT}` | Placeholder Claude Code expands to the plugin's cache path. The only safe way to reference plugin files from hooks. | | Host Python | The system Python interpreter that runs hook scripts. Assume 3.9, even though plugin package code targets 3.12. |

Anatomy of a night-market plugin

Verified tree (imbue, trimmed):

plugins/imbue/
├── .claude-plugin/
│   ├── plugin.json       # Claude Code manifest: registers everything
│   └── metadata.json     # inter-plugin dependency manifest
├── openpackage.yml       # cross-framework export manifest
├── skills/<name>/
│   ├── SKILL.md          # hub document with frontmatter
│   └── modules/*.md      # spokes, loaded on demand
├── commands/*.md         # slash commands
├── agents/*.md           # subagents
├── hooks/
│   ├── hooks.json        # hook registration (auto-loaded)
│   ├── *.py, *.sh        # hook scripts
│   └── shared/           # vendored helpers (hook_io, vow_utils, ...)
├── scripts/              # Python utilities skills shell out to
├── tests/                # pytest suite, run per plugin
├── Makefile              # per-plugin test/lint/typecheck targets
├── pyproject.toml        # package config, per-plugin coverage threshold
└── README.md

plugin.json field contract

| Field | What it does | Local rule | |-------|--------------|------------| | `name` | Plugin identity and namespace prefix for skills/commands | Matches directory name | | `version` | Plugin version | Lockstep with marketplace version (1.9.15). Never hand-edit, use the bumper (below) | | `description` | Marketplace listing text | Two-part style per ADR-0003 | | `skills` | Array of `"./skills/<dir>"` paths. Each dir must contain a `SKILL.md`. Registration makes `Skill(plugin:name)` resolvable | Keep in sync with disk via `/sanctum:update-plugins` | | `commands` | Array of `"./commands/<file>.md"` paths, each becoming a slash command | Same sync rule | | `agents` | Array of `"./agents/<file>.md"` paths, each a dispatchable subagent | Same sync rule | | `hooks` | Paths to ADDITIONAL hook files only. `./hooks/hooks.json` is auto-loaded and must never appear here | Every plugin in this repo keeps `"hooks": []` (verified across all 23 manifests). See the hooks section for why | | `keywords` | Marketplace search and discovery terms | Free-form | | `dependencies` / `optional_dependencies` | Names of other night-market plugins | Informational plus runtime detection only. ADR-0001 forbids import coupling: plugins detect each other via the filesystem and degrade gracefully | | `author`, `license` | Attribution | MIT throughout |

metadata.json

Second manifest in `.claude-plugin/`. Fields verified on imbue: `name`, `version` (lockstep), `main`, a `skills` subset, `dependencies`, `provides` (infrastructure/patterns/tools), and a `claude` block (`skill_prefix`, `auto_load`, `categories`). One trap: dependency ranges here use their own semver namespace. imbue declares `"abstract": ">=2.0.0"` while every plugin ships 1.9.15. The range is not compared against the marketplace version, so do not "fix" it to 1.9.15 during a bump. The `update_versions.py` bumper knows which fields to touch.

openpackage.yml

Cross-framework manifest consumed by the export pipeline (`make cross-framework`, `scripts/clawhub_export.py`). Lists the skills exported outside Claude Code and dependency sources in `gh@athola/claude-night-market` form. Its `version` is also lockstep.

SKILL.md contract

Frontmatter

Fields verified on `plugins/imbue/skills/proof-of-work/SKILL.md`. Only `name` and `description` are consumed by Claude Code itself. The rest are house conventions read by repo tooling.

| Field | Purpose | |-------|-