Command to Skill Migration skill for Claude Code

#!/usr/bin/env python3
"""Plan or perform migration of .claude/commands/**/*.md into .claude/skills/<name>/SKILL.md.

Default is a dry run that prints a migration table and warnings. Nothing is written
unless --write is given. Existing skill folders are never overwritten.

Usage:
  python3 convert_commands.py [--src .claude/commands] [--dest .claude/skills]
                              [--write] [--renumber] [--json]

  --renumber  shift 1-based positional placeholders ($1..$9) down by one ($0..$8),
              for command files written when $1 meant the first argument.
Exit codes: 0 ok, 1 problems found that need a human decision (collisions, existing
skills, missing descriptions), 2 usage error.
"""
import argparse
import json
import re
import sys
from pathlib import Path

KNOWN_KEYS = {
    "description", "argument-hint", "allowed-tools", "model", "disable-model-invocation",
    "user-invocable", "arguments", "when_to_use", "effort", "context", "agent",
    "disallowed-tools", "hooks", "shell",
}
SIDE_EFFECTS = re.compile(
    r"\b(git\s+push|git\s+commit|deploy|publish|release|npm\s+publish|kubectl\s+(apply|delete)|"
    r"terraform\s+(apply|destroy)|rm\s+-rf|gh\s+pr\s+(create|merge)|gh\s+release|drop\s+table)\b",
    re.I,
)
POSITIONAL = re.compile(r"(?<![\\\w])\$([1-9])(?!\d)")
NAME_OK = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")


def split_frontmatter(text: str):
    if text.startswith("---\n"):
        end = text.find("\n---", 4)
        if end != -1:
            return text[4:end], text[end + 4:].lstrip("\n")
    return "", text


def parse_simple_yaml(block: str) -> dict:
    """Parse flat 'key: value' frontmatter; keeps unknown structure as raw lines."""
    data, current = {}, None
    for line in block.splitlines():
        if not line.strip():
            continue
        m = re.match(r"^([A-Za-z_][\w-]*):\s*(.*)$", line)
        if m and not line.startswith((" ", "\t")):
            current = m.group(1)
            data[current] = m.group(2)
        elif current:
            data[current] += "\n" + line
    return data


def slugify(s: str) -> str:
    return re.sub(r"-+", "-", re.sub(r"[^a-z0-9]+", "-", s.lower())).strip("-")


def first_sentence(body: str) -> str:
    for line in body.splitlines():
        t = line.strip().lstrip("#").strip()
        if t and not t.startswith(("!", "```", "@")):
            return t[:200]
    return ""


def plan(src: Path, dest: Path, renumber: bool):
    files = sorted(p for p in src.rglob("*.md") if p.is_file())
    stems = {}
    for p in files:
        stems.setdefault(slugify(p.stem), []).append(p)
    items = []
    for p in files:
        rel = p.relative_to(src)
        base = slugify(p.stem)
        collision = len(stems[base]) > 1
        name = slugify("-".join(rel.with_suffix("").parts)) if collision else base
        fm_raw, body = split_frontmatter(p.read_text(encoding="utf-8"))
        fm = parse_simple_yaml(fm_raw)
        warnings, decisions = [], []
        if collision:
            warnings.append(f"name collision on '{base}': renamed to /{name} (slash command changes)")
        if not NAME_OK.match(name) or "claude" in name or "anthropic" in name:
            warnings.append(f"name '{name}' is not portable; choose another")
        unknown = sorted(set(fm) - KNOWN_KEYS)
        if unknown:
            warnings.append(f"unknown frontmatter keys dropped: {', '.join(unknown)}")
            for k in unknown:
                fm.pop(k)
        if "name" in fm:
            fm.pop("name")
        if not fm.get("description", "").strip():
            guess = first_sentence(body)
            fm["description"] = guess or "TODO: describe what this does and when to use it"
            warnings.append("no description: drafted from first line, rewrite it with trigger words")
        if "disable-model-invocation" not in fm:
            if SIDE_EFFECTS.search(body):
                fm["disable-model-invocation"] = "true"
                decisions.append("side effects detected: set disable-model-invocation: true")
            else:
                decisions.append("no side effects detected: Claude may auto-invoke; confirm this is wanted")
        positions = sorted({int(m.group(1)) for m in POSITIONAL.finditer(body)})
        if positions:
            if renumber:
                body = POSITIONAL.sub(lambda m: f"${int(m.group(1)) - 1}", body)
                decisions.append(f"renumbered positional args {positions} -> {[n - 1 for n in positions]}")
            else:
                warnings.append(
                    f"uses positional ${'/$'.join(map(str, positions))}: current indexing is 0-based "
                    "($0 = first). Verify, or rerun with --renumber"
                )
        if "$ARGUMENTS" not in body and not positions and fm.get("argument-hint"):
            decisions.append("argument-hint set but body has no placeholder: args will be appended as 'ARGUMENTS: ...'")
        target = dest / name / "SKILL.md"
        if target.parent.exists():
            warnings.append(f"{target.parent} already exists: skipped (a skill already shadows this command)")
        items.append({
            "source": str(p), "skill": name, "target": str(target),
            "frontmatter": fm, "body": body, "warnings": warnings, "decisions": decisions,
        })
    return items


def render(item) -> str:
    fm = item["frontmatter"]
    lines = ["---", f"name: {item['skill']}"]
    for k in ["description", "when_to_use", "argument-hint", "arguments", "disable-model-invocation",
              "user-invocable", "allowed-tools", "disallowed-tools", "model", "effort", "context",
              "agent", "shell", "hooks"]:
        if k in fm:
            lines.append(f"{k}: {fm[k]}")
    lines.append("---")
    return "\n".join(lines) + "\n\n" + item["body"].rstrip() + "\n"


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--src", default=".claude/commands")
    ap.add_argument("--dest", default=".claude/skills")
    ap.add_argument("--write", action="store_true")
    ap.add_argument("--renumber", action="store_true")
    ap.add_argument("--json", action="store_true")
    a = ap.parse_args()
    src, dest = Path(a.src), Path(a.dest)
    if not src.is_dir():
        print(f"error: {src} is not a directory", file=sys.stderr)
        return 2
    items = plan(src, dest, a.renumber)
    if a.json:
        print(json.dumps([{k: v for k, v in i.items() if k != "body"} for i in items], indent=2))
    else:
        print(f"{len(items)} command file(s) in {src}\n")
        for i in items:
            print(f"- {i['source']} -> {i['target']}")
            for d in i["decisions"]:
                print(f"    decision: {d}")
            for w in i["warnings"]:
                print(f"    WARNING:  {w}")
    written = 0
    if a.write:
        for i in items:
            t = Path(i["target"])
            if t.parent.exists():
                continue
            t.parent.mkdir(parents=True)
            t.write_text(render(i), encoding="utf-8")
            written += 1
        print(f"\nwrote {written} skill(s). Old command files were NOT deleted; remove them after testing.")
    else:
        print("\ndry run: nothing written (pass --write to create skills)")
    needs_human = any(i["warnings"] for i in items)
    return 1 if needs_human else 0


if __name__ == "__main__":
    sys.exit(main())