跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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.

TermMeaning in this repo
PluginA directory under plugins/ shipping skills, commands, agents, and hooks, with its own tests, Makefile, and pyproject.toml. Independently deployable (ADR-0001).
SkillA directory skills/<name>/ containing SKILL.md. Loaded by the model on demand, invoked as Skill(plugin:name).
ModuleA file under a skill's modules/ subdirectory. Loaded only when the hub SKILL.md routes to it (progressive loading).
CommandA markdown file under commands/. Surfaces as a slash command the user types. Repo docs refer to the namespaced form, e.g. /sanctum:sync-capabilities.
AgentA markdown file under agents/ defining a dispatchable subagent: frontmatter plus a system-prompt body.
HookAn executable script Claude Code runs on a lifecycle event, registered in the plugin's hooks/hooks.json.
Hook eventThe 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.
MarketplaceThe root .claude-plugin/marketplace.json registry listing all plugins, installed via /plugin marketplace add.
Plugin cacheThe 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 PythonThe 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

FieldWhat it doesLocal rule
namePlugin identity and namespace prefix for skills/commandsMatches directory name
versionPlugin versionLockstep with marketplace version (1.9.15). Never hand-edit, use the bumper (below)
descriptionMarketplace listing textTwo-part style per ADR-0003
skillsArray of "./skills/<dir>" paths. Each dir must contain a SKILL.md. Registration makes Skill(plugin:name) resolvableKeep in sync with disk via /sanctum:update-plugins
commandsArray of "./commands/<file>.md" paths, each becoming a slash commandSame sync rule
agentsArray of "./agents/<file>.md" paths, each a dispatchable subagentSame sync rule
hooksPaths to ADDITIONAL hook files only. ./hooks/hooks.json is auto-loaded and must never appear hereEvery plugin in this repo keeps "hooks": [] (verified across all 23 manifests). See the hooks section for why
keywordsMarketplace search and discovery termsFree-form
dependencies / optional_dependenciesNames of other night-market pluginsInformational plus runtime detection only. ADR-0001 forbids import coupling: plugins detect each other via the filesystem and degrade gracefully
author, licenseAttributionMIT 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.

FieldPurpose
阅读完整来源 ↗