monte-carlo-data/mc-agent-toolkit / .claude/skills/toolkit-skill-author
toolkit-skill-author
UnverifiedAuthors 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 |
scripts/lint-skill.py
View on GitHub#!/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
- plugin-only portability markers: line-anchored, never nested, balanced start/end pairs
- `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 key == "metadata" and not rest:
i += 1
while i < len(lines) and (lines[i].startswith(" ") or not lines[i].strip()):
nested = re.match(r"^ bucket:\s*(.*?)\s*$", lines[i])
if nested:
result["metadata.bucket"] = nested.group(1).strip("\"'")
i += 1
elif 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 check_plugin_only_markers(text: str) -> list[str]:
"""Check `plugin-only` portability markers for balance and line anchoring.
Contract (`.claude/rules/skills.md` § "Mark plugin-only sections with
portability markers"): markers sit alone on their own line, never nest,
and every start pairs with the next end — an unbalanced marker makes the
MCP prompt renderer silently drop the rest of the file.
"""
errors: list[str] = []
open_line: int | None = None
for lineno, line in enumerate(text.splitlines(), start=1):
stripped = line.strip()
if "plugin-only:start" in line:
if stripped != "<!-- plugin-only:start -->":
errors.append(
f"line {lineno}: plugin-only:start marker is not line-anchored "
"(must be alone on its own line)"
)
elif open_line is not None:
errors.append(
f"line {lineno}: nested plugin-only:start "
f"(a block opened on line {open_line} is still open)"
)
else:
open_line = lineno
if "plugin-only:end" in line:
if stripped != "<!-- plugin-only:end -->":
errors.append(
f"line {lineno}: plugin-only:end marker is not line-anchored "
"(must be alone on its own line)"
)
elif open_line is None:
errors.append(
f"line {lineno}: plugin-only:end without an open plugin-only:start"
)
else:
open_line = None
if open_line is not None:
errors.append(
f"line {open_line}: plugin-only:start never closed "
"(plugin-only:end missing before end of file)"
)
return errors
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] = []
errors.extend(check_plugin_only_markers(text))
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 and "metadata.bucket" not in fm:
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("metadata.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()
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: 470k | Updated | Claude CodeCodex | Unverified | 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 |