# Extend-or-split decision rules

**Canonical source.** `CONTRIBUTING.md § Skill authoring standards → Extend or split?` summarizes and links here; if the two disagree, this file wins.

**Default:** extend an existing peer skill. Split only when a rule forces it.

**Forbidden buckets.** Agent-routing skills are owned by the toolkit core team per `CONTRIBUTING § Capability buckets` — do not author them via `/toolkit-skill-author`. If the contributor's Q1 answer is `Agent-routing`, halt and refuse before peer search. Do not proceed.

## The 4-step test

Apply in order. Stop at the first step that decides.

### Step 1 — Find the nearest peer

`find-peers.sh` (run in Pre-load) dumps every skill's `name + description + when_to_use`. Read the dump and reason about which skills could plausibly activate on the new skill's Q4 prompts.

For each plausible candidate, ask: *can you write a realistic user prompt that should route to the new skill but could plausibly activate the candidate instead?*

- If no candidate survives this test → **there is no routing collision. Go to new-skill path. Stop.**
- If at least one survives → that is the peer. Continue to Step 2.

### Step 2 — Budget check

Open the peer's `SKILL.md`. Count the combined character length of `description` + `when_to_use`.
If adding one sentence to `description` or one bullet to `when_to_use` would push the combined length past **1,400 characters** → **split.** Stop.
(The hard ceiling is 1,536; 1,400 leaves headroom.)

### Step 3 — Surface check

Does the new behavior:
- hit a different MCP surface / data input, **or**
- produce a different output artifact, **or**
- belong to a different capability bucket

…than the peer? If yes → **split.** Stop.

### Step 4 — Otherwise, extend

Phrasing overlap, "it feels like its own thing," or wanting a cleaner file are not reasons to split. Add a bullet to the peer's `when_to_use`, add a `references/` file if the workflow needs more room.

## PR requirement

If the verdict is SPLIT, the contributor must name the peer(s) considered and cite which step forced the split. `toolkit-skill-author` captures this as the override reason and surfaces it for the PR description.

## Worked example

This example walks the tree for an **ambiguous new-skill** request — the case where Phase 0's Gate C doesn't fast-path, so the full decision applies. (Clear-extend requests skip the tree via Gate C; clear name collisions halt at Gate B.)

- Survey answers: bucket = Monitoring, surface = BigQuery INFORMATION_SCHEMA, purpose = "detect stale partitions," phrasings = ["find stale partitions", "partition freshness"].
- Peer dump shows: `monitoring-advisor`, `tune-monitor`, and others.
- Step 1: `monitoring-advisor`'s current scope ("create monitors for warehouse tables") plausibly activates on "find stale partitions." Peer survives. Continue.
- Step 2: measure `monitoring-advisor`'s actual combined `description + when_to_use` length and add the proposed bullet. If the sum stays under 1,400, no budget pressure. Continue.
- Step 3: same bucket (Monitoring), same primary surface (warehouse table reads, BigQuery is a subset), output overlaps (monitor recommendations). No surface pressure.
- Step 4: **extend** `monitoring-advisor` with the new phrasings.

# Handoff preamble for Anthropic's `skill-creator`

This is the template `toolkit-skill-author` uses when invoking Anthropic's `skill-creator` via the `Skill` tool. Claude fills in the bracketed placeholders from survey answers.

## Template

You are being invoked by mc-agent-toolkit's `/toolkit-skill-author` with pre-collected context.
**Use the pre-filled answers below to skip your initial interview. Then run your full workflow — test cases, iterate loop, and description optimizer — using the answers as the starting draft. If the contributor tells you mid-flow to skip iteration ("just vibe with me"), honor that.**

**Mode:** {{NEW_SKILL | IMPROVE_EXISTING}}

**Target path:** `skills/{{NAME}}/` in the mc-agent-toolkit repo (not your default workspace).

**Pre-filled answers:**
- What should this skill enable Claude to do? {{PURPOSE}}
- When should this skill trigger? {{PHRASINGS as bullet list}}
- Expected output format: {{OUTPUT}}

**Body context (inform the SKILL.md body, do NOT copy verbatim into frontmatter):**
- Persona / workflow: {{PERSONA_WORKFLOW}}
- Disambiguation from nearest peer `{{PEER_NAME}}`: {{DISAMBIGUATION}}
- Bucket: {{BUCKET}} (also emitted as the `bucket` frontmatter field — see below)

**MC-specific voice and length rules (override your defaults):**
- `description` ≤ 1,024 characters.
- Combined `description` + `when_to_use` ≤ 1,400 characters (headroom under the 1,536 truncation ceiling).
- Third-person voice. Describe what the skill does, not what "this skill" does.
- Do **not** open with "This skill…" or "Use this skill when…".
- Do **not** use the "pushy" voice pattern ("Make sure to use this skill whenever…"); use concrete triggers instead.

**Required frontmatter fields (and fields NOT to emit):**
- `name`: `monte-carlo-{{NAME}}` — canonical prefixed form; `{{NAME}}` is the directory name.
- `description`: per the length rule above.
- `when_to_use`: required (not optional).
- `bucket`: `{{BUCKET}}` — one of Trust / Incident Response / Monitoring / Prevent / Optimize / Setup. Tracks which capability bucket the skill belongs to in the public docs.
- Do **not** emit a `version` field. Versions live in the plugin manifests (`plugins/*/.*-plugin/plugin.json`), not in SKILL.md. `toolkit-skill-author` will bump them separately via `scripts/bump-version.sh` after you return.

**Eval artifacts are scratch, not shipped:**
- Your `skills/{{NAME}}/evals/evals.json` and sibling `skills/{{NAME}}-workspace/` drive the iteration loop but are not the repo's eval format. `toolkit-skill-author` will delete them after you return.
- mc-agent-toolkit's real evals live at `plugins/claude-code/evals/{{NAME}}/live-evals-dev.yaml` — a YAML schema with `cases: [{ id, turns: [{ prompt, criteria: { must_call, must_not_call } }], criteria: { judge_rubric } }]`. Authoring that file is handled by `toolkit-skill-author` in the registration checklist — don't attempt to write it yourself, and don't produce a `trigger-evals.json` or any JSON variant.

**When done:** return control to `toolkit-skill-author`. It will lint the generated SKILL.md, clean up scratch artifacts, and walk the registration checklist.

## Improve-existing mode differences

When `{{MODE}} == IMPROVE_EXISTING`:
- **Target path:** the existing `skills/{{PEER_NAME}}/` (edit in place, not new scaffold).
- **Pre-filled answers** describe the *extension*, not a new skill.
- Otherwise identical: same voice rules, same full workflow, same scratch-artifact cleanup.

# Registration checklist

After Phase 2a (extend) or Phase 2b (new skill), walk the relevant subset of these steps. `toolkit-skill-author` tracks each as a TodoWrite item and confirms before writing any file.

## Full checklist (new skill)

Use when Phase 2b concludes with a scaffolded `skills/<name>/SKILL.md`.

1. **Signal definition.** Append a row to `skills/context-detection/references/signal-definitions.md` under *Conversation Signals* and/or *Workspace Signals*. Describe the keywords, artifacts, and user phrasings that should route to the new skill.
   *Skipped if bucket = Setup (after user confirmation).*
2. **`/mc` catalog entry.** Append a row to `plugins/claude-code/commands/catalog/mc.md`.
   *Skipped if bucket = Setup (after user confirmation).*
3. **Eval scaffold.** Create `plugins/claude-code/evals/<name>/live-evals-dev.yaml` using the YAML schema the repo already ships for every other skill. Read `plugins/claude-code/evals/monitoring-advisor/live-evals-dev.yaml` or `plugins/claude-code/evals/context-detection/live-evals-dev.yaml` as templates before writing. Schema:

   ```yaml
   cases:
     - id: <slug-id>
       turns:
         - prompt: "<realistic user prompt>"
           criteria:
             must_call: [mcp_tool_1, mcp_tool_2]      # optional
             must_not_call: [forbidden_tool]           # optional
       criteria:
         judge_rubric: |
           <free-form description of desired behavior>
   ```

   Seed with the Q4 phrasings plus 2–3 should-not-trigger near-misses. Do **not** create `trigger-evals.json` or any other JSON variant — YAML is the canonical format.
4. **Editor plugin symlinks.** For each editor in `plugins/` (claude-code, cursor, opencode, codex), add a relative symlink:
   ```
   plugins/<editor>/skills/<name> -> ../../../skills/<name>
   ```
5. **Claude Code commands entry.** Create `plugins/claude-code/commands/<name>/` with at least one `.md` command file. Add the directory name to the `commands` array in `plugins/claude-code/.claude-plugin/plugin.json`.

## Partial checklist (extend)

Use when Phase 2a edits an existing peer.

1. **Signal definition.** Update only if phrasings shifted (new user-facing routing language).
2. **`/mc` catalog.** Update only if the user-facing surface changed (new capability described in the catalog row).
3. **Eval entry.** Update the peer's existing `plugins/claude-code/evals/<peer>/` entry only if the activation surface expanded.

No symlink or commands changes for extend (they already exist for the peer).

## Setup-bucket confirmation prompt

When Q1 = Setup, `toolkit-skill-author` prompts:

> Setup skills are exempt from signal-definitions and `/mc` catalog registration per `CONTRIBUTING § Capability buckets`. Skip these steps? [Y/n]

Default Y. On N, proceed with steps 1 and 2 as normal (user opted back in).

## Version bump (always)

After the relevant registration subset, run:

```
./scripts/bump-version.sh <patch|minor>
```

See `CONTRIBUTING.md § Version bumping` for semver rules. `toolkit-skill-author` proposes the level; user can override.

#!/usr/bin/env bash
# Dump every skill's frontmatter (name + description + when_to_use) so Claude can
# reason about which skills are peers to the new/extended one. Replaces the old
# bucket+keyword filtering, which was too brittle to be useful — baseline evals
# showed false positives from substring bucket matches and false negatives from
# stopword-dominated keyword ranking.
#
# Output is the raw frontmatter block for each skill, separated by `=== <name> ===`
# headers. Claude reads it and applies the 4-step decision-rules test itself.
set -euo pipefail

SKILLS_DIR="${1:-skills}"

if [ ! -d "$SKILLS_DIR" ]; then
  echo "find-peers.sh: skills dir '$SKILLS_DIR' not found" >&2
  exit 2
fi

found=0
for sm in "$SKILLS_DIR"/*/SKILL.md; do
  [ -f "$sm" ] || continue
  found=1
  name="$(basename "$(dirname "$sm")")"
  echo "=== $name ==="
  awk '/^---[[:space:]]*$/{c++; if(c==2)exit; next} c==1' "$sm"
  echo
done

[ "$found" -eq 1 ] || { echo "find-peers.sh: no SKILL.md files in '$SKILLS_DIR'" >&2; exit 2; }

#!/usr/bin/env python3
"""Lint a customer-facing skill's SKILL.md frontmatter against mc-agent-toolkit standards.

Scope: skills under `skills/`. Dev-only skills under `.claude/skills/` (e.g., toolkit-skill-author
itself) are out of scope and not required to follow the prefix rule — don't point this
script at them.

Parses YAML frontmatter (handles scalar, block, and folded forms), then checks:
- name equals `monte-carlo-<dir>` (canonical) and is kebab-case
- description present, <= 1024 chars, no first-person opener
- when_to_use present (strongly recommended per CONTRIBUTING)
- combined description + when_to_use <= 1400 chars (headroom under 1536 truncation)
- bucket present and is one of the canonical capability buckets
- `version` field WARN (ignored by Claude — plugin versions live in manifests —
  but many legacy skills carry it; don't fail lint on that).

Exits 0 if clean, 1 on any ERROR, 2 on usage / file errors.
"""
import re
import sys
from pathlib import Path

MAX_DESCRIPTION = 1024
MAX_COMBINED = 1400
FIRST_PERSON_RE = re.compile(r"^\s*(this skill|use this skill)", re.IGNORECASE)
KEBAB_RE = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
VALID_BUCKETS = {
    "Trust",
    "Incident Response",
    "Monitoring",
    "Prevent",
    "Optimize",
    "Setup",
    # Agent-routing skills are outside the user-facing capability buckets
    # (orchestrators, owned by the toolkit core team). /toolkit-skill-author blocks
    # new ones at Gate A, but existing routers still carry this bucket value.
    "Agent-routing",
}


def parse_frontmatter(text: str) -> dict[str, str]:
    m = re.match(r"^---\s*\n(.*?)\n---", text, re.DOTALL)
    if not m:
        return {}
    lines = m.group(1).split("\n")
    result: dict[str, str] = {}
    i = 0
    while i < len(lines):
        line = lines[i]
        if not line.strip() or line.lstrip().startswith("#"):
            i += 1
            continue
        km = re.match(r"^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$", line)
        if not km:
            i += 1
            continue
        key, rest = km.group(1), km.group(2).rstrip()
        if rest in ("|", ">", "|-", "|+", ">-", ">+"):
            i += 1
            block: list[str] = []
            while i < len(lines):
                bline = lines[i]
                if bline.startswith("  "):
                    block.append(bline[2:])
                    i += 1
                elif bline.strip() == "":
                    block.append("")
                    i += 1
                else:
                    break
            joined = "\n".join(block).rstrip("\n")
            if rest.startswith(">"):
                joined = re.sub(r"\n(?!\n)", " ", joined)
            result[key] = joined
        else:
            val = rest
            if (val.startswith('"') and val.endswith('"')) or (val.startswith("'") and val.endswith("'")):
                val = val[1:-1]
            result[key] = val
            i += 1
    return result


def lint(name: str, skills_root: Path) -> tuple[list[str], list[str]]:
    path = skills_root / name / "SKILL.md"
    if not path.is_file():
        print(f"ERROR: {path} not found", file=sys.stderr)
        sys.exit(2)
    text = path.read_text()
    fm = parse_frontmatter(text)

    errors: list[str] = []
    warnings: list[str] = []

    actual_name = fm.get("name", "")
    expected = f"monte-carlo-{name}"
    if actual_name != expected:
        errors.append(
            f"name '{actual_name}' should be '{expected}' "
            f"(canonical form: 'monte-carlo-<directory>')"
        )
    if actual_name and not KEBAB_RE.match(actual_name):
        errors.append(f"name '{actual_name}' is not kebab-case")

    desc = fm.get("description", "")
    if not desc:
        errors.append("description is missing (required)")
    else:
        if len(desc) > MAX_DESCRIPTION:
            errors.append(f"description is {len(desc)} chars (max {MAX_DESCRIPTION})")
        if FIRST_PERSON_RE.match(desc):
            errors.append(f"description opens with first-person phrasing (\"{desc[:40]}...\")")

    wtu = fm.get("when_to_use", "")
    if not wtu:
        warnings.append("when_to_use is missing (strongly recommended per CONTRIBUTING)")

    combined = len(desc) + len(wtu)
    if combined > MAX_COMBINED:
        errors.append(
            f"description + when_to_use = {combined} chars "
            f"(max {MAX_COMBINED} for headroom under 1536 truncation)"
        )

    bucket = fm.get("bucket", "").strip()
    if not bucket:
        errors.append(
            f"bucket is missing (required; one of: {', '.join(sorted(VALID_BUCKETS))})"
        )
    elif bucket not in VALID_BUCKETS:
        errors.append(
            f"bucket '{bucket}' is not a valid capability bucket "
            f"(expected one of: {', '.join(sorted(VALID_BUCKETS))})"
        )

    if "version" in fm:
        warnings.append(
            "version field in SKILL.md is ignored by Claude — plugin versions "
            "live in plugins/*/.*-plugin/plugin.json (new skills don't need it)"
        )

    print(f"skill: {name}")
    print(f"  description: {len(desc)} chars")
    print(f"  when_to_use: {len(wtu)} chars")
    print(f"  combined:    {combined} chars  (limit {MAX_COMBINED})")
    for w in warnings:
        print(f"  WARN:  {w}")
    for e in errors:
        print(f"  ERROR: {e}")

    return errors, warnings


def main() -> None:
    if len(sys.argv) < 2 or len(sys.argv) > 3:
        print("Usage: lint-skill.py <skill-name> [skills-root]", file=sys.stderr)
        sys.exit(2)
    name = sys.argv[1]
    skills_root = Path(sys.argv[2]) if len(sys.argv) == 3 else Path("skills")
    errors, _ = lint(name, skills_root)
    sys.exit(1 if errors else 0)


if __name__ == "__main__":
    main()