plugin-platform
Construct overlay on the official plugin-structure skill. Current plugin platform rules (userConfig, path variables, versions and cache, loading precedence, claude plugin CLI, /reload-plugins, --plugin-dir), corrections where plugin-structure is out of date, and construct's own layout. Use together with plugin-structure when changing plugin.json, marketplace.json, userConfig, bin/, component layout, the installer, or when a change "does nothing" after install or reload.
- License 许可
- MIT
- 最近更新
- 2026-10-30
- Stars
- ★ 1
- Forks
- 1
01 前言 Front Matter
- name
- plugin-platform
- description
- Construct overlay on the official plugin-structure skill. Current plugin platform rules (userConfig, path variables, versions and cache, loading precedence, claude plugin CLI, /reload-plugins, --plugin-dir), corrections where plugin-structure is out of date, and construct's own layout. Use together with plugin-structure when changing plugin.json, marketplace.json, userConfig, bin/, component layout, the installer, or when a change "does nothing" after install or reload.
03 SKILL.md 正文
The plugin platform in construct
Load the official plugin-structure skill first (anthropics/claude-code plugin-dev) for directory layout, naming, and component organization. This file adds what it lacks and corrects what is stale. Order of authority: the live docs, then this file, then plugin-structure.
Corrections to plugin-structure
| plugin-structure says | Current docs |
|---|---|
plugin.json is required |
optional; only name is required inside it |
| version must follow semver | not checked against semver; any string, and it pins users until it changes |
"command": "bash ${CLAUDE_PLUGIN_ROOT}/..." unquoted |
shell form must double-quote; prefer exec form with args |
no userConfig, ${CLAUDE_PLUGIN_DATA}, bin/, output styles, modules, types |
all exist; see below |
| custom paths for components | commands, agents, outputStyles replace their default folder; skills adds to it |
Sources (read 2026-10-23): manifest reference, components, loading, CLI reference. Version-gated details change; re-read before relying on one. Hook semantics: settings-hooks skill. Mod module: mods skill.
Construct today: plugins/construct/.claude-plugin/plugin.json sets name, displayName, version (8.1.0), license, description, author, keywords, types, and 35 userConfig options. .claude-plugin/marketplace.json lists it with the relative source ./plugins/construct.
plugin.json rules
- Only
nameis required (kebab-case; noclaude-,anthropic-,cc-plugin-prefixes). Components are namespaced under it:construct:worker,/construct:review. - Unknown top-level keys are stripped with a warning (fails
--strict). Unknown keys insideuserConfigoptions,channels,lspServers,monitorsare errors: the plugin does not load. - Component paths are relative and start with
./, use forward slashes, and must stay inside the plugin root (..is rejected). skillsadds to theskills/scan;commands,agents,outputStyles,workflows,experimental.themes,experimental.monitorsreplace their default folder (the folder is then ignored with a warning).hooksmerges withhooks/hooks.json.typespoints to a.d.tsthat declares a mod's$.stateand$nouns.settings(or a rootsettings.json, which wins): onlyagentandsubagentStatusLinetake effect. Plugin defaults are the lowest layer.- A root
CLAUDE.mdis not loaded as context (validate warns). That is why construct injects its contract through hooks. homepagemust parse as a URL or the plugin fails to load.
userConfig
- Option fields:
type(string,number,boolean,directory,file),title,description; optionalrequired,default,options(string only, not withmultiple/sensitive, v2.1.271+;defaultmust be one of them),multiple,sensitive,min/max. Keys: letters, digits,_, not starting with a digit. - Values reach components as:
CLAUDE_PLUGIN_OPTION_<KEY>(uppercased) in hook processes, for every option. This is what construct's hooks read.${user_config.KEY}in MCP/LSP config, exec-form hookargs, and skill and agent Markdown bodies (non-sensitive only).- Rejected (component fails) in shell-form hook
command, monitorcommand, MCPheadersHelper. Monitors get neither form.
- Non-sensitive values live under
pluginConfigsin usersettings.json;sensitiveones in the OS credential store. - Rows appear in
/config(v2.1.269+), exceptsensitiveandmultiple.claude plugin installnever prompts:--config KEY=VALUEorclaude plugin configure --values-stdin. - Adding, renaming, or removing an option, or changing its
type/options, is a consumed-contract change (Risk item 3): stored user values may stop loading.
Path variables
| Variable | Value | Use |
|---|---|---|
${CLAUDE_PLUGIN_ROOT} |
the installed version's directory, ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/; for a local-path marketplace, the source directory |
read-only code; changes on every update, never write state here |
${CLAUDE_PLUGIN_DATA} |
~/.claude/plugins/data/<id>/ (construct@construct → construct-construct) |
durable caches; survives updates, deleted on last uninstall unless --keep-data |
${CLAUDE_PROJECT_DIR} |
session-start project root | does not follow worktrees |
Exported to hook processes: ROOT, DATA, PROJECT_DIR, OPTION_*. None of them are in the Bash tool's environment, in the main session or subagents. Construct's per-repository stores live under the git common dir, not CLAUDE_PLUGIN_DATA, so they are shared by worktrees.
Components
bin/: on the Bash tool'sPATHwhile enabled, after the user's own entries (cannot shadowgit). Needschmod +x. claude.ai and Cowork refuse to install a plugin withbin/.- Agents:
agents/*.md, recursive; subfolders become name segments. Plugin agents ignorepermissionMode,hooks,mcpServers,initialPrompt. Details:agents-and-skills-authoringskill. - Skills:
skills/<dir>/SKILL.md→/construct:<dir>; frontmatternamereplaces the last segment. - Hooks:
hooks/hooks.jsonwith a top-level"hooks"key; amoduleskey lists mod modules. If two enabled plugins share a manifest name, only one registers hooks and only one loads its module (Errors tab, v2.1.296+). - Output styles:
output-styles/<name>.md→construct:<name>in/output-style. - Monitors and workflows exist too: monitors run only interactively, never with
-p, and not in repository (project-scope) plugins.
Versions, cache, and "my change does nothing"
- Version resolution: manifest
version, then marketplace entryversion, then a source-derived value (12-char git SHA for git sources;unknownfor a non-git local directory). - A pinned
versionkeeps users on the cached copy until the string changes:construct is already at the latest version (8.1.0).So every release bumpsversion(see CONTRIBUTING releases). - Relative-path plugins in a local-path marketplace load in place: edits apply at the next session or
/reload-plugins, no bump needed, no Node dependency install. - Old version directories get
.orphaned_atand are removed after 14 days. - Node deps install only for copied plugins with
package.jsonplusbun.lock,npm-shrinkwrap.json, orpackage-lock.json(v2/v3),--ignore-scripts, 60 s timeout. Construct has no runtime dependencies; keep it that way.
Which settings load the plugin
enabledPlugins, lowest to highest: --add-dir (only true), user ~/.claude/settings.json, project .claude/settings.json, local .claude/settings.local.json, --settings, managed (true forces, false blocks). The highest source that names the id wins. A project-only enable of an external-source plugin is not fetched. Claude Code does not scan .claude/plugins/.
CLI and reload
claude plugin validate --strict <path>: warnings fail; exit0,1, or2;--json(v2.1.259+). Run on both.and./plugins/construct.claude plugin test [dir]: mod tests (*.test.ts), no session or network.claude plugin eval: see theplugin-evalsskill.install/uninstall/update/enable/disabletake-s, --scope user|project|local(updatealsomanaged);enableon an already-enabled plugin exits1(already_in_goal_state).uninstall --keep-data.claude plugin tag [path]creates<name>--v<version>and checks thatplugin.jsonand the marketplace entry agree./reload-plugins [--force]reloads hooks, skills, agents, MCP, LSP; printsReloaded: N plugins · N skills · .... It refuses without--forcewhen the change would invalidate the prompt cache; monitors need a restart. Not documented for output styles or mod modules: restart the session to be sure.--plugin-dir <path>(repeatable; directory or.zip): loads in place as<name>@inline, silently overrides a same-named installed copy (--debuglogsPlugin "<name>" from --plugin-dir overrides installed version), unless managed settings lock the name orclaude plugin disable <name>@inlinewas run.
04 同仓库更多 Skills
workflow
The ADD protocol for every implementation request, feature plan, resume, task sizing, and the closing Risk line.
sources
Ground version-dependent code in official documentation. Use when you name a specific uncertainty about a library or framework API, a version-dependent pattern, or a deprecation. Skip when the repository already shows the pattern.
review
Mandatory outside review of high-risk work units, by lens agents the hooks feed and record, plus the dual blind review on request. Trigger: a unit whose Risk names an item is ready to publish, the publication gate denied a push, PR, or release, or the user asks for a review, a dual review, or an adversarial review.
migration
Plan and verify risky migrations and removals. Use when changing a schema or stored data, removing or renaming a public API, flag, config format, or export, replacing a system, or when the task's Risk names item 1 or 3.
delivery
Plan commits, branches, and pull requests as reviewable units. Use when deciding commit contents, opening or preparing a PR, splitting large work into sub-branches of a feature branch, or preparing a release.
delegation
When and how the ADD orchestrator delegates to construct agents: role mapping, allowed edit surfaces, parallel writers, verifier timing, handoff prompts, and relaying a subagent's blocking question or choice menu. Trigger: deciding to delegate, launching an agent, writing a handoff, or a subagent or tool returns a question, menu, or consent request.