
marketplace-dev
Scaffold, audit, and maintain Claude Code plugins and plugin marketplaces: a markdown-vs-script decision framework, a structural best-practices review agent, scaffolding skills (plugin, marketplace, eval), a generalized plugin-audit, and the migrated agent/skill authoring toolkit. Companion plugin to dev-team.
- version
- 1.3.0
- GitHub stars
- 304
Install
/plugin install marketplace-dev@bfinsterRun it inside Claude Code after adding the marketplace with /plugin marketplace add bdfinst/agentic-dev-team.
Contents
Discovered from sourceSkills 10
Add Plugin
Role: implementation. This skill installs a Claude Code plugin and
adds it to .claude/settings.json so the project's plugin set is
reproducible.
You have been invoked with the /add-plugin skill.
Implementation constraints
- Always update settings.json. Installing without registering defeats the purpose — the whole point is reproducibility.
- Derive marketplace from the identifier. The
name@marketplaceformat encodes both; never ask the user to repeat information already in the argument. - Do not duplicate entries. Check settings.json before adding; if the plugin is already registered, report it and stop.
- Be concise. Report only the outcome — no narration of each step.
Parse Arguments
Arguments: $ARGUMENTS
Required: plugin identifier ($0) in name@marketplace format —
e.g. skill-creator@claude-plugins-official or refactoring@refactoring.
Optional:
--repo <owner/repo>: GitHub repository to register as the marketplace source before installing (e.g.elifiner/refactoring). Required for plugins not on an official marketplace.
Steps
1. Parse arguments
Extract:
NAME— the part before@in$0MARKETPLACE— the part after@in$0REPO— value of--repo, or empty string if not provided
2. Check for existing registration
Read .claude/settings.json. If enabledPlugins already contains
"<NAME>@<MARKETPLACE>": true, report:
<NAME>@<MARKETPLACE> is already registered in settings.json. Nothing to do.
and stop.
3. Register marketplace (if --repo provided)
If REPO is non-empty, run:
claude plugin marketplace add <REPO>
If this fails, report the error and stop.
4. Install the plugin
Run:
claude plugin install <NAME>@<MARKETPLACE>
If this fails, report the error and stop — do not update settings.json for a plugin that did not install successfully.
5. Add to settings.json
Add to the enabledPlugins object in .claude/settings.json:
"<NAME>@<MARKETPLACE>": true
If a --repo was provided, also add to extraKnownMarketplaces:
"<MARKETPLACE>": {
"source": {
"source": "github",
"repo": "<REPO>"
}
}
6. Report
Installed: <NAME>@<MARKETPLACE>
Repo: <REPO or "official marketplace">
settings.json: updated
Agent Add
Role: implementation.
Implementation constraints
- Follow the official sub-agent schema and token budgets.
- Delegate the build to the agent-create skill; do not improvise structure.
- Be concise. Report the created agent file, no narration.
Steps
1. Parse arguments
Capture the agent name/spec or URL from $ARGUMENTS.
2. Delegate
Invoke the agent-create skill with the arguments.
3. Record the decision-log row
agent-create Step 15 appends a keep row to docs/model-effort-decisions.md
when the target repo has that file. Do not skip it. In a repo without the
file, nothing happens.
4. Report
Output the created file path, and the decision-log row when one was added.
Apply the guidelines defined in skills/agent-create/SKILL.md to the current task. Read the skill file and follow its steps exactly.
If $ARGUMENTS starts with http:// or https://, fetch the URL with
WebFetch first and extract the relevant guidance, then use that content as
the agent description.
Pass these flags through to the skill as context:
--plugin <dir>→ target plugin directory (resolved by agent-create Step 0)--name <name>→ set agent name (skips name prompt)--type review|team→ set agent type (skips type prompt)--model sonnet|opus|haiku|fable|inherit|<full model ID>→ sets the agent's model (invalid values rejected against agent-contract.json)--effort low|medium|high|xhigh|max→ sets the agent's reasoning effort (invalid values rejected against agent-contract.json)--memory user|project|local/--isolation worktree/--color <color>/--max-turns <int>/--background true|false/--skills <name1,name2,...>→ optional native fields, no forced defaults--context diff-only|full-file|project-structure→ setsContext needs:field--lang <exts>→ adds language scope declaration to the body--dry→ show generated content without writing to disk or updating registry
Apply this skill to: $ARGUMENTS
Agent Create
Automates production of Claude Code sub-agent files that pass schema validation
and stay within token-efficiency budgets. For conventions, anti-patterns, and
registration checklists, see skills/agent-skill-authoring/SKILL.md.
Constraints
- Do not write any file until validation passes and the user confirms the draft
- Name validation is a hard gate — exit immediately if the name is invalid
- Never include
hooks,mcpServers, orpermissionModewithout explicit user confirmation after the plugin warning - Body line budgets are hard limits enforced at generation time; trim content is shown to the user before any file is written
- Registry and CLAUDE.md updates are append-only; never edit existing rows
Step 0 — Resolve Target Plugin
Determine $PLUGIN (the target plugin directory) and $NAME (the plugin's
name field from .claude-plugin/plugin.json):
- If
--plugin <dir>was passed, use that directory as$PLUGIN. - Else if exactly one
plugins/*/directory exists in the repo root, use it. - Else if the current working directory is inside a directory containing
.claude-plugin/plugin.json, use that directory. - Else ask:
Which plugin directory should the agent be added to?
Read $PLUGIN/.claude-plugin/plugin.json and extract the name field as
$NAME. All subsequent path references use $PLUGIN/ and $NAME.
Step 1 — Parse Arguments
Accept these inputs (from arguments or interactive prompts):
| Input | Required | Notes |
|---|---|---|
name | yes | file stem of the new agent |
type | yes | review or team |
description | yes | one-line summary for frontmatter |
tools | no | comma-separated tool list |
--plugin <dir> | no | target plugin directory (resolved in Step 0) |
--model sonnet|opus|haiku|fable|inherit|<full model ID> | no | model the agent runs on; a value is suggested and confirmed in Step 5 if omitted |
--effort low|medium|high|xhigh|max | no | reasoning effort for this agent; a value is suggested and confirmed in Step 5 if omitted |
--memory user|project|local | no | persistent memory scope; omitted unless specified |
--isolation worktree | no | run in an isolated git worktree; omitted unless specified |
--color red|blue|green|yellow|purple|orange|pink|cyan | no | display color in the task list/transcript; omitted unless specified |
--max-turns <int> | no | cap on agentic turns before the subagent stops; omitted unless specified |
--background true|false | no | always run as a background task; omitted unless specified |
--skills <name1,name2,...> | no | skill names to preload into context at startup; omitted unless specified |
--context diff-only|full-file|project-structure | no | sets Context needs: field in review body |
--lang <exts> | no | adds language scope line to review body (e.g. Scope: .ts, .tsx files only) |
--dry | no | display generated content without writing file or updating registry |
Agents declare the native Claude Code sub-agent contract — model: (an alias,
a full model ID, or inherit) and effort: (a reasoning-effort level),
resolved by the harness itself at dispatch, no plugin-owned resolution step.
${CLAUDE_PLUGIN_ROOT}/knowledge/agent-contract.json is the single source of
truth for every field's valid values.
Reject an invalid --model or --effort value. If either flag is given
and doesn't match agent-contract.json's enum for that field, stop and emit
the valid set: model: sonnet|opus|haiku|fable|inherit (or a full model
ID); effort: low|medium|high|xhigh|max. Example:
Invalid effort 'frontier'. Valid values: low, medium, high, xhigh, max.
Reject an invalid --memory/--isolation/--background value the same
way, against that field's enum in agent-contract.json. --color is
validated against only the 4 mechanically-valid colors
(purple|green|yellow|cyan, ADR 0027) — not the contract's full 8-color
enum — because Step 5 below suggests a value the fleet's color test gate
(tests/agents/test_agent_fleet_conventions.py) checks by exact equality
with no escape valve; a --color value from the other 4 contract colors
(red|blue|orange|pink) would pass this validation and then fail that gate.
--max-turns must be a positive integer; --skills entries are not
validated against a fixed set (skill names are plugin-specific) but each
must resolve to a real $PLUGIN/skills/<name>/SKILL.md — warn (not fail) if
one doesn't.
Step 2 — Validate Name (hard gate)
The name must match ^[a-z][a-z0-9-]*$ exactly.
If it does not:
- Emit:
Name must match ^[a-z][a-z0-9-]*$ — use lowercase letters, digits, and hyphens only - Compute a kebab-case correction:
- Lowercase all characters
- Replace runs of non-alphanumeric characters with a single hyphen
- Strip leading/trailing hyphens
- If result starts with a digit: strip leading digits and any adjacent hyphens from the front; if the result is then valid, use it; if empty or still invalid, skip the suggestion
- If a valid correction exists, emit:
Did you mean: <corrected-name>? - Stop immediately. Do not write any file.
Step 3 — Detect Agent Type
If type was not provided:
- Scan
descriptionfor keywords:review,audit,check,validate,detect,scan,lint→ inferreviewengineer,architect,manager,writer,planner,designer,specialist→ inferteam
- If inference is confident, state the inferred type and continue
- If ambiguous or no keywords match, ask:
Agent type: review or team?
Step 4 — Prompt for Missing Tools
If tools was not provided, emit exactly:
Which tools does this agent need?
Read, Grep, Glob (read-only) | add Edit, Write (file changes) | add Bash (shell) | add Skill (skill invocation) | add Agent (spawn subagents)
Wait for the user's selection before continuing.
If tools were provided, validate each against known Claude Code tool names
(Read, Grep, Glob, Bash, Edit, Write, Agent, Skill,
WebFetch, WebSearch, NotebookRead, NotebookEdit). Flag unknown names
as a warning (not an error — custom tools are allowed).
Step 5 — Suggest and Confirm Model/Effort/Color/Skills/Memory; Apply the Tools Default
model, effort, and color are never silently defaulted — always
suggested, then confirmed with the user:
- If
--modelwas not provided, suggest by type: review→haiku, team→sonnet. If--effortwas not provided, suggesthighfor either type. - Emit:
Suggested model: <model>, effort: <effort> — accept? (yes/change) - On
yes: use the suggested values and continue. - On
change: askModel?and/orEffort?for whichever the user wants to change, validate each againstagent-contract.json's enum (the rejection rule in Step 1), then continue with the confirmed values.
If the user passed --model and/or --effort explicitly in Step 1, skip
this prompt for that field entirely — an explicit flag is already a
decision, not something to re-confirm.
Color follows the same suggest-and-confirm shape, computed from the
mechanical rule (ADR 0027): Agent in the resolved tools: → purple;
else Edit/Write in tools: → yellow; else the name ends -review or
starts plan-review- → green; else → cyan.
- If
--colorwas not provided, compute the suggestion from the rule above using the tools resolved in Step 4/this step and the agent'sname. - Emit:
Suggested color: <color> — accept? (yes/change). - On
yes: use the suggested value and continue. - On
change: askColor?, validate against the same 4-color set the Step 1 rejection rule uses (purple|green|yellow|cyan— not the contract's full 8-color enum, since the fleet's color test gate checks exact equality with the rule-computed value and has no escape valve for the other 4). On an invalid answer, emit the same 4-value rejection message as Step 1 and re-ask rather than aborting the whole flow.
If the user passed --color explicitly in Step 1, skip this prompt — an
explicit flag is already a decision, not something to re-confirm.
tools keeps its silent default (Read, Grep, Glob for review agents when
not specified) — no confirmation needed, it isn't a cost/capability choice
the way model/effort/color are.
Skills and memory also follow the suggest-and-confirm shape, pinned to the same wording pattern color uses above (issue #1335):
- If the generated agent body includes a
## Skillssection, list every skill name that section documents and emit:Suggested skills: [<name1>, <name2>, ...] — accept? (yes/change). Onyes: use the listed names. Onchange: ask which names to add/remove; each must resolve to a real$PLUGIN/skills/<name>/SKILL.md(warn, don't fail, per the existing--skillsvalidation rule). If the body has no## Skillssection, skip this prompt — omitskills:entirely. - If the resolved
tools:includesEditorWrite, emit:Suggested memory: project — accept? (yes/change). Onyes: useproject. Onchange: askMemory scope?and validate againstproject— the fleet's memory test gate (test_every_file_mutating_agent_declares_memory_project) checks exact equality againstprojectfor everyEdit/Writeagent and has no escape valve, so--memorycannot be omitted or set to anything else here; on an invalid answer, restate thatprojectis the only accepted value for a file-mutating agent and re-ask rather than aborting the whole flow. Iftools:has neitherEditnorWrite, skip this prompt — omitmemory:entirely.
If the user passed --skills and/or --memory explicitly in Step 1, skip
the respective prompt — an explicit flag is already a decision.
isolation, maxTurns, and background have no forced default and no
suggestion — genuinely free-form operational flags with no mechanical
default; omit each from frontmatter entirely unless the user passed it.
Step 6 — Check for Existing File
Glob $PLUGIN/agents/<name>.md.
If the file exists:
- Read its
descriptionfrontmatter field - Emit:
$PLUGIN/agents/<name>.md already exists (description: <existing-description>) - Ask:
Overwrite? (yes/no) - On
no: emitCancelled. Existing agent: $PLUGIN/agents/<name>.md — <existing-description>and stop with no changes - On
yes: continue
Step 7 — Check Scope Overlap (Review Agents Only)
For review agents, scan existing agents for topical overlap:
-
Read
descriptionfrontmatter of all files in$PLUGIN/agents/ -
For each existing agent, also read the first 20 lines of its
## Detectsection if present -
If the LLM judges ≥ 60% topical overlap between the new description and an existing agent's scope, emit:
Possible overlap with <agent-name>: <one-sentence description of shared concept>. Continue anyway? (yes/no) -
On
no: stop with no changes -
On
yes: continue -
This check is advisory — the user can always continue
For team agents: compare descriptions only (no ## Detect scan).
Step 8 — Handle Plugin-Unsupported Fields
If the user has requested hooks, mcpServers, or permissionMode, emit:
hooks/mcpServers/permissionMode are silently ignored for plugin agents — move the file to .claude/agents/ if you need them to take effect
Then ask: Include anyway? (yes/no)
- On
no: omit the field from generated frontmatter - On
yes: include the field as requested
Do not emit this warning for fields the user did not request.
Step 9 — Generate Frontmatter
Emit only official fields with non-empty values. Use this structure:
---
name: <name>
description: <description>
tools: <comma-separated tool list>
model: <alias|full-id|inherit>
effort: <level>
[memory: <user|project|local>]
[isolation: worktree]
[color: <color>]
[maxTurns: <int>]
[background: <true|false>]
[skills: [<name>, ...]]
[any additional fields the user requested and confirmed]
---
Emit each bracketed optional field only when the user passed the corresponding flag in Step 1 — there is no forced default for any of them.
Do not include hooks, mcpServers, or permissionMode unless the user
confirmed their inclusion in Step 8.
Cites: (citation drift defense)
When a review agent inlines normative numeric thresholds (e.g. "functions
MUST be under 50 lines", "coverage SHOULD reach 80%") that are owned by a
canonical skill or knowledge file, declare those sources with a body-level
Cites: list — not frontmatter: cites is not part of the official
Claude Code sub-agent contract (agent-contract.json), so it lives in the
generated body, near the top, alongside Context needs::
Cites: [complexity, object-calisthenics] # skill names or knowledge file stems
Each entry resolves to $PLUGIN/skills/<name>/SKILL.md or $PLUGIN/knowledge/<name>.md.
The citation lint flags any threshold the agent states on an RFC-2119 line
that is absent from every cited source. The lint is advisory (Phase 1,
non-blocking) either way.
Pre-write check. After Step 10 generates the body, before Step 11 writes the file:
-
Scan the generated body for threshold-bearing RFC-2119 lines — any line carrying
MUST|SHOULD|SHALL|REQUIRED|NEVER|ALWAYSAND a numeric token (\d+(\.\d+)?%?), outside code fences and blockquotes. -
If any are found AND no
Cites:line was set, emit exactly:⚠ Agent body states N numeric threshold(s) on RFC-2119 lines but no Cites: was declared. Eval drift defense will be blind on this agent. (a) add Cites: (b) proceed without -
On
(a): prompt for a comma-separated list, validate each entry resolves to a real$PLUGIN/skills/<name>/SKILL.mdor$PLUGIN/knowledge/<name>.md, insert aCites: [<list>]line into the body, and continue to Step 11. -
On
(b): continue to Step 11 with noCites:— the lint will flag the agent asadvisorygoing forward, which is the correct deferred state.
Omit the check entirely when the body states no thresholds; nothing for the lint to verify means the field is genuinely optional.
Step 10 — Generate Body
Review Agent Body Structure (required order)
If --context was provided, use it for the Context needs: field. Otherwise infer a sensible default from the description (simple detectors → diff-only; agents that need full file context → full-file; agents that need project structure → project-structure).
If --lang was provided, insert a language scope line immediately after the title: Scope: <exts> files only. Skip if no <exts> files are present.
# <Title Case Name>
[Scope: <exts> files only. Skip if no <exts> files are present.]
Output JSON:
```json
{"status": "pass|warn|fail|skip", "issues": [{"severity": "error|warning|suggestion", "confidence": "high|medium|none", "file": "", "line": 0, "message": "", "suggestedFix": ""}], "summary": ""}
Status: pass=, warn=, fail= Severity: error=, warning=, suggestion= Confidence: high=, medium=, none=
Context needs: <diff-only|full-file|project-structure>
Skip
Return {"status": "skip", ...} when:
Detect
:
Ignore
(handled by other agents)
### Team Agent Body Structure (required order)
```markdown
# <Title Case Name>
You are a <role description: worldview, characteristic approach, communication style>. <2–3 additional sentences covering how this agent thinks, what it prioritizes, and how it delivers output.>
## Output discipline
- Write <artifact type specific to this role> to files, not chat.
- No preamble. <Role-specific communication default.>
- End-of-turn: one sentence on <what this role reports at turn end>.
- For structured deliverables (<role-specific examples>), emit only the structure.
- Status updates: one paragraph max.
## Technical Responsibilities
- <action-oriented responsibility>
[## Skills] (optional — list skill name + one-line invocation context)
[## Behavioral Guidelines] (optional — decision-making autonomy, escalation, conflict)
Token-Efficiency Rules (both types)
Apply these rules when generating the body:
- No opener (review agents only): for review agents, no line may match
^You are an?(case-insensitive). Team agents MUST start with aYou are…persona paragraph — this rule does not apply to them. - No description restatement: title must not contain the
descriptionfield value verbatim (whitespace-normalized) - No placeholder text: body must not contain
your-agent-name,One-sentence description, or# Agent Name - Bullet length: no single bullet point may span more than two lines
- Knowledge file reference: one line only —
Read knowledge/X.md before starting— no prose explanation - Review Skip section: 1–3 bullet conditions, no prose explanation
- Review Ignore section: one sentence listing what other agents handle
- Skills section (team): skill name + one-line invocation context only
Line Budget Gate
After generating the body, count all lines (including blank lines).
Review agents: if line count > 40:
- Emit:
Body is N lines — X lines over the 40-line budget for review agents - List each removed/collapsed item, each prefixed with
-(dash space) - Emit:
Approve this trim? (yes/no) - On
yes: apply trim and continue - On
no: emitOptions: (a) reduce spec scope and regenerate, (b) accept N lines and proceed without trimmingand wait
Team agents: same gate with budget of 75 and label team agents.
Trimmable content (in priority order):
- Blank separator lines between sections (but not between bullets)
- Multi-line bullets collapsed to one line
- Wordy bullet text shortened to the essential action
Protected content (never trim):
- Output JSON block
- Section headings (
## Skip,## Detect,## Ignore,## Responsibilities) - The closing
---of any required section
Step 11 — Run /plugin-audit Validation Gate
/plugin-audit (structural compliance of the generated agent file) is the
validation gate of record — it is the tool that audits agent files. The gate is
blocking: an unresolved audit failure aborts creation (the cancel path
below), it never silently continues.
If --dry was passed: display the complete generated file content to the user and stop. Do not write any file, do not run validation, do not update the registry or CLAUDE.md.
Otherwise: write the generated content to disk, then invoke the plugin-audit skill:
Skill(plugin-audit $PLUGIN/agents/<name>.md)
If the audit returns errors:
- Emit the raw
/plugin-auditoutput verbatim - Emit:
All your inputs are preserved. - Emit:
(a) auto-correct and re-validate (b) cancel - On
(b): delete the file, make no changes, stop - On
(a): apply the minimal corrections, re-run/plugin-auditonce more- If the second run passes: continue to Step 12
- If the second run also fails: emit new
/plugin-auditoutput verbatim; emitAll your inputs are preserved.; emit(a) auto-correct and re-validate (b) cancelagain (no silent stop)
If the audit passes: continue to Step 12.
Step 12 — Present Draft and Confirm Write
Ask: Write this file to $PLUGIN/agents/<name>.md? (yes/no)
On no: delete the file written in Step 11, make no other changes, stop.
On yes: the file is already on disk from Step 11; no re-write needed unless the user modified the draft.
Step 13 — Update Agent Registry
If $PLUGIN/knowledge/agent-registry.md exists, locate the table whose heading
contains Review Agents (for review type) or Team Agents (for team type).
If the file does not exist: emit
$PLUGIN/knowledge/agent-registry.md not found — skip registry update.
and continue to Step 14.
If the file exists but the heading is not found: emit
Cannot update $PLUGIN/knowledge/agent-registry.md: heading containing '<type> Agents' not found. Update manually.
and stop without modifying the file.
Append a row matching that table's columns:
-
Review Agents (
| Agent | File | What It Checks |):| <name> | agents/<name>.md | <description> | -
Team Agents (
| Agent | File | ~Tokens | Primary Focus |):| <name> | agents/<name>.md | <~token-estimate> | <primary focus> |
The effort band is not mirrored in the registry — it lives only in the
agent's effort: frontmatter.
Step 14 — Update Plugin CLAUDE.md
If $PLUGIN/CLAUDE.md exists and has a prose Quick Reference list under
### Quick Reference:
- Review type → the line beginning
**Review agents** (<N>): - Team type → the line beginning
**Team agents** (<N>):
Edit that line in place: increment the parenthesised count (<N>) → (<N+1>)
and append , <name> to the comma-separated list.
If $PLUGIN/CLAUDE.md does not exist, or the Quick Reference section is not
present, emit:
$PLUGIN/CLAUDE.md Quick Reference list not found — skip CLAUDE.md update.
and continue.
If the file exists and the section is present but the matching line is not
found: emit
Cannot update $PLUGIN/CLAUDE.md: '<type> agents' Quick Reference line not found. Update manually.
and stop without modifying the file.
Confirm both updates (or skips) in the completion report.
Step 15 — Record the Model/Effort Decision (conditional)
Run this step only if the repo root contains docs/model-effort-decisions.md.
If that file does not exist, skip this step silently and omit its line from
the completion report.
Run:
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/append_model_effort_row.py" "$PLUGIN/agents/<name>.md" --repo-root <repo-root>
The script appends one keep row with the agent's model: and effort:
values, the count of evals/expected fixtures that name the agent, and the
matching reason. It skips an agent that is already listed or whose directory
has no rows in the log. Do not edit the row by hand. On a non-zero exit, show
the script's error output and stop.
Completion Report
Agent created: $PLUGIN/agents/<name>.md
Type: <review|team>
Model: <alias|full-id|inherit>
Effort: <level>
Body: <N> lines
Validation: PASS (/plugin-audit)
Registry updated: $PLUGIN/knowledge/agent-registry.md (<type> Agents table) [or: skipped — file not found]
CLAUDE.md updated: <type> agents Quick Reference list (count <N>→<N+1>) [or: skipped — section not found]
Decision log: <the script's output line> (only when docs/model-effort-decisions.md exists)
Agent Remove
Role: implementation. This skill removes an agent and all its references from the system — it does not modify agent behavior or content.
You have been invoked with the /agent-remove skill. Fully remove a named
agent and update all required documentation.
Implementation constraints
- Confirm before deleting. Always show the user what will be removed and wait for confirmation before any destructive action.
- Detect agent type first. Review agents (declare
Model tier:) and team agents (declare persona sections) require different cleanup paths. - Remove all references. An agent that is deleted but still referenced in other files leaves the system in an inconsistent state.
- Always update documentation. Documentation steps are mandatory. Review updated docs before reporting completion.
- Be concise. Report only what changed. No narration of each step.
Parse Arguments
Arguments: $ARGUMENTS
Required: agent name ($0) — the filename stem without .md
(e.g., js-fp-review, security-engineer)
Optional:
--plugin <dir>: target plugin directory. Resolved as: this flag if given; else singleplugins/*/; else cwd ancestor with.claude-plugin/plugin.json; else ask. Stored as$PLUGIN.--dry: Show what would be removed without making changes
Steps
0. Resolve target plugin
Determine $PLUGIN using the convention above. Read
$PLUGIN/.claude-plugin/plugin.json and extract name as $NAME.
1. Locate agent file
Verify $PLUGIN/agents/<name>.md exists. If not, list all agent files
and report that the named agent was not found.
2. Detect agent type
Read $PLUGIN/agents/<name>.md:
- If it declares
Model tier:→ review agent - Otherwise → team agent
3. Show removal plan
Display a confirmation prompt listing every action that will be taken:
Remove agent: <name> (<type>) from $PLUGIN
Files to delete:
- $PLUGIN/agents/<name>.md
[review agents only — if eval fixtures exist at repo root]
- evals/$NAME/fixtures/<name>-* (if any)
- evals/$NAME/expected/<name>-* (if any)
Registry entries to remove:
- $PLUGIN/knowledge/agent-registry.md: <table row> (if file exists)
- $PLUGIN/CLAUDE.md: Quick Reference list entry (if section exists)
[team agents only — if plugin maintains team-structure docs]
- $PLUGIN/docs/team-structure.md: <diagram node and edges> (if file exists)
Documentation to update:
- $PLUGIN/docs/agent_info.md: remove table row (if file exists)
[team agents only]
- $PLUGIN/agents/orchestrator.md: Tier guidance bullet (if listed)
- Other agent files in $PLUGIN/agents/ referencing <name>
Proceed? (yes to continue)
If --dry was passed, display the plan and stop without waiting for
confirmation.
4. Remove agent file
git rm $PLUGIN/agents/<name>.md
If not in a git repository, use rm.
5. Clean up eval artifacts (review agents only)
Search for and remove matching eval fixtures and expected files at the repo
root under evals/$NAME/:
ls evals/$NAME/fixtures/ | grep <name>
ls evals/$NAME/expected/ | grep <name>
Remove each matching file with git rm (or rm if not in git). If the
evals/$NAME/ directory does not exist, skip this step silently.
6. Update agent registry
If $PLUGIN/knowledge/agent-registry.md exists, remove the agent's row
from the appropriate table (Team Agents or Review Agents). If the file
does not exist, skip this step.
7. Update plugin CLAUDE.md
If $PLUGIN/CLAUDE.md exists:
- Remove the agent from the Quick Reference list (decrement the count and remove the name from the comma-separated list)
- Remove from the Skills Registry table if listed
If the file does not exist, skip this step.
8. Update orchestrator agent (team agents only)
If $PLUGIN/agents/orchestrator.md exists:
- Remove the agent name from any "Tier guidance (informational)" bullet list
- Remove from any Inline Review Checkpoint table if listed
If the file does not exist, skip this step.
9. Update cross-references in other agent files
Search for references to the removed agent:
grep -r "<name>" $PLUGIN/agents/ --include="*.md" -l
For each file found, remove or update:
- Collaboration protocol entries that name the removed agent
- Skills section references (if a team agent was referenced as a skill)
10. Update docs/agent_info.md (if it exists)
If $PLUGIN/docs/agent_info.md exists:
- Remove the agent's row from the Team Agents or Review Agents table
- If removing a team agent, remove any "Primary Collaborators" references in prose sections
If the file does not exist, skip this step.
11. Update team-structure docs (team agents only, if they exist)
If $PLUGIN/docs/team-structure.md exists, remove the agent node and all
its edges from any Mermaid diagrams in that file. If the file does not
exist, skip this step.
12. Review documentation
Review all modified documentation files for accuracy and consistency before reporting completion. Specifically check:
- No dangling references to the removed agent remain in any doc
- Tables are consistent across CLAUDE.md and docs/
- Any Mermaid diagrams render correctly (no orphaned edges)
13. Report
Agent removed: <name> (<type>) from $PLUGIN
Deleted:
- $PLUGIN/agents/<name>.md
[+ eval files if any]
Updated:
- $PLUGIN/knowledge/agent-registry.md [or: skipped — file not found]
- $PLUGIN/CLAUDE.md [or: skipped — file not found]
[+ orchestrator.md, team-structure.md, cross-references as applicable]
Documentation is consistent.
Agent & Skill Authoring
Overview
This skill defines the philosophy of the agent-vs-skill split and the conventions for writing skills. Agents own orchestration logic (when and why); skills own execution knowledge (how). This separation keeps agents readable as workflow definitions while keeping capabilities DRY across the team.
Scope boundary:
- This skill — skill creation, shared philosophy, anti-patterns, documentation sync policy
agent-createskill — the procedural workflow for generating a new agent file (invoked by/agent-add)
If you are creating an agent file, use /agent-add (which invokes the agent-create skill). This skill no longer duplicates that procedure.
Constraints
- Skills must be agent-agnostic; no persona or behavioral logic in skill files
- Execution details belong in skills; orchestration logic belongs in agents
- Every new agent or skill must be registered (see
references/templates.md) - Do not embed a skill's knowledge inline in an agent — reference the skill file
Core Pattern
Agent (when + why) Skill (how)
┌─────────────────┐ ┌─────────────────┐
│ ## Skills │ │ # Skill Name │
│ - Skill A ──────│───────>│ │
│ "Invoke when │ │ ## Concepts │
│ designing │ │ ## Patterns │
│ bounded │ │ ## Guidelines │
│ contexts" │ │ ## Structure │
│ │ │ │
│ ## Behavioral │ │ (reusable by │
│ Guidelines │ │ any agent) │
│ (orchestration) │ │ │
└─────────────────┘ └─────────────────┘
- Agents define the role: persona, behavior, collaboration style, and when/why to use each skill
- Skills define the capability: concepts, patterns, guidelines, and project structures
- An agent references a skill and annotates it with invocation context
- Multiple agents can share the same skill, each with different invocation context
Creating an Agent
Run /agent-add — it invokes the agent-create skill, which is the canonical procedure: name validation, type detection, scope-overlap check, body generation within token-efficiency budgets, /plugin-audit validation gate, and registry/CLAUDE.md updates.
Do not hand-author agent files when /agent-add is available — divergent templates produced manually have historically drifted from the schema enforced by /plugin-audit.
Creating a Skill
Resolve the target plugin directory ($PLUGIN) using the same convention as
agent-create: --plugin <dir> argument; else single plugins/*/; else cwd
ancestor with .claude-plugin/plugin.json; else ask.
Place skill files at $PLUGIN/skills/{skill-name}/SKILL.md. Use the skill template and authoring guidelines from references/templates.md. Then follow the registration checklist.
Meta-Patterns for Skill Writing
Before writing a new skill, read 2-3 existing skills in $PLUGIN/skills/ to absorb the project's voice and structure. Skills that follow existing patterns integrate better.
Explain the why, not just the what. LLMs follow rules more reliably when they understand the reasoning. "Do X because Y happens without it" beats "ALWAYS do X." Compare:
- Weak: "ALWAYS run tests before claiming done"
- Strong: "Run tests before claiming done — LLMs confidently claim 'done' without verification, and this is the single most common failure mode"
Include rationalization prevention. LLMs generate plausible excuses to skip hard steps. Add an "Excuses vs. Reality" table that pre-empts the common rationalizations for the skill's domain. This is the most effective compliance pattern in this project.
Use hard gates, not soft suggestions. "Should" is ignored; "must, with evidence" is followed. Gate pattern: require tool output (paste the result) as proof that a step was completed. Without evidence, the agent cannot proceed.
Constrain scope explicitly. Skills that try to cover everything get applied inconsistently. Define clear boundaries: what this skill covers, what it doesn't, and what adjacent skills handle the rest.
Test against the forgetting curve. Skills are most likely to be skipped when the agent is deep in implementation and eager to deliver. Front-load the most critical constraints in the skill's ## Constraints section — they're read first and remembered longest.
Apply TDD to skill-writing itself.
- RED: Run the task scenario WITHOUT the skill. Observe how the agent naturally fails.
- GREEN: Write the minimal skill that addresses those specific failures.
- REFACTOR: Capture the verbatim excuses the agent generated during baseline testing and build explicit counters into a rationalization prevention table.
Optimize skill descriptions for triggering. The description field in frontmatter determines whether the skill gets invoked. Descriptions that summarize the workflow cause the agent to follow the description instead of reading the full skill. Descriptions should contain triggering conditions only — when should I use this? — not workflow summaries.
Registration
After creating an agent or skill, follow the registration checklist in references/templates.md. For agents, /agent-add performs registration automatically; for skills and slash commands, follow the manual steps. Incomplete registration leaves the system in an inconsistent state.
Documentation Sync Policy
Every change must be reflected in documentation. See the sync policy and source-of-truth table in references/templates.md.
Output
New or updated $PLUGIN/skills/*/SKILL.md file(s) with all registry tables and docs updated. Be concise — confirm what was created/updated and its registration status.
Anti-Patterns
| Anti-Pattern | Problem | Fix |
|---|---|---|
| Skill logic embedded in agent | Duplicated across agents, hard to update | Extract to a skill file, reference from agent |
| Agent behavior embedded in skill | Skill becomes role-specific, can't be reused | Move persona/judgment logic to the agent |
| Skill without any agent reference | Orphaned knowledge, never invoked | Add to relevant agents or remove |
| Agent without Skills section | All knowledge is inline, nothing is reusable | Identify extractable capabilities |
| Overly broad skill | Tries to cover too much, hard to reference precisely | Split into focused skills |
| Hand-authoring an agent file | Drifts from the schema enforced by /plugin-audit | Use /agent-add (invokes the agent-create skill) |
| Deferred tool called before its schema loads | Assumed shape (e.g. batched TaskCreate) fails with InputValidationError | Call ToolSearch("select:<ToolName>") first; state the real per-call contract |
Agent Type Advisor
Role: worker. Recommend markdown vs script for a plugin capability, citing the shared decision rules so the recommendation is auditable, not a vibe.
Constraints
- Cite, do not paraphrase. Every recommendation names at least two rule IDs
(
R1–R10) fromknowledge/agent-type-decision-rules.md. That file is the single source of truth — read it first, do not restate its reasoning from memory. - Classify the input mode first. Prose → forward-looking. File path → retrospective. Both modes are first-class.
- Behavior decides type, not extension. Judge an existing file by what its
body actually does, never by its
.md/.shsuffix alone. - Be concise. Emit only the recommendation block. No preamble.
Step 1 — Read the rules
Read knowledge/agent-type-decision-rules.md in full. It is short and is the
rule source (R1–R10, the markdown/script columns, and the confidence ladder).
Step 2 — Detect input mode
Inspect $ARGUMENTS:
- If it resolves to an existing file (ends in
.md/.sh/.pyand exists on disk, or Glob finds it) → retrospective mode (Step 3b). - Otherwise treat the whole argument as a prose use-case → forward-looking mode (Step 3a).
If $ARGUMENTS is empty, ask the user for a prose use-case or a file path and
stop.
Step 3a — Forward-looking (prose use-case)
- Extract the unit's job: what does it produce, how often does it run, does it gate anything, does the answer vary with phrasing/context?
- Walk the rules. Collect every rule that applies and the column it points to.
- Decide
markdownorscriptby the dominant column. - Set confidence per the file's ladder (high / medium / low).
Output the recommendation block (Step 4) with recommendation: = markdown or
script.
Step 3b — Retrospective (existing file)
- Read the target file. Determine its observable behavior from the body — what it actually computes or produces — independent of its extension.
- Determine the type it should be by the same rule walk as Step 3a.
- Compare to the type it currently is (markdown unit =
.mdagent/SKILL.md; script =.sh/.py):- should-be matches current →
recommendation: KEEP - should-be differs from current →
recommendation: CHANGE(name the target type and what to extract/convert) - mixed mechanical + judgment → apply R10: if the markdown unit already
delegates the mechanical half to a script it calls,
KEEP; if it inlines mechanical enumeration,CHANGE(extract the script).
- should-be matches current →
- Set confidence per the ladder.
Step 4 — Output
Emit exactly this block (Markdown), nothing else:
## Agent Type Recommendation
- Target: <prose summary | file path>
- Mode: <forward-looking | retrospective>
- Recommendation: <markdown | script | KEEP | CHANGE>
[retrospective only] Current type: <markdown | script> → Should be: <markdown | script>
- Confidence: <high | medium | low>
- Rationale: <2–3 sentences keyed to the job>
- Rules cited:
- <Rn>: <one-line why this rule applies here>
- <Rm>: <one-line why this rule applies here>
[low/medium confidence only]
- To raise confidence: <the missing detail>
At least two distinct rule IDs are required. For a CHANGE, cite the rule(s)
that the current type violates and the rule(s) that justify the target type.
Init Plugin Eval
Role: implementation. Create the eval scaffold so a plugin's review agents and advisory skills can be graded — without shipping any of it inside the plugin.
Constraints
- Evals never ship. The eval tree lives at the repo root under
evals/<plugin>/, never underplugins/<plugin>/. Build/test tooling inside a plugin dir is a shipping bug. - Stub, don't fake. Scaffold empty
fixtures/andexpected/dirs and a README. Do not invent fixtures — an empty scaffold must grade as "no fixtures", a clean no-op, not an error. - Never overwrite. If
evals/<plugin>/exists, report and stop.
Step 1 — Parse
NAME=$0(the plugin name, matching itsplugin.jsonname).DIR=--dirvalue, elseevals/<NAME>.- If
DIRexists → report and stop.
Step 2 — Create the structure
mkdir -p "$DIR/fixtures" "$DIR/expected"
for d in fixtures expected; do : > "$DIR/$d/.gitkeep"; done
fixtures/— input artifacts an agent/skill runs against (sample agent files, plugin dirs, prose use-cases).expected/— one<fixture-stem>.jsonper fixture declaring the expected grading (which agent/skill it targets and the pass condition).
Step 3 — Write the grading-contract README
$DIR/README.md documents the contract a grader enforces:
# Eval corpus — <NAME>
Fixtures (`fixtures/`) and their expected gradings (`expected/*.json`) for the
<NAME> plugin's review agents and advisory skills.
## Grading contract
Each `expected/<stem>.json` pairs with a `fixtures/<stem>.*` input and declares:
- `fixture` — the fixture file/dir this grades.
- `description` — what the fixture exercises.
- `applicableAgents` / `applicableSkills` — the unit(s) under test.
- For a **review agent**: `expectedStatus` (`pass|warn|fail|skip`),
`issueCount` ({min,max}), and `severities` bounds.
- For an **advisory skill**: the expected `recommendation`/fields and the
rule citations or gates the output must contain.
A grader pairs every `expected/*.json` with a fixture and checks the actual
output falls within the declared bounds. An **empty corpus grades as
"no fixtures"** — a clean no-op, never an error.
Step 4 — Verify the empty scaffold is a clean no-op
Confirm the scaffold grades as "no fixtures", not an error:
expected/contains only.gitkeep(no*.json) → a corpus check finds nothing to grade and reports "no fixtures".- If a project-level eval runner exists (e.g.
scripts/eval_grade.py --check-corpus), run it scoped toevals/<NAME>/and confirm exit 0 with a "no fixtures" / "nothing to grade" message.
Completion report
Eval scaffold created: <DIR>
Dirs: fixtures/ expected/
Docs: README.md (grading contract)
State: no fixtures yet → grades as a clean no-op
Next: add a fixtures/<stem>.* input and an expected/<stem>.json grading
Plugin Audit
Role: orchestrator. Mechanical, deterministic structural compliance — pattern
matching against the plugin contract. This is the generalized successor to
dev-team's internal agent-audit, scoped to architectural decisions only.
Scope boundary
| In scope (this skill) | Out of scope |
|---|---|
| Agent type appropriateness (markdown vs script) | Detection-logic quality (→ the plugin's own agent-eval) |
| Frontmatter compliance | Shipping hygiene / ${CLAUDE_PLUGIN_ROOT} ref resolution |
| Eval coverage presence | Shell portability (bash 3.2 / BSD / Git Bash) |
| Body line-count budgets | Catalog/version sync (→ release-please config) |
Architecture only. Do not evaluate whether a detector is good — only whether the unit is the right type, well-formed, covered, and within budget.
Orchestrator constraints
- Check structure, not semantics. Verify fields/sections/patterns exist and the type matches the job. Never grade detection rules.
- Deterministic checks only. Every check is reproducible — does the field exist? Is the format correct? Is the body within budget?
- Generalized. Resolve every path from the target plugin dir. Never assume
plugins/dev-team, anagent-registry.md, or a.claude/docs/eval-system.md. --fixapplies minimal structural fixes (insert missing sections/fields from templates). Never rewrite existing content.- Be concise. Output the report table and action items only.
Step 1 — Resolve target plugin
Parse $ARGUMENTS:
- A directory path → audit that plugin.
- No path → if exactly one
plugins/*/exists, use it; if several, list them and ask which to audit; if the cwd is itself a plugin dir (.claude-plugin/plugin.jsonpresent), use it. --fix→ after the report, apply fixes for FAIL/WARN items.
Let PLUGIN = the resolved dir, NAME = its .claude-plugin/plugin.json name.
Eval fixtures are expected at the repo-root sibling evals/<NAME>/ (never shipped
inside PLUGIN); accept evals/<NAME>/fixtures/ or flat evals/<NAME>/ layouts.
Step 2 — Audit agents ($PLUGIN/agents/*.md)
For every agent file:
- Frontmatter compliance — the native Claude Code sub-agent contract is
the only source of truth:
nameanddescriptionare the sole required fields. Runpython3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_agent_contract.py <file>and fold everyerrorinto FAIL and everywarninginto WARN in this table — this covers required-field presence,namepattern, enum membership on any field present (model,effort,permissionMode,memory,isolation,color,background,maxTurns), unknown-key warnings, and the plugin-ignored-field warning (hooks/mcpServers/permissionModeare inert for plugin-supplied agents). There is no separate hand-rolledeffortcheck — a plugin's own convention (e.g. dev-team'seffort: highon every agent) is that plugin's local preference, not a requirement this generalized gate enforces. - No colon in
description— the value must not contain:(breaks argument-hints). FAIL on a colon. - Skills–Skill invariant — if the body has a
## Skillsheading,tools:must includeSkill. FAIL otherwise. - Agent type appropriateness — read
${CLAUDE_PLUGIN_ROOT}/knowledge/agent-type-decision-rules.mdand classify the file by its observable behavior (the same R1–R10 walk as/agent-type-advisor's retrospective mode). ACHANGEverdict is a WARN with the cited rule IDs; aKEEPis PASS. (For a deeper, dispatched review, the user can run theplugin-best-practices-reviewagent separately.) - Review-agent shape — a body containing the JSON status schema
(
"status": "pass|warn|fail|skip") must declare the output schema (status,issues,summary), severity definitions, a## Skipsection, andContext needs:. WARN on any missing. - Body line-count — count body lines (after frontmatter). Review agents
(JSON-output) over 40 → WARN; team agents (persona
You are…body) over 75 → WARN.
Step 3 — Audit skills ($PLUGIN/skills/*/SKILL.md)
- Frontmatter —
name,description(no colon), androlepresent. FAIL on missingname/description; WARN on missingrole. - Structured steps — the body has an ordered procedure (numbered
##/###steps or a## Stepssection). FAIL if absent. - Arguments documented — a user-invocable skill (
user-invocable: true) declares its arguments (argument-hintor an arguments section). WARN if missing. - Conciseness directive — the skill instructs concise output somewhere ("Be concise" / "no preamble" / output-only). WARN if absent.
Step 4 — Eval coverage
For every review agent found in Step 2, check that at least one fixture
references it under evals/<NAME>/. WARN (not FAIL) when a review agent has no
fixture — eval authoring is a follow-up, but the gap must be visible.
Step 5 — Report
# Plugin Audit — <NAME> (<PLUGIN>)
## Agents
| Agent | Frontmatter | No-Colon Desc | Skills-Tool | Type | Review Shape | Body Budget | Status |
| --- | --- | --- | --- | --- | --- | --- | --- |
## Skills
| Skill | Frontmatter | Steps | Arguments | Concise | Status |
| --- | --- | --- | --- | --- | --- |
## Eval coverage
| Review agent | Fixture under evals/<NAME>/ | Status |
| --- | --- | --- |
## Summary
- Agents: N OK, N WARN, N FAIL
- Skills: N OK, N WARN, N FAIL
- Eval coverage: N covered, N gaps
- Action items: <list>
A clean plugin reports zero findings (every cell PASS / N/A). That is the bar
/scaffold-plugin output and a migrated skill must clear.
Step 6 — Apply fixes (only when --fix is passed)
Without --fix, list action items and stop. With --fix, apply minimal
structural fixes and re-verify each:
- Missing review-agent output schema → insert the JSON block after the H1.
- Missing
## Skip→ insert the skip stub before## Detect. - Colon in
description→ rewrite the value to remove colons (use–/and). ## SkillswithoutSkillin tools → append, Skillto thetools:line.
After each fix: re-read the file, re-run the specific check, report
FIXED: <unit> — <what>. Type mismatches (Step 2.4) are never auto-fixed —
converting markdown↔script is a human decision; report them as action items.
Scaffold Marketplace
Role: implementation. Lay down the marketplace catalog and the release wiring that keeps it in sync, then seed at least one plugin slot.
Constraints
- Catalog format is fixed.
.claude-plugin/marketplace.jsonmust match the structure indocs/marketplace-builder-plugin-playbook.md§2.1 —name,owner, and aplugins[]array ofgit-subdirsource entries. - At least one plugin slot. A marketplace with no plugins is not done;
scaffold a first plugin entry (via
--first-pluginor a placeholder slot). - Versioning is automated, never hand-edited. Every catalog entry's
versionandsource.refare owned by release-pleaseextra-files. Do not ask the user to maintain them by hand. - Never overwrite an existing catalog. If
.claude-plugin/marketplace.jsonexists, report and stop (offer/scaffold-pluginto add a plugin instead).
Step 1 — Parse
OWNER=$0(the marketplacename/ owner handle).FIRST=--first-pluginvalue, elseexample-plugin(a placeholder slot the user renames).- If
.claude-plugin/marketplace.jsonexists → stop.
Step 2 — Write the catalog
.claude-plugin/marketplace.json:
{
"metadata": { "description": "<one-line marketplace description>" },
"name": "<OWNER>",
"owner": { "name": "<OWNER full name>" },
"plugins": [
{
"author": { "name": "<OWNER full name>" },
"description": "<FIRST plugin description>",
"homepage": "https://github.com/<org>/<repo>",
"license": "MIT",
"name": "<FIRST>",
"repository": "https://github.com/<org>/<repo>",
"source": {
"path": "plugins/<FIRST>",
"ref": "<FIRST>-v0.1.0",
"source": "git-subdir",
"url": "https://github.com/<org>/<repo>.git"
},
"version": "0.1.0"
}
]
}
Each entry's version and source.ref stay in lock-step with the plugin's own
plugin.json and its release tag — wired in Step 4, never hand-edited.
Step 3 — Scaffold the first plugin
Invoke /scaffold-plugin <FIRST> to create plugins/<FIRST>/ with its required
files and dirs. (If the user passed no --first-plugin, scaffold the placeholder
and tell them to rename it.)
Step 4 — Wire release automation
.release-please-manifest.json — one entry per plugin at its current version:
{ "plugins/<FIRST>": "0.1.0" }
release-please-config.json — include-v-in-tag + include-component-in-tag
true, and one packages entry per plugin. Each plugin versions independently
(its own component, tag prefix, and manifest entry); extra-files rewrite the
catalog on release so plugin.json, the tag, and marketplace.json never drift:
"plugins/<FIRST>": {
"release-type": "simple",
"package-name": "<FIRST>",
"component": "<FIRST>",
"extra-files": [
".claude-plugin/plugin.json",
{ "type": "json", "path": "/.claude-plugin/marketplace.json",
"jsonpath": "$.plugins[?(@.name=='<FIRST>')].version" },
{ "type": "json", "path": "/.claude-plugin/marketplace.json",
"jsonpath": "$.plugins[?(@.name=='<FIRST>')].source.ref" }
]
}
feat: → minor, fix: → patch, feat!:/BREAKING CHANGE → major. A commit is
attributed to a plugin by the path it touches; keep commits plugin-scoped for
independent bumps.
Step 5 — Verify
jq . .claude-plugin/marketplace.jsonparses and has ≥1plugins[]entry.- Each catalog
namehas aplugins/<name>/dir, a manifest entry, and a release-please package. - Run
/plugin-audit plugins/<FIRST>→ zero findings.
Completion report
Marketplace scaffolded: <OWNER>
Catalog: .claude-plugin/marketplace.json (1 plugin slot: <FIRST>)
Release: release-please-config.json + .release-please-manifest.json
Plugin: plugins/<FIRST>/ (/plugin-audit → zero findings)
Next: add more plugins with /scaffold-plugin <name>
Scaffold Plugin
Role: implementation. Emit the shipped-plugin skeleton, then prove it clean.
Constraints
- Name is a hard gate.
<plugin-name>must match^[a-z][a-z0-9-]*$. On a mismatch, emit the rule and a kebab-case suggestion, then stop. - Never overwrite. If the target dir already exists, report and stop.
- Only shipped files go under
plugins/<name>/. Tests, eval fixtures, and build tooling live at the repo root — never scaffold them inside the plugin. - End on a green audit. The deliverable is not the files; it is
/plugin-audit plugins/<name>reporting zero findings.
Step 1 — Parse and validate
NAME=$0; validate against^[a-z][a-z0-9-]*$(Step constraint 1).DIR=--dirvalue, elseplugins/<NAME>.DESC=--descriptionvalue, else a one-line placeholder the user edits.- If
DIRexists → report and stop.
Step 2 — Create the directory skeleton
mkdir -p "$DIR"/.claude-plugin "$DIR"/agents "$DIR"/skills "$DIR"/hooks "$DIR"/knowledge
agents/, skills/, hooks/, and knowledge/ start empty. Git does not track
empty directories — add a .gitkeep to each so the skeleton survives commit:
for d in agents skills hooks knowledge; do : > "$DIR/$d/.gitkeep"; done
Step 3 — Write the required files
$DIR/.claude-plugin/plugin.json — version starts at 0.1.0; release-please
keeps it in sync thereafter (do not hand-bump):
{
"name": "<NAME>",
"version": "0.1.0",
"description": "<DESC>",
"author": { "name": "", "email": "" }
}
$DIR/CLAUDE.md — plugin instructions that ship with the plugin: a one-line
purpose, a table of the plugin's /commands (empty to start), and the
conventions it enforces. Keep it small (it is always loaded).
$DIR/install.sh — the prerequisite checker with the Git-Bash-on-Windows
guard. Copy the canonical pattern from ${CLAUDE_PLUGIN_ROOT}/install.sh
(checks claude + jq, warns on optional tools, detects Windows-without-Git-Bash
and points to https://git-scm.com/download/win), retitled for <NAME>. Then
chmod +x "$DIR/install.sh".
$DIR/settings.json — hook registrations (empty hooks to start) plus a
permissions block:
{
"permissions": {
"allow": ["Bash", "Edit", "Write", "Read", "Glob", "Grep", "Agent", "Skill", "mcp__*"],
"deny": ["Bash(rm *)", "Bash(git push *)"]
}
}
Step 4 — Register in the catalog (if a marketplace exists)
If .claude-plugin/marketplace.json exists at the repo root, add a plugin entry
(name, description, source.path: "<DIR>", source.source: "git-subdir",
source.ref, version: "0.1.0") and add the matching release-please package +
manifest entry — see /scaffold-marketplace Step 4 for the exact block. If no
catalog exists, note that the user can create one with /scaffold-marketplace.
Step 5 — Audit gate
Run /plugin-audit <DIR>. A fresh skeleton has no agents/skills, so the audit
must report zero findings. If it does not, fix the scaffold and re-run before
reporting success.
Completion report
Plugin scaffolded: <DIR>
Files: .claude-plugin/plugin.json, CLAUDE.md, install.sh, settings.json
Dirs: agents/ skills/ hooks/ knowledge/
Audit: /plugin-audit <DIR> → zero findings
Next: add agents with /agent-add, skills by hand or /agent-skill-authoring,
eval fixtures with /init-plugin-eval <NAME>
Agents 1
Plugin Best Practices Review
Cites: [agent-type-decision-rules]
Output JSON:
{"status": "pass|warn|fail|skip", "issues": [{"severity": "error|warning|suggestion", "confidence": "high|medium|none", "file": "", "line": 0, "message": "", "suggestedFix": ""}], "summary": ""}
Status: pass=clean, warn=missing eval coverage or over budget, fail=type mismatch or malformed frontmatter
Severity: error=breaks plugin contract, warning=structural drift, suggestion=tightening
Confidence: high=mechanical (field absent, line count); medium=type judgment with rule support; none=human judgment
Context needs: project-structure
Read knowledge/agent-type-decision-rules.md first — the rule source (R1–R10) for the type check; cite rule IDs in findings.
Skip
Return {"status": "skip", "issues": [], "summary": "Not a plugin directory"} when the target has no agents/ or skills/.
Detect
Agent type (markdown vs script):
- markdown unit with a purely mechanical body (R1–R5) → should be a script; a script whose job needs judgment (R6–R9) → should be markdown. Cite the governing rule IDs.
Frontmatter compliance:
- missing
name,description, orefforton an agent; a colon inside thedescriptionvalue; a## Skillsbody section withoutSkillintools.
Eval coverage:
- a review agent (JSON-output body) with no fixture under
evals/<plugin>/.
Body line-count:
- review-agent body over 40 lines; team-agent body over 75 lines.
Ignore
Detection-logic quality (the plugin's own agent-eval); shipping hygiene and portability (plugin-audit sibling checks).
Sponsors
Details
- Marketplace
- bdfinst/agentic-dev-team
- Source
- plugins/marketplace-dev
- Author
- Bryan Finster
- Category
- Community
- License
- MIT