{"slug":"toolkit-skill-author","title":"toolkit-skill-author","summary":"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.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-20T07:56:54.482181Z","repo":{"url":"https://github.com/monte-carlo-data/mc-agent-toolkit","stars":92,"forks":5,"license":"Apache-2.0","updatedAt":"2026-09-27T17:08:21Z"},"bodyHtml":"<h1>toolkit-skill-author</h1>\n<p>A meta-skill for <strong>authoring or extending skills in <code>mc-agent-toolkit</code></strong>. Run it from the repo root via <code>/toolkit-skill-author</code>. It interviews you, applies the extend-or-split rules from <code>CONTRIBUTING.md</code>, hands off to Anthropic's <code>skill-creator</code> for the actual SKILL.md generation, and walks the registration checklist that keeps the orchestration layer, <code>/mc</code> catalog, evals, and version manifest in sync.</p>\n<p>This skill is for <strong>toolkit contributors</strong>, not end users of mc-agent-toolkit.</p>\n<h2>Why this exists</h2>\n<p>Adding a skill to <code>mc-agent-toolkit</code> is more than dropping a <code>SKILL.md</code> into <code>skills/</code>. A new skill must be:</p>\n<ol>\n<li><strong>Justified</strong> against the extend-or-split decision rules so we don't grow a soup of overlapping skills.</li>\n<li><strong>Named</strong> without colliding with existing skills (exact or near-match).</li>\n<li><strong>Registered</strong> in the orchestration layer (<code>signal-definitions</code>, <code>/mc</code> catalog) so context detection can find it.</li>\n<li><strong>Eval'd</strong> so activation is measurable.</li>\n<li><strong>Symlinked</strong> into all six editor plugins (<code>claude-code</code>, <code>cursor</code>, <code>codex</code>, <code>copilot</code>, <code>opencode</code>, <code>cortex-code</code>).</li>\n<li><strong>Versioned</strong> via <code>scripts/bump-version.sh</code> so the marketplace ships the change.</li>\n</ol>\n<p>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).</p>\n<h2>When to use it</h2>\n<p>Run <code>/toolkit-skill-author</code> when you want to:</p>\n<ul>\n<li><strong>Add a new skill</strong> to the toolkit.</li>\n<li><strong>Extend an existing skill</strong> with new capabilities, phrasings, or references.</li>\n</ul>\n<p>Do <strong>not</strong> use it for:</p>\n<ul>\n<li><strong>Editing skill internals that aren't activation-surface changes</strong> (typo fixes, minor rewording). Just edit the file and run a <code>patch</code> bump.</li>\n</ul>\n<h2>Prerequisites</h2>\n<ul>\n<li>Run from the <strong><code>mc-agent-toolkit</code> repo</strong>.</li>\n<li>Anthropic's <code>skill-creator</code> plugin must be installed and enabled in the current session:\n<pre><code>/plugin install skill-creator@claude-plugins-official\n</code></pre>\nRestart the session after install. The skill aborts if <code>skill-creator</code> isn't available — the handoff is core to the workflow, and there is no manual fallback.</li>\n<li>Clean working tree recommended (the skill stages changes but does not commit).</li>\n</ul>\n<h2>How it works</h2>\n<pre><code>/toolkit-skill-author\n  │\n  ├── Pre-load: verify repo + skill-creator availability,\n  │             dump CONTRIBUTING.md and existing skill peers\n  │\n  ├── Phase 0 — Parse intent + apply gates\n  │     ├── Gate A: forbidden bucket (Agent-routing) → halt\n  │     ├── Gate B: name collision (exact or token-overlap) → ask before proceeding\n  │     └── Gate C: clear extend → fast-path to Phase 2a\n  │\n  ├── Phase 1 — Decision survey (4 questions, one at a time)\n  │     bucket · MCP surface · purpose · example prompts\n  │\n  ├── Decision — apply 4-step test from decision-rules.md\n  │     verdict: EXTEND &lt;peer&gt;  or  NEW SKILL\n  │\n  ├── Phase 2a — Extend                   Phase 2b — New skill\n  │     hand off to skill-creator           extended survey + name proposal\n  │     in IMPROVE_EXISTING mode            hand off to skill-creator NEW_SKILL\n  │     run lint-skill.py                   run lint-skill.py\n  │     partial registration checklist     full registration checklist\n  │\n  └── Shared — version bump\n        propose patch/minor/major per CONTRIBUTING § Version bumping\n        run scripts/bump-version.sh\n</code></pre>\n<h2>What's in this directory</h2>\n<table>\n<thead>\n<tr>\n<th>Path</th>\n<th>Purpose</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>SKILL.md</code></td>\n<td>The skill itself — the workflow router.</td>\n</tr>\n<tr>\n<td><code>references/decision-rules.md</code></td>\n<td>Source-of-truth for the 4-step extend-or-split test. Linked from <code>CONTRIBUTING.md</code>.</td>\n</tr>\n<tr>\n<td><code>references/handoff-preamble.md</code></td>\n<td>Template the skill passes to <code>skill-creator</code> so the generated SKILL.md matches toolkit conventions.</td>\n</tr>\n<tr>\n<td><code>references/registration-checklist.md</code></td>\n<td>Post-handoff steps (signal-definitions, <code>/mc</code> catalog, evals, symlinks).</td>\n</tr>\n<tr>\n<td><code>scripts/find-peers.sh</code></td>\n<td>Dumps name + description + when_to_use for every existing skill — the candidate set the decision tree reasons over.</td>\n</tr>\n<tr>\n<td><code>scripts/check-prereqs.sh</code></td>\n<td>Pre-flight check used by the pre-load.</td>\n</tr>\n<tr>\n<td><code>scripts/lint-skill.py</code></td>\n<td>Validates frontmatter (name, description ≤250 chars, prefix) after <code>skill-creator</code> returns.</td>\n</tr>\n<tr>\n<td><code>scripts/tests/</code></td>\n<td>Fixture tests for the helper scripts.</td>\n</tr>\n<tr>\n<td><code>evals/</code></td>\n<td>Activation evals for this skill.</td>\n</tr>\n</tbody>\n</table>\n<h2>Notes for SPEDD reviewers</h2>\n<ul>\n<li>The skill is <strong>read-only</strong> through Phase 1 — no files are touched until after the decision verdict is confirmed.</li>\n<li>The skill <strong>never auto-commits</strong>. Every modification is staged for explicit review.</li>\n<li>Forbidden-bucket and name-collision gates run <strong>before</strong> any survey questions, so a refusal is fast and unambiguous.</li>\n<li>The four-step decision-rules test is documented in <code>references/decision-rules.md</code> and referenced by <code>CONTRIBUTING.md</code>. If the rule needs to change, update both.</li>\n<li><code>lint-skill.py</code> enforces the constraints from <code>.claude/rules/skills.md</code> (description length, name prefix). Failures block the registration checklist.</li>\n<li>Version bumps go through <code>scripts/bump-version.sh</code>, which updates all six plugin manifests + changelogs in lockstep — no partial-bump risk.</li>\n</ul>\n<h2>Troubleshooting</h2>\n<table>\n<thead>\n<tr>\n<th>Symptom</th>\n<th>Cause / fix</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>skill-creator plugin is required</code></td>\n<td>Install <code>skill-creator@claude-plugins-official</code>, enable it, restart the session.</td>\n</tr>\n<tr>\n<td><code>CONTRIBUTING.md missing — run from repo root</code></td>\n<td>You're not at the repo root. <code>cd</code> to <code>mc-agent-toolkit/</code>.</td>\n</tr>\n<tr>\n<td>Gate B fires unexpectedly on a name</td>\n<td>Token-overlap is intentional — pick a more distinct name, or switch to extend.</td>\n</tr>\n<tr>\n<td>Lint ERROR after handoff</td>\n<td>Either fix manually or ask <code>skill-creator</code> to regenerate the offending field. The registration checklist will not proceed until lint is clean.</td>\n</tr>\n</tbody>\n</table>\n","files":[{"path":"README.md","sizeBytes":5797,"isText":true},{"path":"references/decision-rules.md","sizeBytes":3303,"isText":true},{"path":"references/handoff-preamble.md","sizeBytes":3850,"isText":true},{"path":"references/registration-checklist.md","sizeBytes":4417,"isText":true},{"path":"scripts/find-peers.sh","sizeBytes":1020,"isText":true},{"path":"scripts/lint-skill.py","sizeBytes":8193,"isText":true},{"path":"scripts/tests/find-peers.bats","sizeBytes":1268,"isText":false},{"path":"scripts/tests/lint-skill.bats","sizeBytes":8059,"isText":false},{"path":"scripts/tests/smoke-test.sh","sizeBytes":2500,"isText":true},{"path":"scripts/tests/test_portable_frontmatter.py","sizeBytes":1800,"isText":true},{"path":"SKILL.md","sizeBytes":9121,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-27T20:55:03.219808Z","sha256":"1A5558EFE97C34E1FDDB94C4FBA602D845D2A1C7A4DF48412F7118097AF740AB","sizeBytes":20699},"review":null,"source":{"repositoryUrl":"https://github.com/monte-carlo-data/mc-agent-toolkit","path":".claude/skills/toolkit-skill-author","license":"Apache-2.0","commit":"f45839dcbc58435014568e1f59538b2963343b38","subtreeSha":"626EBBA7379C05FA7D6A8A551EB7591EAC35FDF508BBC0CC9AAB1CBC6384E173","lastSyncedAt":"2026-09-27T20:54:50.757795Z"},"reviewedAt":"2026-09-27T20:55:46.868225Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/monte-carlo-data/mc-agent-toolkit/tree/main/.claude/skills/toolkit-skill-author"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install monte-carlo-data-mc-agent-toolkit@llmmart"},{"target":"git","command":"git clone https://github.com/monte-carlo-data/mc-agent-toolkit.git"}]}