claude-code-plugin-reference
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.
athola · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add athola/claude-night-market --skill 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 |
|---|