Build and polishan entire Claude Code plugin(manifest / component wiring / hook / advanced components / marketplace). Based on the three official specs plugins / plugins-reference / plugin-marketplaces + this repository's docs/ + plugins/tools/* real plugins.
Details are split across files (read as needed, do not read all):
- references/manifest-and-wiring.md — plugin.json all fields + component directories + namespace + version semantics
- references/hooks.md — 31 event table / 5 hook types / matcher / exit code contract / stdin payload / async / path variables
- references/advanced-components.md — MCP / LSP(+v2.1.205) / monitors / themes / channels / bin / settings / userConfig / dependencies
- references/multi-language.md — compiled-language pitfalls / three approaches / cross-platform / shared code
- references/marketplace.md — marketplace.json schema / 5 source types / publishing process
- references/debugging.md — claude --debug / validate --strict / full plugin CLI / error message quick reference / hook/MCP/LSP/monitor troubleshooting / 4-layer version resolution / cache + symlink
- references/optimize-rubric.md — health check command / 8-dimension scoring (direction axis + ideal value + baseline) / validation-gate loop
Hard guardrails (prohibitions that cannot be stated positively, with positive examples)
| Prohibited (elephant) | Positive example (target) |
|---|---|
Stuffing components into the .claude-plugin/ directory |
Components at the plugin root;.claude-plugin/ only for plugin.json |
hook command hardcoded absolute paths / missing timeout |
${CLAUDE_PLUGIN_ROOT}/scripts/x.sh + each hook with timeout |
guard hook exit 1(semantically vague) |
guard uses exit 2 to block; side-effect hook failure exit 0 as fallback |
MCP env / secrets hardcoded |
${ENV_VAR} reference environment variables |
Designing plugin features for the user out of thin air / plain text instead of AskUserQuestion |
brainstorm question by question + use AskUserQuestion to decide on key disagreements |
| auto push | after changes git add(project rules) + commit,no push, wait for explicit instructions |
| Modify SKILL.md / agent.md skipping the quality gate | after changes pass claude -p quality gate (enforced by project CLAUDE.md) |
Quality gate command (when the endpoint flakily returns 400, retry loop 8 times, see memory claude-p-endpoint-flaky; if still failing → manual verification + small rollback-able commit, marked "to be re-run once endpoint recovers"):
claude -p "<待测内容>" --output-format stream-json | jq -r 'select(.type=="result" and .subtype=="success") | .result'
Routing (first determine whether create or optimize)
| Input signal | Go to |
|---|---|
| "Create a new plugin / make a plugin from scratch / scaffold a plugin" | Process A · Create |
| "Optimize / review / check this plugin / why doesn't the plugin load" | Process B · Optimize |
| Only writing a single skill / agent / command | 🛑 Stop, route to /skill-dev(this skill is plugin-level, does not handle single components) |
| Pure quality scoring of a single SKILL.md | 🛑 Stop, route to /skill-dev(its Process B does in-depth evaluation of a single skill) |
Process A · Create plugin
One-sentence responsibility: build ainstallable, loadable, zero-dangling-wiringplugin skeleton, depth quality delivered /skill-dev。
1. Define scope (brainstorm, not design out of thin air)
Ask the user question by question: what problem the plugin solves / target users / which components are needed (command / agent / skill / hook / MCP / LSP / monitor). For key disagreements use AskUserQuestion to make the call.
Done when: Component list + a one-sentence responsibility for each component, user nods (use AskUserQuestion, plain text forbidden).
2. Build the skeleton
Create the directory under plugins/tools/<name>/(aligned with this repo's conventions):
mkdir -p plugins/tools/<name>/.claude-plugin
# 按清单只建需要的：commands/ agents/ skills/ hooks/ scripts/ bin/ monitors/
A single-skill plugin can skip skills/，SKILL.md and place it directly at the root.
Done when: Every component directory in the list has been created, with no extra empty directories.
3. Write the manifest
.claude-plugin/plugin.json(all fields + namespace + version semantics see references/manifest-and-wiring.md）：
{
"name": "<name>", // 必填, kebab-case, = 目录名, = namespace 前缀
"description": "<做什么 + 差异化核心>",
"author": { "name": "...", "email": "...", "url": "..." },
"homepage": "...", "repository": "...", "license": "AGPL-3.0-or-later",
"keywords": ["..."],
"skills": ["./skills/<name>-x"], // 数组=逐条挂, 或 "./skills/" 挂整目录
"agents": ["./agents/<name>-y.md"],
"commands": ["./commands/<name>-z.md"],
"hooks": { /* 见 references/hooks.md */ },
"userConfig": { /* 可选, 见 references/advanced-components.md */ }
// version 省略则走 git commit SHA；正式发布再加 semver
}
Done when: jq . passes;name kebab-case = directory name;description contains "what it does + differentiation".
4. Write the components
Delegate the specific way to write each component to /skill-dev, this skill only guarantees the wiring.
Delivery requirement: target plugin components are phrased positively by default, retaining counterexamples only for necessary hard-guardrail scenarios (rejected naming pattern + reason + positive example).
- command：
commands/*.md，frontmatterdescription/argument-hint/allowed-tools/model; for the body use$ARGUMENTS/$1。 - agent：
agents/*.md，frontmattername(required) /description(required) /tools/model/skills。 - skill：
skills/<skill>/SKILL.md(uppercase). - hook：
plugin.jsoninlinehooksor standalonehooks/hooks.json; event / matcher / exit code / payload / async / timeout required reading references/hooks.md。 - MCP / LSP / monitor / bin / settings / userConfig / outputStyles: see references/advanced-components.md。
- script distribution(compiled/interpreted/uvx): see references/multi-language.md. 🔴 Core:
claude plugin adddoes not compile or install dependencies.
Done when: Health check #3 #4 zero dangling zero missing (every mount path has a real file + every component file is mounted).
5. Local verification
jq . plugins/tools/<name>/.claude-plugin/plugin.json # JSON 合法
claude plugin validate # 官方校验（提交前必跑）
claude --plugin-dir ./plugins/tools/<name> # 开发加载（非安装）
# 进会话后 /reload-plugins 重载改后生效
Done when: Run each command / trigger each skill (/<name>:<skill>) / call each agent / fire each hook event one by one, confirming it actually loads (observe actual triggering, not "it should run").
6. Mount to marketplace
At the repo root .claude-plugin/marketplace.json 's plugins[] append an entry (full schema + 5 source types see references/marketplace.md）：
{ "name": "<name>", "source": "./plugins/tools/<name>",
"description": "...", "author": {...},
"homepage": "...", "repository": "...", "license": "...", "keywords": [...] }
Done when: marketplace.json entry name/source/description/author/license/keywords align field by field with plugin.json .
7. Add docs + commit
README.md(recommended); changes auto git add(project rule), commit follows feat(<name>): ...，push forbidden。
Done when: Fill in the creation report below and hand it to the user.
Scope
- Problem solved: <one sentence>
- Target users: <one sentence>
- Key disagreement rulings (
AskUserQuestion): <list>
Component list
| Component | Path | One-sentence responsibility |
|---|---|---|
| command | commands/.md | ... |
| skill | skills//SKILL.md | ... |
| agent | agents/.md | ... |
| hook | hooks/... | ... |
Manifest
- name: (= directory name ✓)
- description contains "what it does + differentiation": ✓ / ✗
- Fields complete (author/license/homepage): ✓ / ✗
Wiring table (bidirectional check)
- Dangling (mounted but no file): none / <list>
- Missing (file not mounted): none / <list>
Verification results
jq .：✓ / ✗claude plugin validate：✓ / ✗--plugin-dirActually loaded + each component triggered: ✓ / ✗- marketplace entry aligned field by field: ✓ / ✗
- Quality gate
claude -p(only runs if .md changed): ✓ / pending endpoint recovery to re-run
Flow B · Optimize plugin
One-sentence responsibility: first perform a mechanical health check to locate hard defects, then score and prioritize according to the 8-dimension rubric, and iterate the validation-gate loop until convergence at the ceiling.For the health check command + full rubric, see references/optimize-rubric.md。
8-dimension quick overview (weights): ① Manifest compliance (16) ② Component wiring completeness (20) ③ Structural standards (12) ④ Hook robustness (14) ⑤ Component quality (14, in-depth review delegated to /skill-dev) ⑥ Marketplace consistency (12) ⑦ Documentation completeness (6) ⑧ Naming metadata consistency (6).
B-1. Fix health check hard defects first
Run optimize-rubric.md health check command with 9 items. Hits on dimensions 1/2/3 (invalid JSON / dangling or missing wiring / misplaced components) = P0, fix first.
Done when: All 9 health check items green or only non-blocking ⚠️ remaining.
B-2. Score by 8 dimensions + prioritize
Score each dimension 1-10 × weight according to the rubric; record the before score + direction axis + completion criteria baseline status.Independent verification: spawn an independent sub-agent to run scoring (self-scoring in the same context is prohibited; self-scoring is +1 overly optimistic).
Done when: All 8 dimensions have before scores; the lowest dimension (and one whose direction axis has not met the standard) is locked as this round's target.
Delivery requirement: if this round modifies component body text (skill/agent/command body), the target component should use positive phrasing by default, retaining counterexamples only in necessary hard-guardrail scenarios (rejected naming patterns + reasons + positive examples).
B-3. validation-gate loop
Modify one dimension per round (or one related cluster); keep only if it passes the gross gate (Δ>0) + human review gate (use AskUserQuestionfor destructive/wiring/trigger word changes), otherwise git revert HEAD roll back; if Δ<2 for 2 consecutive rounds → ceiling reached, break; if post-change size > original ×1.5 → reject submission.For the complete 6-element flowchart + independent verification discipline, see optimize-rubric.md。
Done when: Ceiling reached, break, or all dimensions meet the completion criteria baseline; fill in the optimization report below and deliver it to the user.
Health check results
- Hard defects (P0, dimensions 1/2/3): <list or none>
- ⚠️ Non-blocking: <list or none>
8-dimension before → after + Δ + direction axis
| # | Dimension | Weight | Direction | Ideal value | before | after | Δ | Completion baseline met ✓/✗ |
|---|---|---|---|---|---|---|---|---|
| 1 | Manifest compliance | 16 | ↑ | 10 | ||||
| 2 | Component wiring completeness | 20 | ↑ | 10 | ||||
| 3 | Structural standards | 12 | ↑ | 10 | ||||
| 4 | Hook robustness | 14 | ↑ | 10 | ||||
| 5 | Component quality | 14 | ↑ | 8 | ||||
| 6 | Marketplace consistency | 12 | ↑ | 10 | ||||
| 7 | Documentation completeness | 6 | ↑ | 8 | ||||
| 8 | Naming metadata consistency | 6 | ↑ | 10 | ||||
| Σ/100 |
Keep / roll back list
| Round | Dimension | gross Δ | Direction axis | gate (gross + human review) | Keep/Roll back | Reason |
|---|---|---|---|---|---|---|
| 1 |
Ceiling signal
- Consecutive Δ<2 rounds: / break: yes / no
- Bloat guardrail: post-change size / original size = <ratio> (≤1.5 ✓ / >1.5 reject submission)
- Independent verification: spawn sub-agent each round ✓ / same-context self-scoring ✗
Dimensions not meeting baseline (hand off to subsequent rounds or /skill-dev in-depth review)
- <list or all met>
Visual results card (optional, showcase achievements)
Copy templates/result-card.html, fill in plugin name / before-after-Δ weighted score / health-check P0 hard flaws / 8-dimension before▸after / hill-climbing rounds / improvement summary / date, open in browser or take a screenshot. The template ships with 3 styles (swiss/terminal/newspaper, switched via URL hash), 8-dimension weighting (weights ×16/20/12/14/14/12/6/6 = 100), JS automatically computes the weighted score and bar widths, no external scripts needed.
Failure modes (characteristic failures → fixes)
| Trigger | First-line fix | Fallback if still failing |
|---|---|---|
claude plugin add / --plugin-dir load failure |
jq . validate manifest JSON + health-check for dangling entries |
Bisect component by component: first mount only skills, then add one by one, to locate the bad component |
| Component not taking effect (command/skill doesn't appear) | Check for missed mounting + case + SKILL.md uppercase; the invocation name is /<plugin>:<skill> |
Check whether it was mistakenly placed in .claude-plugin/ ;/reload-plugins or restart the session |
| hook error blocks the session | Add timeout + change ${CLAUDE_PLUGIN_ROOT} + fail exit 0; for guard use exit 2 |
First remove that hook from the manifest to restore usability, then debug it separately |
| hook not triggering | Check matcher spelling (case-sensitive) / event name (PostToolUse not post_tool_use) / command path / script +x |
claude --debug to see the live trigger |
| marketplace source relative fails | When a user adds a marketplace from a URL, relative doesn't resolve → change to github/url/npm source | Only use relative when adding a marketplace via git/local |
Quality gate claude -p returns 400/empty |
Retry loop 8 times (endpoint flakiness) | Still failing → manual review + small rollback-able commit, marked "pending endpoint recovery for re-run" |
| Uncertain whether it's better after optimization | Independent sub-agent re-runs health check for comparison + passes quality gate | Score fine-grained untrustworthy → destructive/wiring changes go to user for confirmation |
Rejected framings (rejected naming/framing + reason + positive example, complementary to and non-overlapping with the hard guardrail table above)
- 「
claude plugin addwill compile/install dependencies for me" — add only copies, doesn't build. Positive example: precompiled binaries into bin/, or uvx/interpreted distribution, see multi-language.md. - "The plugin works without mounting it in a marketplace" — without mounting it can't be discovered/installed by the marketplace. Positive example: append
marketplace.jsonentry and align field by field. - "Use this skill to write a single skill/agent" — out of scope, single components belong to
/skill-dev. Positive example: route/skill-dev(see routing table above).
Resources
- Three official articles：plugins · plugins-reference · plugin-marketplaces
- This repo's
docs/plugin-development.md— structure / component format / release process tutorial. - For the complete manifest / hooks / MCP / marketplace schema see the official plugins-reference; for multi-language / compiled distribution see references/multi-language.md; for design principles / naming / security see the official plugins。
plugins/tools/*(skein / notify / version / cortex / deepresearch / novelist / trellisx) — real plugin examples.- Root
.claude-plugin/marketplace.json— real field template for marketplace entries.
Out of scope
- Covers the Claude Code plugin system (official spec as of 2026-07-17 fetch); some new fields are marked
{/* min-version: x.y.z */}depends on the user's Claude Code version. - In-depth component quality assessment (skill 9-dimension scoring / agent body design)—see the "Routing" table above; Dimension 5 of this skill only performs a threshold check.
- Scoring rubric weights are empirical summaries; fine-grained details are unreliable, and important decisions require human review.