dsh-aris-panel 0.1.0

package/tools/check_skills_inventory.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""Check ARIS skill inventory drift across mainline, Codex mirror, and docs."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SKILLS_ROOT = REPO_ROOT / "skills"
+CODEX_ROOT = SKILLS_ROOT / "skills-codex"
+CATALOG = REPO_ROOT / "docs" / "SKILLS_CATALOG.md"
+README = REPO_ROOT / "README.md"
+README_CN = REPO_ROOT / "README_CN.md"
+AGENT_GUIDE = REPO_ROOT / "AGENT_GUIDE.md"
+ARIS_INTRO = REPO_ROOT / "docs" / "ARIS_INTRO.md"
+ARIS_INTRO_HTML = REPO_ROOT / "docs" / "ARIS_INTRO.html"
+CODEX_README = CODEX_ROOT / "README.md"
+CODEX_README_CN = CODEX_ROOT / "README_CN.md"
+BOM = b"\xef\xbb\xbf"
+
+FORBIDDEN_CODEX_REVIEWER_STRINGS = (
+    "mcp__codex__codex",
+    "codex-reply",
+    "reviewer-continuation",
+    "threadId",
+)
+
+# Phase A (issue #240): cross-language anchor IDs that MUST exist as
+# explicit `<a id="..."></a>` in both README.md and README_CN.md so that
+# cross-language hyperlinks resolve identically. Adding a new numbered
+# section means adding it to both READMEs AND extending this list.
+REQUIRED_README_ANCHORS = (
+    "contents",
+    "more-than-just-a-prompt",
+    "whats-new",
+    "quick-start",
+    "features",
+    "score-progression",
+    "community-showcase",
+    "awesome-community-skills",
+    "workflows",
+    "skills-catalog",
+    "setup",
+    "customization",
+    "alternative-model-combinations",
+    "community",
+    "citation",
+    "star-history",
+    "acknowledgements",
+    "license",
+    "prerequisites",
+    "install-skills",
+    "gpu-server-setup",
+    "alt-a-glm--gpt",
+    "-optional-gpt-54-pro-via-oracle",
+    "-research-wiki--persistent-research-memory",
+)
+
+
+def skill_names(root: Path) -> set[str]:
+    return {path.parent.name for path in root.glob("*/SKILL.md")}
+
+
+def allowed_tools(text: str) -> list[str]:
+    """Tokens on the frontmatter `allowed-tools:` line (empty if absent)."""
+    match = re.search(r"^allowed-tools:\s*(.+)$", text, flags=re.MULTILINE)
+    if not match:
+        return []
+    return [tok.strip() for tok in match.group(1).split(",") if tok.strip()]
+
+
+def frontmatter_split(text: str) -> str:
+    """Return the body after a leading YAML frontmatter block (whole text if
+    no frontmatter). Anchors on the opening `---` fence and the first closing
+    `---` fence, so `---` horizontal rules later in the body are not mistaken
+    for the frontmatter boundary."""
+    match = re.match(r"^---\n.*?\n---\n", text, flags=re.DOTALL)
+    return text[match.end():] if match else text
+
+
+def readme_anchors(text: str) -> set[str]:
+    return set(re.findall(r'<a id="([^"]+)"></a>', text))
+
+
+def numbered_h2_count(text: str) -> int:
+    return len(re.findall(r"^## \d+\.\s", text, flags=re.MULTILINE))
+
+
+def read(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def catalog_names() -> set[str]:
+    text = read(CATALOG)
+    return set(re.findall(r"\[`/([^`]+)`\]\(\.\./skills/[^)]+/SKILL\.md\)", text))
+
+
+def require(condition: bool, message: str, failures: list[str]) -> None:
+    if not condition:
+        failures.append(message)
+
+
+def require_count(path: Path, text: str, pattern: str, expected_count: int, failures: list[str]) -> None:
+    match = re.search(pattern, text)
+    rel = path.relative_to(REPO_ROOT)
+    if match is None:
+        failures.append(f"{rel} is missing live count pattern: {pattern}")
+        return
+    actual = int(match.group("count"))
+    if actual != expected_count:
+        failures.append(f"{rel} reports {actual} skills; expected {expected_count}")
+
+
+def check_inventory() -> list[str]:
+    failures: list[str] = []
+    main = skill_names(SKILLS_ROOT)
+    codex = skill_names(CODEX_ROOT)
+    catalog = catalog_names()
+    main_refs = {path.name for path in (SKILLS_ROOT / "shared-references").glob("*.md")}
+    codex_refs = {path.name for path in (CODEX_ROOT / "shared-references").glob("*.md")}
+
+    missing_codex = sorted(main - codex)
+    extra_codex = sorted(codex - main)
+    missing_catalog = sorted(main - catalog)
+    extra_catalog = sorted(catalog - main)
+
+    require(not missing_codex, f"missing Codex mirrors: {', '.join(missing_codex)}", failures)
+    require(not extra_codex, f"unexpected Codex-only skills: {', '.join(extra_codex)}", failures)
+    require(
+        not (main_refs - codex_refs),
+        f"missing Codex shared references: {', '.join(sorted(main_refs - codex_refs))}",
+        failures,
+    )
+    require(
+        not (codex_refs - main_refs),
+        f"unexpected Codex-only shared references: {', '.join(sorted(codex_refs - main_refs))}",
+        failures,
+    )
+    require(not missing_catalog, f"missing catalog entries: {', '.join(missing_catalog)}", failures)
+    require(not extra_catalog, f"catalog entries without mainline skills: {', '.join(extra_catalog)}", failures)
+
+    catalog_text = read(CATALOG)
+    readme = read(README)
+    readme_cn = read(README_CN)
+    agent_guide = read(AGENT_GUIDE)
+    aris_intro = read(ARIS_INTRO)
+    aris_intro_html = read(ARIS_INTRO_HTML)
+    codex_readme = read(CODEX_README)
+    codex_readme_cn = read(CODEX_README_CN)
+
+    expected_count = len(main)
+    count_checks = [
+        (CATALOG, catalog_text, r"\*\*(?P<count>\d+) skills\*\*"),
+        (AGENT_GUIDE, agent_guide, r"Full catalog.*?\*\*(?P<count>\d+) skills\*\*"),
+        (ARIS_INTRO, aris_intro, r"collection of \*\*(?P<count>\d+) composable Claude Code skills\*\*"),
+        (ARIS_INTRO, aris_intro, r"## The (?P<count>\d+) Skills"),
+        (ARIS_INTRO, aris_intro, r"一组 (?P<count>\d+) 个可组合的 Claude Code skills"),
+        (ARIS_INTRO_HTML, aris_intro_html, r"collection of <strong>(?P<count>\d+) composable Claude Code skills</strong>"),
+        (ARIS_INTRO_HTML, aris_intro_html, r'id="the-(?P<count>\d+)-skills"'),
+        (ARIS_INTRO_HTML, aris_intro_html, r"一组 (?P<count>\d+) 个可组合的 Claude Code skills"),
+        (CODEX_README, codex_readme, r"all `(?P<count>\d+)` mainline skills"),
+        (CODEX_README_CN, codex_readme_cn, r"`(?P<count>\d+)`[^\n]*skill"),
+    ]
+    for path, text, pattern in count_checks:
+        require_count(path, text, pattern, expected_count, failures)
+
+    for skill_file in sorted(CODEX_ROOT.glob("*/SKILL.md")):
+        if skill_file.read_bytes().startswith(BOM):
+            failures.append(f"{skill_file.relative_to(REPO_ROOT)} starts with UTF-8 BOM before frontmatter")
+        text = read(skill_file)
+        for forbidden in FORBIDDEN_CODEX_REVIEWER_STRINGS:
+            if forbidden in text:
+                failures.append(f"{skill_file.relative_to(REPO_ROOT)} contains forbidden reviewer string: {forbidden}")
+
+    # Root READMEs on this distribution branch are the dsh ones and carry no
+    # skill counts, anchors, or numbered sections; the full-ARIS README checks
+    # live on main.
+
+    # Agent-grant hygiene (WB2): `Agent` in allowed-tools is the Tier-2
+    # fan-out capability gate. Per shared-references/fan-out-pattern.md it is
+    # granted ONLY to skills that actually fan out, and such skills MUST cite
+    # the convention doc in their body. A grant without that citation is a
+    # vestigial/boilerplate grant and fails the drift check.
+    for skill_file in sorted(SKILLS_ROOT.glob("*/SKILL.md")):
+        text = read(skill_file)
+        if "Agent" not in allowed_tools(text):
+            continue
+        if "fan-out-pattern.md" not in frontmatter_split(text):
+            rel = skill_file.relative_to(REPO_ROOT)
+            failures.append(
+                f"{rel} grants `Agent` in allowed-tools but its body does not "
+                f"cite fan-out-pattern.md — vestigial grant or undocumented "
+                f"fan-out (see shared-references/fan-out-pattern.md)"
+            )
+
+    # Watchdog 'loop' task type ⇔ its documented trigger (A2). Mirrors the Agent-grant⇒cite
+    # rule above: a feature with no documented trigger is dead weight, a documented trigger
+    # for a missing feature is a broken pointer. The loop type is a shipped feature, so BOTH
+    # must be present.
+    watchdog_py = read(REPO_ROOT / "tools" / "watchdog.py")
+    ext_cadence = read(SKILLS_ROOT / "shared-references" / "external-cadence.md")
+    tool_loop = bool(re.search(r"def check_loop\b", watchdog_py)) and bool(re.search(r'==\s*"loop"', watchdog_py))
+    doc_loop = bool(re.search(r'"type"\s*:\s*"loop"', ext_cadence))
+    require(tool_loop, "tools/watchdog.py must implement the loop-liveness check_loop (A2)", failures)
+    require(doc_loop, "external-cadence.md must document registering a watchdog 'loop' task — its trigger (A2)", failures)
+
+    # iteration_log.py (stall→pivot, B) must exist AND be both documented (the ladder with
+    # both thresholds) and actually wired into a heartbeat consumer — else it is dead code.
+    # Same dead-code guard as the Agent-grant⇒cite rule above.
+    extc = read(SKILLS_ROOT / "shared-references" / "external-cadence.md")
+    rp = read(SKILLS_ROOT / "research-pipeline" / "SKILL.md")
+    tool_stall = (REPO_ROOT / "tools" / "iteration_log.py").is_file()
+    doc_ladder = bool(re.search(r"forced structural pivot", extc, re.IGNORECASE)) and \
+        bool(re.search(r"stale_count`?\s*>=\s*2", extc)) and bool(re.search(r"stale_count`?\s*>=\s*4", extc))
+    # Prove the wiring is real (not a prose mention): resolver chain + note invocation +
+    # both pivot branches handled in research-pipeline.
+    wired = ('iteration_log.py' in rp and 'ITER_LOG' in rp
+             and re.search(r'"\$ITER_LOG"\s+note', rp) is not None
+             and 'pivot' in rp and 'structural' in rp and 'human' in rp)
+    require(tool_stall, "tools/iteration_log.py (stall→pivot, B) must exist", failures)
+    require(doc_ladder, "external-cadence.md must document the stall ladder with both thresholds (>=2 structural, >=4 human) (B)", failures)
+    require(wired, "research-pipeline/SKILL.md must actually wire iteration_log.py (resolver + `$ITER_LOG note` + pivot handling) — not just mention it (B)", failures)
+
+    # research_wiki.py add_claim (claim layer) ⇔ its documented birth trigger in
+    # /proof-checker. add_claim is a writer; without a skill that calls it, the claim
+    # layer is dead code (the exact orphan-writer trap). Same dead-code guard as above:
+    # the writer and its single birth point must BOTH be present.
+    rwiki = read(REPO_ROOT / "tools" / "research_wiki.py")
+    pchk = read(SKILLS_ROOT / "proof-checker" / "SKILL.md")
+    tool_claim = bool(re.search(r"def add_claim\b", rwiki)) and bool(re.search(r'add_parser\("add_claim"', rwiki))
+    # Prove the trigger is real (anchored to the actual command line, not a prose
+    # mention or comment): proof-checker must literally invoke the resolved helper.
+    born = re.search(r'python3\s+"\$WIKI_SCRIPT"\s+add_claim\b', pchk) is not None
+    require(tool_claim, "tools/research_wiki.py must implement the add_claim claim-layer writer + its CLI", failures)
+    require(born, "proof-checker/SKILL.md must invoke `add_claim` as the claim birth point — not just mention it (else add_claim is an orphan writer)", failures)
+
+    # research_wiki.py upsert_idea (idea layer) ⇔ its documented write-back in
+    # /idea-creator Phase 7. Same orphan-writer guard: the deterministic idea writer
+    # and the skill that calls it must BOTH be present, anchored to the real command.
+    icreator = read(SKILLS_ROOT / "idea-creator" / "SKILL.md")
+    tool_idea = bool(re.search(r"def upsert_idea\b", rwiki)) and bool(re.search(r'add_parser\("upsert_idea"', rwiki))
+    idea_written = re.search(r'python3\s+"\$WIKI_SCRIPT"\s+upsert_idea\b', icreator) is not None
+    require(tool_idea, "tools/research_wiki.py must implement the upsert_idea idea-layer writer + its CLI", failures)
+    require(idea_written, "idea-creator/SKILL.md must invoke `upsert_idea` to record ideas (Phase 7) — not just mention it (else ideas are written freehand and skipped on re-gen)", failures)
+
+    # research_wiki.py add_experiment (experiment layer) ⇔ its write-back in
+    # /result-to-claim Step 5. Same orphan-writer guard; closes the last freehand
+    # wiki layer so the supports/invalidates edges never dangle off a missing exp node.
+    r2c = read(SKILLS_ROOT / "result-to-claim" / "SKILL.md")
+    tool_exp = bool(re.search(r"def add_experiment\b", rwiki)) and bool(re.search(r'add_parser\("add_experiment"', rwiki))
+    exp_written = re.search(r'python3\s+"\$WIKI_SCRIPT"\s+add_experiment\b', r2c) is not None
+    require(tool_exp, "tools/research_wiki.py must implement the add_experiment experiment-layer writer + its CLI", failures)
+    require(exp_written, "result-to-claim/SKILL.md must invoke `add_experiment` to create the experiment node (Step 5) — not just mention it (else exp pages are freehand and supports/invalidates edges dangle)", failures)
+
+    return failures
+
+
+def main() -> int:
+    failures = check_inventory()
+    if failures:
+        print("ARIS skill inventory drift detected:", file=sys.stderr)
+        for failure in failures:
+            print(f"- {failure}", file=sys.stderr)
+        return 1
+    print("ARIS skill inventory is consistent.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/tools/convert_skills_to_llm_chat.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""Convert Codex-native skills to llm-chat MCP compatible versions.
+
+Reads skills from a source directory, replaces all mcp__codex__codex and
+mcp__codex__codex-reply references with mcp__llm-chat__chat, removes
+Codex-specific parameters, and writes the converted files to a target
+directory. Works on Windows, macOS, and Linux.
+
+Usage:
+    # Convert all skills to ~/.claude/skills/
+    python convert_skills_to_llm_chat.py
+
+    # Custom source and target
+    python convert_skills_to_llm_chat.py --source ./skills --target ./skills-llm-chat
+
+    # Preview changes without writing files
+    python convert_skills_to_llm_chat.py --dry-run
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import sys
+from pathlib import Path
+
+
+# ── Codex → llm-chat text replacements ──────────────────────────────────
+
+# Tool name replacements
+REPLACEMENTS_TEXT: list[tuple[str, str]] = [
+    # Tool names
+    ("mcp__codex__codex-reply", "mcp__llm-chat__chat"),
+    ("mcp__codex__codex", "mcp__llm-chat__chat"),
+    # Description text
+    ("Always pin `model: gpt-5.6-sol` + `config: {\"model_reasoning_effort\": \"ultra\"}` (deep-audit tier).",
+     "Ask the LLM reviewer for its strictest, deepest review (deep-audit tier)."),
+    ("for new review threads\n  (`model: gpt-5.6-sol`, `config: {\"model_reasoning_effort\": \"ultra\"}`).",
+     "for new review threads."),
+    ("`model: gpt-5.6-sol`, `reasoning: ultra`", "the configured `LLM_MODEL`, deepest available reasoning"),
+    ("- **ALWAYS use `config: {\"model_reasoning_effort\": \"xhigh\"}`** for all Codex review calls.",
+     "- **Always ask the LLM reviewer for strict, high-rigor feedback** in every review round."),
+    ("ALWAYS pin `model: gpt-5.6-sol` + `config: {\"model_reasoning_effort\": \"ultra\"}` for reviews (deep-audit tier; capability fallback per `reviewer-routing.md`, never below `xhigh`)",
+     "ALWAYS ask the LLM reviewer for strict, maximum-depth review"),
+    ("Always use `model_reasoning_effort: \"xhigh\"` for maximum analysis depth.",
+     "Always ask the LLM reviewer for maximum analysis depth."),
+    ("(`gpt-5.6-sol` via Codex MCP)", "(via llm-chat MCP)"),
+    ("override the default reviewer (`gpt-5.6-sol`)", "override the default reviewer"),
+    ("via GPT-5.6-Sol xhigh review", "via llm-chat MCP review"),
+    ("via GPT-5.6-Sol ultra review", "via llm-chat MCP review"),
+    ("GPT-5.6-Sol xhigh", "LLM reviewer"),
+    ("GPT-5.6-Sol ultra", "LLM reviewer"),
+    ("via GPT-5.5 xhigh review", "via llm-chat MCP review"),
+    ("GPT-5.5 xhigh", "LLM reviewer"),
+    ("a second Codex agent", "an LLM via llm-chat MCP"),
+    ("secondary Codex agent", "LLM reviewer via llm-chat MCP"),
+    ("Codex agent", "LLM reviewer"),
+    ("- ALWAYS use `config: {\"model_reasoning_effort\": \"xhigh\"}` for maximum reasoning depth",
+     "- ALWAYS ask the LLM reviewer for maximum reasoning depth"),
+    ("pin `model: gpt-5.6-sol` + `config: {\"model_reasoning_effort\": \"xhigh\"}` per `../shared-references/reviewer-routing.md`",
+     "ask for strict, high-rigor review"),
+    ("pin `model: gpt-5.6-sol` + `config: {\"model_reasoning_effort\": \"ultra\"}` (deep-audit tier)",
+     "ask for strict, maximum-depth review"),
+    ("with `model: gpt-5.6-sol`, `config: {model_reasoning_effort: xhigh}`, `sandbox: read-only`, fresh thread",
+     "with a fresh thread"),
+    ("with `model: gpt-5.6-sol`, `config: {model_reasoning_effort: ultra}`, `sandbox: read-only`, fresh thread",
+     "with a fresh thread"),
+    ("model_reasoning_effort: \"ultra\"", "# (reasoning effort not supported by llm-chat)"),
+    ("model_reasoning_effort: \"xhigh\"", "# (reasoning effort not supported by llm-chat)"),
+    ("model_reasoning_effort: ultra", "# (reasoning effort not supported by llm-chat)"),
+    ("model_reasoning_effort: xhigh", "# (reasoning effort not supported by llm-chat)"),
+    ("reasoning_effort: ultra", "# (reasoning effort not supported by llm-chat)"),
+    ("reasoning_effort: xhigh", "# (reasoning effort not supported by llm-chat)"),
+    ("reasoning_effort: high", "# (reasoning effort not supported by llm-chat)"),
+]
+
+# Regex patterns for structural changes
+CONFIG_LINE_RE = re.compile(
+    r'^(\s*)(?:- )?`?config`?:\s*\{[^}]*model_reasoning_effort[^}]*\}`?\s*$',
+    re.MULTILINE,
+)
+MODEL_LINE_RE = re.compile(
+    r'^(\s*)(?:- )?`?"?model"?`?:\s*(?:["\'`]?gpt-[^\s"\'`]+["\'`]?|REVIEWER_MODEL)\s*$',
+    re.MULTILINE,
+)
+THREAD_ID_LINE_RE = re.compile(
+    r'^(\s*)threadId:\s*\S+.*$',
+    re.MULTILINE,
+)
+APPROVAL_POLICY_LINE_RE = re.compile(
+    r'^(\s*)approval-policy:\s*\S+.*$',
+    re.MULTILINE,
+)
+SANDBOX_LINE_RE = re.compile(
+    r'^(\s*)sandbox:\s*\S+.*$',
+    re.MULTILINE,
+)
+BASE_INSTRUCTIONS_LINE_RE = re.compile(
+    r'^(\s*)base-instructions:\s*["\'].*$',
+    re.MULTILINE,
+)
+DEVELOPER_INSTRUCTIONS_LINE_RE = re.compile(
+    r'^(\s*)developer-instructions:\s*["\'].*$',
+    re.MULTILINE,
+)
+# Match "prompt:" as a parameter name under mcp tool blocks
+PROMPT_PARAM_RE = re.compile(
+    r'^(\s*)prompt:\s*\|',
+    re.MULTILINE,
+)
+
+
+def convert_content(text: str) -> str:
+    """Apply all Codex → llm-chat conversions to skill content."""
+
+    # 1. Simple text replacements
+    for old, new in REPLACEMENTS_TEXT:
+        text = text.replace(old, new)
+
+    # 1b. Deduplicate mcp tool names in allowed-tools / tool references
+    text = re.sub(
+        r'(mcp__llm-chat__chat),\s*mcp__llm-chat__chat',
+        r'\1',
+        text,
+    )
+
+    # 2. Remove Codex-specific parameter lines
+    for pattern in (
+        CONFIG_LINE_RE,
+        MODEL_LINE_RE,
+        THREAD_ID_LINE_RE,
+        APPROVAL_POLICY_LINE_RE,
+        SANDBOX_LINE_RE,
+        BASE_INSTRUCTIONS_LINE_RE,
+        DEVELOPER_INSTRUCTIONS_LINE_RE,
+    ):
+        text = pattern.sub('', text)
+
+    # 3. Rename "prompt:" → "prompt:" (llm-chat uses "prompt" too based on auto-review-loop-llm)
+    #    Actually llm-chat MCP accepts "prompt" as the main parameter, so no rename needed.
+    #    The auto-review-loop-llm reference skill uses "prompt:" parameter name.
+
+    # 4. Add conversion note after YAML frontmatter if not already present
+    note = (
+        "\n> **llm-chat conversion**: This skill has been auto-converted from Codex to "
+        "use `mcp__llm-chat__chat`. Multi-turn conversations are handled as single-turn "
+        "calls with manual context inclusion.\n"
+    )
+    if "llm-chat conversion" not in text:
+        # Insert after frontmatter
+        fm_end = text.find("---", text.find("---") + 3)
+        if fm_end != -1:
+            fm_end = text.find("\n", fm_end + 3)
+            if fm_end != -1:
+                text = text[:fm_end + 1] + note + text[fm_end + 1:]
+
+    # 5. Clean up multiple blank lines from removed lines
+    text = re.sub(r'\n{3,}', '\n\n', text)
+
+    return text
+
+
+def convert_file(src: Path, dst: Path) -> bool:
+    """Convert a single SKILL.md file. Returns True if changes were made."""
+    content = src.read_text(encoding="utf-8")
+    converted = convert_content(content)
+
+    if converted == content:
+        return False
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    dst.write_text(converted, encoding="utf-8")
+    return True
+
+
+def find_skills(source_dir: Path) -> list[Path]:
+    """Find all SKILL.md files under source_dir, excluding known variant dirs."""
+    skills = []
+    exclude_dirs = {
+        "skills-codex",
+        "skills-codex-claude-review",
+        "skills-codex-gemini-review",
+    }
+    for skill_md in sorted(source_dir.rglob("SKILL.md")):
+        # Skip variant skill directories
+        parts = skill_md.relative_to(source_dir).parts
+        if any(d in parts for d in exclude_dirs):
+            continue
+        # Skip skills that already use llm-chat
+        content = skill_md.read_text(encoding="utf-8")
+        if "mcp__llm-chat__chat" in content and "mcp__codex__codex" not in content:
+            continue
+        # Only include files that reference codex
+        if "mcp__codex__codex" not in content:
+            continue
+        skills.append(skill_md)
+    return skills
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Convert Codex-native skills to llm-chat MCP compatible versions."
+    )
+    parser.add_argument(
+        "--source",
+        type=Path,
+        default=None,
+        help="Source directory containing skill folders (default: repo skills/)",
+    )
+    parser.add_argument(
+        "--target",
+        type=Path,
+        default=None,
+        help="Target directory for converted skills (default: source, in-place)",
+    )
+    parser.add_argument(
+        "--force-in-place",
+        action="store_true",
+        help="Allow in-place conversion of the repo's canonical skills/ tree (dangerous)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview changes without writing files",
+    )
+    args = parser.parse_args()
+
+    # Default source: skills/ in the same repo as this script
+    repo_root = Path(__file__).resolve().parents[1]
+    source_dir = args.source or repo_root / "skills"
+    target_dir = args.target or source_dir  # in-place by default
+
+    # Refuse to rewrite the repo's canonical skill tree in place — that destroys
+    # the Codex-native sources (this exact accident has happened). Convert INTO
+    # a separate --target, or pass --force-in-place if you really mean it.
+    canonical = (repo_root / "skills").resolve()
+    tgt = target_dir.resolve()
+    if (tgt == canonical or canonical in tgt.parents) \
+            and not args.dry_run and not args.force_in_place:
+        print("Error: refusing to convert the repo's canonical skills/ tree in place.")
+        print("Pass --target <dir> (recommended) or --force-in-place to override.")
+        sys.exit(1)
+
+    if not source_dir.exists():
+        print(f"Error: source directory not found: {source_dir}")
+        sys.exit(1)
+
+    skills = find_skills(source_dir)
+    if not skills:
+        print("No Codex-based skills found to convert.")
+        return
+
+    print(f"Found {len(skills)} skill(s) to convert:\n")
+
+    converted = 0
+    for skill_path in skills:
+        rel = skill_path.relative_to(source_dir)
+        dst = target_dir / rel
+
+        if args.dry_run:
+            content = skill_path.read_text(encoding="utf-8")
+            new_content = convert_content(content)
+            has_changes = content != new_content
+            status = "would convert" if has_changes else "no changes"
+            print(f"  [DRY-RUN] {rel} — {status}")
+            if has_changes:
+                converted += 1
+        else:
+            if convert_file(skill_path, dst):
+                print(f"  Converted: {rel}")
+                converted += 1
+            else:
+                print(f"  No changes: {rel}")
+
+    print(f"\nDone: {converted}/{len(skills)} skill(s) converted.")
+    if args.dry_run:
+        print("(dry-run mode — no files were written)")
+
+
+if __name__ == "__main__":
+    main()