Claude Cursor Skill

toolkit-skill-author

Authors or extends a skill in mc-agent-toolkit. Gates for forbidden buckets and name collisions, applies CONTRIBUTING's extend-or-split rules, then edits a peer skill or hands off to Anthropic's skill-creator and walks the registration checklist.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download monte-carlo-data-mc-agent-toolkit-.claude_skills_toolkit-skill-author-f45839d.zip · 20 KB

Install

skills CLI npx skills add https://github.com/monte-carlo-data/mc-agent-toolkit/tree/main/.claude/skills/toolkit-skill-author
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install monte-carlo-data-mc-agent-toolkit@llmmart
Git git clone https://github.com/monte-carlo-data/mc-agent-toolkit.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole monte-carlo-data/mc-agent-toolkit collection as a plugin from our marketplace. Git is the plain clone.

README

toolkit-skill-author

A meta-skill for authoring or extending skills in mc-agent-toolkit. Run it from the repo root via /toolkit-skill-author. It interviews you, applies the extend-or-split rules from CONTRIBUTING.md, hands off to Anthropic's skill-creator for the actual SKILL.md generation, and walks the registration checklist that keeps the orchestration layer, /mc catalog, evals, and version manifest in sync.

This skill is for toolkit contributors, not end users of mc-agent-toolkit.

Why this exists

Adding a skill to mc-agent-toolkit is more than dropping a SKILL.md into skills/. A new skill must be:

  1. Justified against the extend-or-split decision rules so we don't grow a soup of overlapping skills.
  2. Named without colliding with existing skills (exact or near-match).
  3. Registered in the orchestration layer (signal-definitions, /mc catalog) so context detection can find it.
  4. Eval'd so activation is measurable.
  5. Symlinked into all six editor plugins (claude-code, cursor, codex, copilot, opencode, cortex-code).
  6. Versioned via scripts/bump-version.sh so the marketplace ships the change.

Doing all of that by hand is error-prone. This skill enforces the workflow and gates against the common mistakes (forbidden buckets, name collisions, skipping registration steps).

When to use it

Run /toolkit-skill-author when you want to:

  • Add a new skill to the toolkit.
  • Extend an existing skill with new capabilities, phrasings, or references.

Do not use it for:

  • Editing skill internals that aren't activation-surface changes (typo fixes, minor rewording). Just edit the file and run a patch bump.

Prerequisites

  • Run from the mc-agent-toolkit repo.
  • Anthropic's skill-creator plugin must be installed and enabled in the current session:
    /plugin install skill-creator@claude-plugins-official
    
    Restart the session after install. The skill aborts if skill-creator isn't available — the handoff is core to the workflow, and there is no manual fallback.
  • Clean working tree recommended (the skill stages changes but does not commit).

How it works

/toolkit-skill-author
  │
  ├── Pre-load: verify repo + skill-creator availability,
  │             dump CONTRIBUTING.md and existing skill peers
  │
  ├── Phase 0 — Parse intent + apply gates
  │     ├── Gate A: forbidden bucket (Agent-routing) → halt
  │     ├── Gate B: name collision (exact or token-overlap) → ask before proceeding
  │     └── Gate C: clear extend → fast-path to Phase 2a
  │
  ├── Phase 1 — Decision survey (4 questions, one at a time)
  │     bucket · MCP surface · purpose · example prompts
  │
  ├── Decision — apply 4-step test from decision-rules.md
  │     verdict: EXTEND <peer>  or  NEW SKILL
  │
  ├── Phase 2a — Extend                   Phase 2b — New skill
  │     hand off to skill-creator           extended survey + name proposal
  │     in IMPROVE_EXISTING mode            hand off to skill-creator NEW_SKILL
  │     run lint-skill.py                   run lint-skill.py
  │     partial registration checklist     full registration checklist
  │
  └── Shared — version bump
        propose patch/minor/major per CONTRIBUTING § Version bumping
        run scripts/bump-version.sh

What's in this directory

Path Purpose
SKILL.md The skill itself — the workflow router.
references/decision-rules.md Source-of-truth for the 4-step extend-or-split test. Linked from CONTRIBUTING.md.
references/handoff-preamble.md Template the skill passes to skill-creator so the generated SKILL.md matches toolkit conventions.
references/registration-checklist.md Post-handoff steps (signal-definitions, /mc catalog, evals, symlinks).
scripts/find-peers.sh Dumps name + description + when_to_use for every existing skill — the candidate set the decision tree reasons over.
scripts/check-prereqs.sh Pre-flight check used by the pre-load.
scripts/lint-skill.py Validates frontmatter (name, description ≤250 chars, prefix) after skill-creator returns.
scripts/tests/ Fixture tests for the helper scripts.
evals/ Activation evals for this skill.

Notes for SPEDD reviewers

  • The skill is read-only through Phase 1 — no files are touched until after the decision verdict is confirmed.
  • The skill never auto-commits. Every modification is staged for explicit review.
  • Forbidden-bucket and name-collision gates run before any survey questions, so a refusal is fast and unambiguous.
  • The four-step decision-rules test is documented in references/decision-rules.md and referenced by CONTRIBUTING.md. If the rule needs to change, update both.
  • lint-skill.py enforces the constraints from .claude/rules/skills.md (description length, name prefix). Failures block the registration checklist.
  • Version bumps go through scripts/bump-version.sh, which updates all six plugin manifests + changelogs in lockstep — no partial-bump risk.

Troubleshooting

Symptom Cause / fix
skill-creator plugin is required Install skill-creator@claude-plugins-official, enable it, restart the session.
CONTRIBUTING.md missing — run from repo root You're not at the repo root. cd to mc-agent-toolkit/.
Gate B fires unexpectedly on a name Token-overlap is intentional — pick a more distinct name, or switch to extend.
Lint ERROR after handoff Either fix manually or ask skill-creator to regenerate the offending field. The registration checklist will not proceed until lint is clean.

Skill manifest

toolkit-skill-author

Pre-load

!test -f CONTRIBUTING.md || (echo "CONTRIBUTING.md missing — run from repo root." && exit 1)

Verify skill-creator is callable in this session. Scan the available-skills list for a skill named skill-creator (bare or namespaced, e.g. skill-creator:skill-creator). If absent, abort with exactly this message:

skill-creator plugin is required. Run /plugin install skill-creator@claude-plugins-official, enable it, then restart this session and re-run /toolkit-skill-author.

Do not fall back to manually scaffolding SKILL.md — the handoff is core to the workflow.

Load authoritative context:

!cat CONTRIBUTING.md
!bash .claude/skills/toolkit-skill-author/scripts/find-peers.sh skills
  • @.claude/skills/toolkit-skill-author/references/decision-rules.md
  • @.claude/skills/toolkit-skill-author/references/handoff-preamble.md
  • @.claude/skills/toolkit-skill-author/references/registration-checklist.md

Phase 0 — Parse intent and apply gates

From the contributor's initial prompt, extract (without asking yet):

  • target_name — did they name a specific skill (e.g., "extend monitoring-advisor", "create a skill called foo-bar")?
  • action — extend, new, or unknown.
  • bucket — did they state a capability bucket?

Apply the gates below before any survey question. Each gate halts when it fires.

Gate A — Forbidden bucket

If bucket is Agent-routing (or a synonym like "agent routing", "routing skill"), refuse:

Agent-routing skills are owned by the toolkit core team per CONTRIBUTING § Capability buckets — not authored via /toolkit-skill-author. Halting.

Do not proceed. If bucket is unstated, this gate re-applies after Q1.

Gate B — Name collision (new-skill intent)

If action is new and target_name is given, lowercase both target_name and each existing skill directory name, then check:

  • Exact match (equal strings): refuse with "<target_name> already exists in skills/. Pick a different name, or switch to extend." Do not proceed.
  • Near match. Split both names on - into token lists. Fire if either (a) the two lists share any token, or (b) any token in one list is a substring of any token in the other list. Example: monitor-advisor ↔ monitoring-advisor fires via (a) shared advisor and (b) monitor ⊂ monitoring. When fired, surface the overlap and ask: "<target_name> overlaps with existing <existing>. Did you mean to extend <existing>, or proceed with a new name?" Wait for an answer before continuing.

Gate C — Fast-path for clear extend

If action is extend and target_name names an existing skill:

  • Re-check the bucket. If target_name is one of the agent-routing skills (context-detection, incident-response, proactive-monitoring), fire Gate A's refusal — those are owned by the core team and cannot be extended via /toolkit-skill-author either.
  • Otherwise: skip the Phase 1 survey, use the initial prompt as the extension description, and jump directly to Phase 2a — Extend. If the prompt is missing fields the handoff preamble needs (purpose, phrasings, output artifact), ask only for those specific fields — do not re-run the full Q1–Q4 survey.

Otherwise, continue to Phase 1. New-skill requests always run the decision tree — the gate against hidden collisions is the tree itself.

Phase 1 — Decision survey

Ask these four questions one at a time, waiting for each answer.

  1. Capability bucket. Trust / Incident Response / Monitoring / Prevent / Optimize / Setup. Agent-routing is not offered. If the contributor writes in Agent-routing, fire Gate A and halt.
  2. Primary MCP surface or data input. E.g. Monte Carlo GraphQL, BigQuery INFORMATION_SCHEMA, Sentry issues. One or two items.
  3. One-line purpose. Plain language — no pushy triggers.
  4. 2–3 example user prompts. Quote them literally.

Decision

Apply the 4-step test from decision-rules.md against the peers dumped by find-peers.sh. The dump shows every skill's name + description + when_to_use; reason directly about which skills could plausibly activate on the Q4 prompts.

Filter agent-routing skills out of the candidate set — contributors can't author those, so they can't be extension targets. Current list: context-detection, incident-response, proactive-monitoring. If the toolkit adds new routing skills, update both this list and Gate C's list to match.

Present the verdict:

  • EXTEND <peer> or NEW SKILL.
  • The step that decided, and why.
  • "Proceed with this verdict, or override?"

If the user overrides, capture their reason verbatim — it becomes part of the PR description per CONTRIBUTING.

Phase 2a — Extend

Invoke skill-creator via the Skill tool in improve-existing mode, passing the handoff preamble from references/handoff-preamble.md with MODE=IMPROVE_EXISTING, PEER_NAME=<peer>, and the survey answers (or the initial prompt for the fast-path case).

skill-creator runs its full loop; if the contributor wants a lighter-touch edit, they can tell it mid-flow to skip iteration.

When skill-creator returns:

!rm -rf skills/<peer>/evals/ skills/<peer>-workspace/
!python3 .claude/skills/toolkit-skill-author/scripts/lint-skill.py <peer>

Scratch-artifact cleanup removes skill-creator's iteration files (they drove the loop but aren't the repo's eval format). Lint surfaces any frontmatter violations.

Walk the partial checklist from references/registration-checklist.md via TodoWrite:

  • Signal-definitions update — only if phrasings shifted.
  • /mc catalog update — only if user-facing surface changed.
  • Eval entry update — only if activation surface expanded.

Continue to the shared version-bump step.

Phase 2b — New skill

Extended survey (one at a time)

  1. Output artifact — what the skill produces (file type, diff, notebook, text verdict).
  2. Persona / workflow — who invokes this and during what task.
  3. Disambiguation — how it differs from the nearest peer (by bucket), even if no peer forced a split.

Propose name

Suggest 2–3 kebab-case directory names. Short is better. Re-run Gate B against each candidate:

  • Exact match → drop the candidate.
  • Near match (token-overlap with any existing skill) → drop or explicitly flag.

Only present candidates that survive Gate B. Wait for the contributor to pick one. Before handoff, re-verify skills/<chosen>/ does not exist.

Note the two-level naming: the directory is skills/<chosen>/, but the name field inside the generated SKILL.md frontmatter should be monte-carlo-<chosen> — the canonical prefixed form. The handoff preamble passes both, and lint-skill.py verifies them after scaffold.

Handoff to skill-creator

Invoke via the Skill tool with the handoff preamble from references/handoff-preamble.md, MODE=NEW_SKILL, and all survey answers.

When skill-creator returns:

!rm -rf skills/<name>/evals/ skills/<name>-workspace/
!python3 .claude/skills/toolkit-skill-author/scripts/lint-skill.py <name>

If lint prints ERROR lines, surface them and wait for the contributor to fix (manually or via a regenerate pass) before proceeding.

Full registration checklist

Walk the full checklist from references/registration-checklist.md via TodoWrite, one item per step:

  1. Read the relevant existing file.
  2. Draft the addition.
  3. Show the diff and confirm.
  4. Apply with Edit, or create new files with Write.

If Q1 = Setup, confirm: "Setup skills are exempt from signal-definitions and /mc catalog registration per CONTRIBUTING. Skip those two steps? [Y/n]" — default Y.

Shared — version bump

Both phases converge here.

  1. Propose a level based on what actually changed:
    • New skill → minor per CONTRIBUTING § Version bumping.
    • Extend changed activation surface (phrasings in description or when_to_use) → minor.
    • Extend did not touch activation surface → patch.
  2. "Proceed with this level, or override?" Valid overrides: patch, minor, major.
  3. Run:
    !./scripts/bump-version.sh <level>
    
    The script opens $EDITOR for the changelog, then updates all 6 plugin configs and all 6 CHANGELOG.md files.

Done

Tell the contributor:

All changes are staged. Review with git status / git diff --staged, then commit and run /ship to open the PR.

Do not auto-commit or push.

Files (mc-agent-toolkit)
  • references
    • decision-rules.md 3.2 KB
      Loading…
    • handoff-preamble.md 3.8 KB
      Loading…
    • registration-checklist.md 4.3 KB
      Loading…
  • scripts
    • tests
      • find-peers.bats 1.2 KB · in bundle
      • lint-skill.bats 7.9 KB · in bundle
      • smoke-test.sh 2.4 KB
        Loading…
      • test_portable_frontmatter.py 1.8 KB
        Loading…
    • find-peers.sh 1020 B
      Loading…
    • lint-skill.py 8 KB
      Loading…
  • README.md 5.7 KB
    # toolkit-skill-author
    
    A meta-skill for **authoring or extending skills in `mc-agent-toolkit`**. Run it from the repo root via `/toolkit-skill-author`. It interviews you, applies the extend-or-split rules from `CONTRIBUTING.md`, hands off to Anthropic's `skill-creator` for the actual SKILL.md generation, and walks the registration checklist that keeps the orchestration layer, `/mc` catalog, evals, and version manifest in sync.
    
    This skill is for **toolkit contributors**, not end users of mc-agent-toolkit.
    
    ## Why this exists
    
    Adding a skill to `mc-agent-toolkit` is more than dropping a `SKILL.md` into `skills/`. A new skill must be:
    
    1. **Justified** against the extend-or-split decision rules so we don't grow a soup of overlapping skills.
    2. **Named** without colliding with existing skills (exact or near-match).
    3. **Registered** in the orchestration layer (`signal-definitions`, `/mc` catalog) so context detection can find it.
    4. **Eval'd** so activation is measurable.
    5. **Symlinked** into all six editor plugins (`claude-code`, `cursor`, `codex`, `copilot`, `opencode`, `cortex-code`).
    6. **Versioned** via `scripts/bump-version.sh` so the marketplace ships the change.
    
    Doing all of that by hand is error-prone. This skill enforces the workflow and gates against the common mistakes (forbidden buckets, name collisions, skipping registration steps).
    
    ## When to use it
    
    Run `/toolkit-skill-author` when you want to:
    
    - **Add a new skill** to the toolkit.
    - **Extend an existing skill** with new capabilities, phrasings, or references.
    
    Do **not** use it for:
    
    - **Editing skill internals that aren't activation-surface changes** (typo fixes, minor rewording). Just edit the file and run a `patch` bump.
    
    ## Prerequisites
    
    - Run from the **`mc-agent-toolkit` repo**.
    - Anthropic's `skill-creator` plugin must be installed and enabled in the current session:
      ```
      /plugin install skill-creator@claude-plugins-official
      ```
      Restart the session after install. The skill aborts if `skill-creator` isn't available — the handoff is core to the workflow, and there is no manual fallback.
    - Clean working tree recommended (the skill stages changes but does not commit).
    
    ## How it works
    
    ```
    /toolkit-skill-author
      │
      ├── Pre-load: verify repo + skill-creator availability,
      │             dump CONTRIBUTING.md and existing skill peers
      │
      ├── Phase 0 — Parse intent + apply gates
      │     ├── Gate A: forbidden bucket (Agent-routing) → halt
      │     ├── Gate B: name collision (exact or token-overlap) → ask before proceeding
      │     └── Gate C: clear extend → fast-path to Phase 2a
      │
      ├── Phase 1 — Decision survey (4 questions, one at a time)
      │     bucket · MCP surface · purpose · example prompts
      │
      ├── Decision — apply 4-step test from decision-rules.md
      │     verdict: EXTEND <peer>  or  NEW SKILL
      │
      ├── Phase 2a — Extend                   Phase 2b — New skill
      │     hand off to skill-creator           extended survey + name proposal
      │     in IMPROVE_EXISTING mode            hand off to skill-creator NEW_SKILL
      │     run lint-skill.py                   run lint-skill.py
      │     partial registration checklist     full registration checklist
      │
      └── Shared — version bump
            propose patch/minor/major per CONTRIBUTING § Version bumping
            run scripts/bump-version.sh
    ```
    
    ## What's in this directory
    
    | Path | Purpose |
    | --- | --- |
    | `SKILL.md` | The skill itself — the workflow router. |
    | `references/decision-rules.md` | Source-of-truth for the 4-step extend-or-split test. Linked from `CONTRIBUTING.md`. |
    | `references/handoff-preamble.md` | Template the skill passes to `skill-creator` so the generated SKILL.md matches toolkit conventions. |
    | `references/registration-checklist.md` | Post-handoff steps (signal-definitions, `/mc` catalog, evals, symlinks). |
    | `scripts/find-peers.sh` | Dumps name + description + when_to_use for every existing skill — the candidate set the decision tree reasons over. |
    | `scripts/check-prereqs.sh` | Pre-flight check used by the pre-load. |
    | `scripts/lint-skill.py` | Validates frontmatter (name, description ≤250 chars, prefix) after `skill-creator` returns. |
    | `scripts/tests/` | Fixture tests for the helper scripts. |
    | `evals/` | Activation evals for this skill. |
    
    ## Notes for SPEDD reviewers
    
    - The skill is **read-only** through Phase 1 — no files are touched until after the decision verdict is confirmed.
    - The skill **never auto-commits**. Every modification is staged for explicit review.
    - Forbidden-bucket and name-collision gates run **before** any survey questions, so a refusal is fast and unambiguous.
    - The four-step decision-rules test is documented in `references/decision-rules.md` and referenced by `CONTRIBUTING.md`. If the rule needs to change, update both.
    - `lint-skill.py` enforces the constraints from `.claude/rules/skills.md` (description length, name prefix). Failures block the registration checklist.
    - Version bumps go through `scripts/bump-version.sh`, which updates all six plugin manifests + changelogs in lockstep — no partial-bump risk.
    
    ## Troubleshooting
    
    | Symptom | Cause / fix |
    | --- | --- |
    | `skill-creator plugin is required` | Install `skill-creator@claude-plugins-official`, enable it, restart the session. |
    | `CONTRIBUTING.md missing — run from repo root` | You're not at the repo root. `cd` to `mc-agent-toolkit/`. |
    | Gate B fires unexpectedly on a name | Token-overlap is intentional — pick a more distinct name, or switch to extend. |
    | Lint ERROR after handoff | Either fix manually or ask `skill-creator` to regenerate the offending field. The registration checklist will not proceed until lint is clean. |
    
  • SKILL.md 8.9 KB
    ---
    name: toolkit-skill-author
    description: Authors or extends a skill in mc-agent-toolkit. Gates for forbidden buckets and name collisions, applies CONTRIBUTING's extend-or-split rules, then edits a peer skill or hands off to Anthropic's skill-creator and walks the registration checklist.
    disable-model-invocation: true
    when_to_use: |
      Invoked explicitly as /toolkit-skill-author when a contributor wants to add, extend, or draft a new skill for mc-agent-toolkit. Not auto-routed. Requires Anthropic's skill-creator plugin.
    ---
    
    # toolkit-skill-author
    
    ## Pre-load
    
    ```bash
    !test -f CONTRIBUTING.md || (echo "CONTRIBUTING.md missing — run from repo root." && exit 1)
    ```
    
    **Verify `skill-creator` is callable in this session.** Scan the available-skills list for a skill named `skill-creator` (bare or namespaced, e.g. `skill-creator:skill-creator`). If absent, abort with **exactly this message**:
    
    > `skill-creator` plugin is required. Run `/plugin install skill-creator@claude-plugins-official`, enable it, then restart this session and re-run `/toolkit-skill-author`.
    
    Do **not** fall back to manually scaffolding SKILL.md — the handoff is core to the workflow.
    
    Load authoritative context:
    
    ```bash
    !cat CONTRIBUTING.md
    !bash .claude/skills/toolkit-skill-author/scripts/find-peers.sh skills
    ```
    
    - @.claude/skills/toolkit-skill-author/references/decision-rules.md
    - @.claude/skills/toolkit-skill-author/references/handoff-preamble.md
    - @.claude/skills/toolkit-skill-author/references/registration-checklist.md
    
    ## Phase 0 — Parse intent and apply gates
    
    From the contributor's initial prompt, extract (without asking yet):
    
    - **`target_name`** — did they name a specific skill (e.g., *"extend `monitoring-advisor`"*, *"create a skill called `foo-bar`"*)?
    - **`action`** — `extend`, `new`, or `unknown`.
    - **`bucket`** — did they state a capability bucket?
    
    Apply the gates below **before** any survey question. Each gate halts when it fires.
    
    ### Gate A — Forbidden bucket
    
    If `bucket` is `Agent-routing` (or a synonym like "agent routing", "routing skill"), refuse:
    
    > Agent-routing skills are owned by the toolkit core team per `CONTRIBUTING § Capability buckets` — not authored via `/toolkit-skill-author`. Halting.
    
    Do not proceed. If `bucket` is unstated, this gate re-applies after Q1.
    
    ### Gate B — Name collision (new-skill intent)
    
    If `action` is `new` and `target_name` is given, lowercase both `target_name` and each existing skill directory name, then check:
    
    - **Exact match** (equal strings): refuse with *"`<target_name>` already exists in `skills/`. Pick a different name, or switch to extend."* Do not proceed.
    - **Near match.** Split both names on `-` into token lists. Fire if either (a) the two lists share any token, or (b) any token in one list is a substring of any token in the other list. Example: `monitor-advisor` ↔ `monitoring-advisor` fires via (a) shared `advisor` and (b) `monitor` ⊂ `monitoring`. When fired, surface the overlap and ask: *"`<target_name>` overlaps with existing `<existing>`. Did you mean to extend `<existing>`, or proceed with a new name?"* Wait for an answer before continuing.
    
    ### Gate C — Fast-path for clear extend
    
    If `action` is `extend` and `target_name` names an existing skill:
    - **Re-check the bucket.** If `target_name` is one of the agent-routing skills (`context-detection`, `incident-response`, `proactive-monitoring`), fire Gate A's refusal — those are owned by the core team and cannot be extended via `/toolkit-skill-author` either.
    - Otherwise: skip the Phase 1 survey, use the initial prompt as the extension description, and jump directly to **Phase 2a — Extend**. If the prompt is missing fields the handoff preamble needs (purpose, phrasings, output artifact), ask only for those specific fields — do not re-run the full Q1–Q4 survey.
    
    Otherwise, continue to Phase 1. **New-skill requests always run the decision tree** — the gate against hidden collisions is the tree itself.
    
    ## Phase 1 — Decision survey
    
    Ask these four questions **one at a time**, waiting for each answer.
    
    1. **Capability bucket.** Trust / Incident Response / Monitoring / Prevent / Optimize / Setup. Agent-routing is not offered. If the contributor writes in `Agent-routing`, fire Gate A and halt.
    2. **Primary MCP surface or data input.** E.g. Monte Carlo GraphQL, BigQuery INFORMATION_SCHEMA, Sentry issues. One or two items.
    3. **One-line purpose.** Plain language — no pushy triggers.
    4. **2–3 example user prompts.** Quote them literally.
    
    ## Decision
    
    Apply the 4-step test from `decision-rules.md` against the peers dumped by `find-peers.sh`. The dump shows every skill's name + description + when_to_use; reason directly about which skills could plausibly activate on the Q4 prompts.
    
    Filter agent-routing skills out of the candidate set — contributors can't author those, so they can't be extension targets. Current list: `context-detection`, `incident-response`, `proactive-monitoring`. If the toolkit adds new routing skills, update both this list and Gate C's list to match.
    
    Present the verdict:
    - `EXTEND <peer>` or `NEW SKILL`.
    - The step that decided, and why.
    - "Proceed with this verdict, or override?"
    
    If the user overrides, capture their reason verbatim — it becomes part of the PR description per `CONTRIBUTING`.
    
    ## Phase 2a — Extend
    
    Invoke `skill-creator` via the `Skill` tool in **improve-existing mode**, passing the handoff preamble from `references/handoff-preamble.md` with `MODE=IMPROVE_EXISTING`, `PEER_NAME=<peer>`, and the survey answers (or the initial prompt for the fast-path case).
    
    `skill-creator` runs its full loop; if the contributor wants a lighter-touch edit, they can tell it mid-flow to skip iteration.
    
    When `skill-creator` returns:
    
    ```bash
    !rm -rf skills/<peer>/evals/ skills/<peer>-workspace/
    !python3 .claude/skills/toolkit-skill-author/scripts/lint-skill.py <peer>
    ```
    
    Scratch-artifact cleanup removes skill-creator's iteration files (they drove the loop but aren't the repo's eval format). Lint surfaces any frontmatter violations.
    
    Walk the **partial** checklist from `references/registration-checklist.md` via TodoWrite:
    - Signal-definitions update — only if phrasings shifted.
    - `/mc` catalog update — only if user-facing surface changed.
    - Eval entry update — only if activation surface expanded.
    
    Continue to the shared version-bump step.
    
    ## Phase 2b — New skill
    
    ### Extended survey (one at a time)
    
    5. **Output artifact** — what the skill produces (file type, diff, notebook, text verdict).
    6. **Persona / workflow** — who invokes this and during what task.
    7. **Disambiguation** — how it differs from the nearest peer (by bucket), even if no peer forced a split.
    
    ### Propose name
    
    Suggest 2–3 kebab-case **directory names**. Short is better. Re-run Gate B against each candidate:
    
    - Exact match → drop the candidate.
    - Near match (token-overlap with any existing skill) → drop or explicitly flag.
    
    Only present candidates that survive Gate B. Wait for the contributor to pick one. Before handoff, re-verify `skills/<chosen>/` does not exist.
    
    **Note the two-level naming:** the directory is `skills/<chosen>/`, but the `name` field inside the generated SKILL.md frontmatter should be `monte-carlo-<chosen>` — the canonical prefixed form. The handoff preamble passes both, and `lint-skill.py` verifies them after scaffold.
    
    ### Handoff to `skill-creator`
    
    Invoke via the `Skill` tool with the handoff preamble from `references/handoff-preamble.md`, `MODE=NEW_SKILL`, and all survey answers.
    
    When `skill-creator` returns:
    
    ```bash
    !rm -rf skills/<name>/evals/ skills/<name>-workspace/
    !python3 .claude/skills/toolkit-skill-author/scripts/lint-skill.py <name>
    ```
    
    If lint prints ERROR lines, surface them and wait for the contributor to fix (manually or via a regenerate pass) before proceeding.
    
    ### Full registration checklist
    
    Walk the full checklist from `references/registration-checklist.md` via TodoWrite, one item per step:
    1. Read the relevant existing file.
    2. Draft the addition.
    3. Show the diff and confirm.
    4. Apply with `Edit`, or create new files with `Write`.
    
    If Q1 = Setup, confirm: *"Setup skills are exempt from signal-definitions and `/mc` catalog registration per CONTRIBUTING. Skip those two steps? [Y/n]"* — default Y.
    
    ## Shared — version bump
    
    Both phases converge here.
    
    1. Propose a level based on what actually changed:
       - New skill → **minor** per `CONTRIBUTING § Version bumping`.
       - Extend changed activation surface (phrasings in `description` or `when_to_use`) → **minor**.
       - Extend did not touch activation surface → **patch**.
    2. *"Proceed with this level, or override?"* Valid overrides: `patch`, `minor`, `major`.
    3. Run:
       ```bash
       !./scripts/bump-version.sh <level>
       ```
       The script opens `$EDITOR` for the changelog, then updates all 6 plugin configs and all 6 `CHANGELOG.md` files.
    
    ## Done
    
    Tell the contributor:
    
    > All changes are staged. Review with `git status` / `git diff --staged`, then commit and run `/ship` to open the PR.
    
    Do **not** auto-commit or push.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.