Skip to content

monte-carlo-data/mc-agent-toolkit / .claude/skills/toolkit-skill-author

toolkit-skill-author

Unverified

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.

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()
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: 470kUpdated Claude CodeCodexUnverifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall