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@bfinster

Run it inside Claude Code after adding the marketplace with /plugin marketplace add bdfinst/agentic-dev-team.

Contents

Discovered from source

Skills 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

  1. Always update settings.json. Installing without registering defeats the purpose — the whole point is reproducibility.
  2. Derive marketplace from the identifier. The name@marketplace format encodes both; never ask the user to repeat information already in the argument.
  3. Do not duplicate entries. Check settings.json before adding; if the plugin is already registered, report it and stop.
  4. 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 $0
  • MARKETPLACE — the part after @ in $0
  • REPO — 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

  1. Follow the official sub-agent schema and token budgets.
  2. Delegate the build to the agent-create skill; do not improvise structure.
  3. 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 → sets Context 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, or permissionMode without 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):

  1. If --plugin <dir> was passed, use that directory as $PLUGIN.
  2. Else if exactly one plugins/*/ directory exists in the repo root, use it.
  3. Else if the current working directory is inside a directory containing .claude-plugin/plugin.json, use that directory.
  4. 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):

InputRequiredNotes
nameyesfile stem of the new agent
typeyesreview or team
descriptionyesone-line summary for frontmatter
toolsnocomma-separated tool list
--plugin <dir>notarget plugin directory (resolved in Step 0)
--model sonnet|opus|haiku|fable|inherit|<full model ID>nomodel the agent runs on; a value is suggested and confirmed in Step 5 if omitted
--effort low|medium|high|xhigh|maxnoreasoning effort for this agent; a value is suggested and confirmed in Step 5 if omitted
--memory user|project|localnopersistent memory scope; omitted unless specified
--isolation worktreenorun in an isolated git worktree; omitted unless specified
--color red|blue|green|yellow|purple|orange|pink|cyannodisplay color in the task list/transcript; omitted unless specified
--max-turns <int>nocap on agentic turns before the subagent stops; omitted unless specified
--background true|falsenoalways run as a background task; omitted unless specified
--skills <name1,name2,...>noskill names to preload into context at startup; omitted unless specified
--context diff-only|full-file|project-structurenosets Context needs: field in review body
--lang <exts>noadds language scope line to review body (e.g. Scope: .ts, .tsx files only)
--drynodisplay 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:

  1. Emit: Name must match ^[a-z][a-z0-9-]*$ — use lowercase letters, digits, and hyphens only
  2. 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
  3. If a valid correction exists, emit: Did you mean: <corrected-name>?
  4. Stop immediately. Do not write any file.

Step 3 — Detect Agent Type

If type was not provided:

  • Scan description for keywords:
    • review, audit, check, validate, detect, scan, lint → infer review
    • engineer, architect, manager, writer, planner, designer, specialist → infer team
  • 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:

  1. If --model was not provided, suggest by type: review→haiku, team→sonnet. If --effort was not provided, suggest high for either type.
  2. Emit: Suggested model: <model>, effort: <effort> — accept? (yes/change)
  3. On yes: use the suggested values and continue.
  4. On change: ask Model? and/or Effort? for whichever the user wants to change, validate each against agent-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.

  1. If --color was not provided, compute the suggestion from the rule above using the tools resolved in Step 4/this step and the agent's name.
  2. Emit: Suggested color: <color> — accept? (yes/change).
  3. On yes: use the suggested value and continue.
  4. On change: ask Color?, 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):

  1. If the generated agent body includes a ## Skills section, list every skill name that section documents and emit: Suggested skills: [<name1>, <name2>, ...] — accept? (yes/change). On yes: use the listed names. On change: ask which names to add/remove; each must resolve to a real $PLUGIN/skills/<name>/SKILL.md (warn, don't fail, per the existing --skills validation rule). If the body has no ## Skills section, skip this prompt — omit skills: entirely.
  2. If the resolved tools: includes Edit or Write, emit: Suggested memory: project — accept? (yes/change). On yes: use project. On change: ask Memory scope? and validate against project — the fleet's memory test gate (test_every_file_mutating_agent_declares_memory_project) checks exact equality against project for every Edit/Write agent and has no escape valve, so --memory cannot be omitted or set to anything else here; on an invalid answer, restate that project is the only accepted value for a file-mutating agent and re-ask rather than aborting the whole flow. If tools: has neither Edit nor Write, skip this prompt — omit memory: 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:

  1. Read its description frontmatter field
  2. Emit: $PLUGIN/agents/<name>.md already exists (description: <existing-description>)
  3. Ask: Overwrite? (yes/no)
  4. On no: emit Cancelled. Existing agent: $PLUGIN/agents/<name>.md — <existing-description> and stop with no changes
  5. On yes: continue

Step 7 — Check Scope Overlap (Review Agents Only)

For review agents, scan existing agents for topical overlap:

  1. Read description frontmatter of all files in $PLUGIN/agents/

  2. For each existing agent, also read the first 20 lines of its ## Detect section if present

  3. 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)

  4. On no: stop with no changes

  5. On yes: continue

  6. 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:

  1. Scan the generated body for threshold-bearing RFC-2119 lines — any line carrying MUST|SHOULD|SHALL|REQUIRED|NEVER|ALWAYS AND a numeric token (\d+(\.\d+)?%?), outside code fences and blockquotes.

  2. 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
    
  3. On (a): prompt for a comma-separated list, validate each entry resolves to a real $PLUGIN/skills/<name>/SKILL.md or $PLUGIN/knowledge/<name>.md, insert a Cites: [<list>] line into the body, and continue to Step 11.

  4. On (b): continue to Step 11 with no Cites: — the lint will flag the agent as advisory going 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:

  1. No opener (review agents only): for review agents, no line may match ^You are an? (case-insensitive). Team agents MUST start with a You are… persona paragraph — this rule does not apply to them.
  2. No description restatement: title must not contain the description field value verbatim (whitespace-normalized)
  3. No placeholder text: body must not contain your-agent-name, One-sentence description, or # Agent Name
  4. Bullet length: no single bullet point may span more than two lines
  5. Knowledge file reference: one line only — Read knowledge/X.md before starting — no prose explanation
  6. Review Skip section: 1–3 bullet conditions, no prose explanation
  7. Review Ignore section: one sentence listing what other agents handle
  8. 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:

  1. Emit: Body is N lines — X lines over the 40-line budget for review agents
  2. List each removed/collapsed item, each prefixed with - (dash space)
  3. Emit: Approve this trim? (yes/no)
  4. On yes: apply trim and continue
  5. On no: emit Options: (a) reduce spec scope and regenerate, (b) accept N lines and proceed without trimming and 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:

  1. Emit the raw /plugin-audit output verbatim
  2. Emit: All your inputs are preserved.
  3. Emit: (a) auto-correct and re-validate (b) cancel
  4. On (b): delete the file, make no changes, stop
  5. On (a): apply the minimal corrections, re-run /plugin-audit once more
    • If the second run passes: continue to Step 12
    • If the second run also fails: emit new /plugin-audit output verbatim; emit All your inputs are preserved.; emit (a) auto-correct and re-validate (b) cancel again (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

  1. Confirm before deleting. Always show the user what will be removed and wait for confirmation before any destructive action.
  2. Detect agent type first. Review agents (declare Model tier:) and team agents (declare persona sections) require different cleanup paths.
  3. Remove all references. An agent that is deleted but still referenced in other files leaves the system in an inconsistent state.
  4. Always update documentation. Documentation steps are mandatory. Review updated docs before reporting completion.
  5. 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 single plugins/*/; 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-create skill — 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.

  1. RED: Run the task scenario WITHOUT the skill. Observe how the agent naturally fails.
  2. GREEN: Write the minimal skill that addresses those specific failures.
  3. 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-PatternProblemFix
Skill logic embedded in agentDuplicated across agents, hard to updateExtract to a skill file, reference from agent
Agent behavior embedded in skillSkill becomes role-specific, can't be reusedMove persona/judgment logic to the agent
Skill without any agent referenceOrphaned knowledge, never invokedAdd to relevant agents or remove
Agent without Skills sectionAll knowledge is inline, nothing is reusableIdentify extractable capabilities
Overly broad skillTries to cover too much, hard to reference preciselySplit into focused skills
Hand-authoring an agent fileDrifts from the schema enforced by /plugin-auditUse /agent-add (invokes the agent-create skill)
Deferred tool called before its schema loadsAssumed shape (e.g. batched TaskCreate) fails with InputValidationErrorCall 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

  1. Cite, do not paraphrase. Every recommendation names at least two rule IDs (R1–R10) from knowledge/agent-type-decision-rules.md. That file is the single source of truth — read it first, do not restate its reasoning from memory.
  2. Classify the input mode first. Prose → forward-looking. File path → retrospective. Both modes are first-class.
  3. Behavior decides type, not extension. Judge an existing file by what its body actually does, never by its .md/.sh suffix alone.
  4. 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/.py and 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)

  1. 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?
  2. Walk the rules. Collect every rule that applies and the column it points to.
  3. Decide markdown or script by the dominant column.
  4. 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)

  1. Read the target file. Determine its observable behavior from the body — what it actually computes or produces — independent of its extension.
  2. Determine the type it should be by the same rule walk as Step 3a.
  3. Compare to the type it currently is (markdown unit = .md agent/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).
  4. 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

  1. Evals never ship. The eval tree lives at the repo root under evals/<plugin>/, never under plugins/<plugin>/. Build/test tooling inside a plugin dir is a shipping bug.
  2. Stub, don't fake. Scaffold empty fixtures/ and expected/ dirs and a README. Do not invent fixtures — an empty scaffold must grade as "no fixtures", a clean no-op, not an error.
  3. Never overwrite. If evals/<plugin>/ exists, report and stop.

Step 1 — Parse

  • NAME = $0 (the plugin name, matching its plugin.json name).
  • DIR = --dir value, else evals/<NAME>.
  • If DIR exists → 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>.json per 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 to evals/<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 complianceShipping hygiene / ${CLAUDE_PLUGIN_ROOT} ref resolution
Eval coverage presenceShell portability (bash 3.2 / BSD / Git Bash)
Body line-count budgetsCatalog/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

  1. Check structure, not semantics. Verify fields/sections/patterns exist and the type matches the job. Never grade detection rules.
  2. Deterministic checks only. Every check is reproducible — does the field exist? Is the format correct? Is the body within budget?
  3. Generalized. Resolve every path from the target plugin dir. Never assume plugins/dev-team, an agent-registry.md, or a .claude/docs/eval-system.md.
  4. --fix applies minimal structural fixes (insert missing sections/fields from templates). Never rewrite existing content.
  5. 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.json present), 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:

  1. Frontmatter compliance — the native Claude Code sub-agent contract is the only source of truth: name and description are the sole required fields. Run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/validate_agent_contract.py <file> and fold every error into FAIL and every warning into WARN in this table — this covers required-field presence, name pattern, 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/ permissionMode are inert for plugin-supplied agents). There is no separate hand-rolled effort check — a plugin's own convention (e.g. dev-team's effort: high on every agent) is that plugin's local preference, not a requirement this generalized gate enforces.
  2. No colon in description — the value must not contain : (breaks argument-hints). FAIL on a colon.
  3. Skills–Skill invariant — if the body has a ## Skills heading, tools: must include Skill. FAIL otherwise.
  4. Agent type appropriateness — read ${CLAUDE_PLUGIN_ROOT}/knowledge/agent-type-decision-rules.md and classify the file by its observable behavior (the same R1–R10 walk as /agent-type-advisor's retrospective mode). A CHANGE verdict is a WARN with the cited rule IDs; a KEEP is PASS. (For a deeper, dispatched review, the user can run the plugin-best-practices-review agent separately.)
  5. 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 ## Skip section, and Context needs:. WARN on any missing.
  6. 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)

  1. Frontmatter — name, description (no colon), and role present. FAIL on missing name/description; WARN on missing role.
  2. Structured steps — the body has an ordered procedure (numbered ##/### steps or a ## Steps section). FAIL if absent.
  3. Arguments documented — a user-invocable skill (user-invocable: true) declares its arguments (argument-hint or an arguments section). WARN if missing.
  4. 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).
  • ## Skills without Skill in tools → append , Skill to the tools: 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

  1. Catalog format is fixed. .claude-plugin/marketplace.json must match the structure in docs/marketplace-builder-plugin-playbook.md §2.1 — name, owner, and a plugins[] array of git-subdir source entries.
  2. At least one plugin slot. A marketplace with no plugins is not done; scaffold a first plugin entry (via --first-plugin or a placeholder slot).
  3. Versioning is automated, never hand-edited. Every catalog entry's version and source.ref are owned by release-please extra-files. Do not ask the user to maintain them by hand.
  4. Never overwrite an existing catalog. If .claude-plugin/marketplace.json exists, report and stop (offer /scaffold-plugin to add a plugin instead).

Step 1 — Parse

  • OWNER = $0 (the marketplace name / owner handle).
  • FIRST = --first-plugin value, else example-plugin (a placeholder slot the user renames).
  • If .claude-plugin/marketplace.json exists → 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.json parses and has ≥1 plugins[] entry.
  • Each catalog name has a plugins/<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

  1. 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.
  2. Never overwrite. If the target dir already exists, report and stop.
  3. Only shipped files go under plugins/<name>/. Tests, eval fixtures, and build tooling live at the repo root — never scaffold them inside the plugin.
  4. 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 = --dir value, else plugins/<NAME>.
  • DESC = --description value, else a one-line placeholder the user edits.
  • If DIR exists → 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, or effort on an agent; a colon inside the description value; a ## Skills body section without Skill in tools.

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

More from bdfinst/agentic-dev-team

All 3