monte-carlo-data/mc-agent-toolkit / .claude/skills/toolkit-skill-author
toolkit-skill-author
VerifiedAuthors 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.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 5.7 KB |
| SKILL.md | skill md | 8.9 KB |
| references/decision-rules.md | markdown | 3.2 KB |
| references/handoff-preamble.md | markdown | 3.8 KB |
| references/registration-checklist.md | markdown | 4.7 KB |
| scripts/find-peers.shexecutable | script | 1020 B |
| scripts/lint-skill.pyexecutable | script | 8.0 KB |
| scripts/tests/find-peers.bats | other | 1.2 KB |
| scripts/tests/lint-skill.bats | other | 7.9 KB |
| scripts/tests/smoke-test.shexecutable | script | 2.4 KB |
| scripts/tests/test_portable_frontmatter.py | script | 1.8 KB |
README.md
View on GitHub# 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. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |