1#!/usr/bin/env python3
2"""Validate platform compatibility for the published Agent Skills corpus.
3 
4This script checks the parts of Cursor, Claude Code, Codex, and Open Plugins
5compatibility that are deterministic from the repository contents:
6 
7- Published skills are strict-YAML parseable and match Agent Skills naming rules.
8- Open Plugins and Claude marketplace manifests discover the same skill set.
9- Local/manual install layouts preserve `skill-name/SKILL.md` under the platform
10  skill roots documented by Cursor, Claude Code, and Codex.
11- If the upstream `agentskills` CLI from `skills-ref` is installed, each skill is
12  validated with the reference Agent Skills validator as well.
13"""
14 
15from __future__ import annotations
16 
17import argparse
18import json
19import re
20import shutil
21import subprocess
22import sys
23import tempfile
24from pathlib import Path
25from typing import Any
26 
27from skill_frontmatter import parse_frontmatter
28 
29 
30ROOT = Path(__file__).resolve().parents[2]
31PLATFORM_SKILL_ROOTS = [
32    ".cursor/skills",
33    ".claude/skills",
34    ".codex/skills",
35    ".agents/skills",
36]
37SKILL_NAME_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
38 
39 
40def error(message: str, errors: list[str]) -> None:
41    errors.append(message)
42 
43 
44def load_json(path: Path, errors: list[str]) -> dict[str, Any]:
45    try:
46        data = json.loads(path.read_text(encoding="utf-8"))
47    except (OSError, json.JSONDecodeError) as exc:
48        error(f"{path.relative_to(ROOT)}: {exc}", errors)
49        return {}
50    if not isinstance(data, dict):
51        error(f"{path.relative_to(ROOT)}: expected JSON object", errors)
52        return {}
53    return data
54 
55 
56def published_skill_dirs() -> list[Path]:
57    return sorted(path for path in (ROOT / "skills").iterdir() if (path / "SKILL.md").exists())
58 
59 
60def validate_skill_dir(skill_dir: Path, errors: list[str]) -> None:
61    skill_file = skill_dir / "SKILL.md"
62    if not skill_file.exists():
63        error(f"{skill_dir}: missing SKILL.md", errors)
64        return
65    data, issues = parse_frontmatter(skill_file.read_text(encoding="utf-8"))
66    for issue in issues:
67        error(f"{skill_file.relative_to(ROOT)}: {issue}", errors)
68    name = str(data.get("name", ""))
69    description = str(data.get("description", ""))
70    if name != skill_dir.name:
71        error(f"{skill_file.relative_to(ROOT)}: name {name!r} does not match directory {skill_dir.name!r}", errors)
72    if not SKILL_NAME_PATTERN.fullmatch(name):
73        error(f"{skill_file.relative_to(ROOT)}: name must be lowercase kebab-case without repeated hyphens", errors)
74    if len(description) > 1024:
75        error(f"{skill_file.relative_to(ROOT)}: description exceeds 1024 characters", errors)
76 
77 
78def validate_manifests(skill_names: list[str], errors: list[str]) -> None:
79    plugin_dir = ROOT / ".plugin"
80    plugin_path = plugin_dir / "plugin.json"
81    plugin = load_json(plugin_path, errors)
82    unexpected = sorted(path.name for path in plugin_dir.iterdir() if path.name != "plugin.json")
83    if unexpected:
84        error(f".plugin/ must contain only plugin.json, found: {unexpected}", errors)
85 
86    raw_skills = plugin.get("skills")
87    if isinstance(raw_skills, str):
88        skill_paths = [raw_skills]
89    elif isinstance(raw_skills, list) and all(isinstance(item, str) for item in raw_skills):
90        skill_paths = list(raw_skills)
91    else:
92        error(".plugin/plugin.json: skills must be a string or list of strings", errors)
93        skill_paths = []
94 
95    discovered: set[str] = set()
96    for raw_path in skill_paths:
97        path = Path(raw_path)
98        if not raw_path.startswith("./"):
99            error(f".plugin/plugin.json: skill path must start with './': {raw_path}", errors)
100            continue
101        if path.is_absolute() or ".." in path.parts:
102            error(f".plugin/plugin.json: skill path escapes plugin root: {raw_path}", errors)
103            continue
104        full_path = ROOT / raw_path
105        if not full_path.exists():
106            error(f".plugin/plugin.json: skill path does not exist: {raw_path}", errors)
107            continue
108        if (full_path / "SKILL.md").exists():
109            discovered.add(full_path.name)
110        elif full_path.is_dir():
111            discovered.update(path.name for path in full_path.iterdir() if (path / "SKILL.md").exists())
112        else:
113            error(f".plugin/plugin.json: skill path is not a directory: {raw_path}", errors)
114    if sorted(discovered) != skill_names:
115        error(f".plugin/plugin.json: discovered skills {sorted(discovered)} != corpus {skill_names}", errors)
116 
117    marketplace = load_json(ROOT / ".claude-plugin" / "marketplace.json", errors)
118    plugins = marketplace.get("plugins")
119    if not isinstance(plugins, list) or len(plugins) != 1:
120        error(".claude-plugin/marketplace.json: expected exactly one bundled plugin", errors)
121        return
122    entry = plugins[0]
123    if not isinstance(entry, dict):
124        error(".claude-plugin/marketplace.json: plugin entry must be an object", errors)
125        return
126    if entry.get("name") != plugin.get("name"):
127        error(".claude-plugin/marketplace.json: plugin name differs from .plugin/plugin.json", errors)
128    if entry.get("source") != "./":
129        error(".claude-plugin/marketplace.json: source must be './'", errors)
130    claude_skill_paths = entry.get("skills")
131    if not isinstance(claude_skill_paths, list) or not all(isinstance(item, str) for item in claude_skill_paths):
132        error(".claude-plugin/marketplace.json: skills must be a list of strings", errors)
133        return
134    claude_names = []
135    for raw_path in claude_skill_paths:
136        if not raw_path.startswith("./"):
137            error(f".claude-plugin/marketplace.json: skill path must start with './': {raw_path}", errors)
138            continue
139        path = ROOT / raw_path
140        if not (path / "SKILL.md").exists():
141            error(f".claude-plugin/marketplace.json: skill path missing SKILL.md: {raw_path}", errors)
142            continue
143        claude_names.append(path.name)
144    if sorted(claude_names) != skill_names:
145        error(f".claude-plugin/marketplace.json: discovered skills {sorted(claude_names)} != corpus {skill_names}", errors)
146 
147 
148def validate_platform_install_layouts(skill_dirs: list[Path], errors: list[str]) -> None:
149    with tempfile.TemporaryDirectory(prefix="skill-platform-compat-") as tmp:
150        root = Path(tmp)
151        for platform_root in PLATFORM_SKILL_ROOTS:
152            target_root = root / platform_root
153            target_root.mkdir(parents=True, exist_ok=True)
154            for skill_dir in skill_dirs:
155                target = target_root / skill_dir.name
156                shutil.copytree(skill_dir, target)
157                validate_skill_dir(target, errors)
158 
159 
160def run_reference_validator(skill_dirs: list[Path], require: bool, errors: list[str]) -> None:
161    agentskills = shutil.which("agentskills")
162    if agentskills is None:
163        if require:
164            error("agentskills CLI not found; install with `python -m pip install skills-ref`", errors)
165        return
166 
167    for skill_dir in skill_dirs:
168        completed = subprocess.run(
169            [agentskills, "validate", str(skill_dir)],
170            cwd=ROOT,
171            text=True,
172            capture_output=True,
173            check=False,
174        )
175        if completed.returncode != 0:
176            message = completed.stderr.strip() or completed.stdout.strip() or f"exit {completed.returncode}"
177            error(f"agentskills validate {skill_dir.relative_to(ROOT)} failed: {message}", errors)
178 
179 
180def main() -> int:
181    parser = argparse.ArgumentParser(description="Validate cross-platform Agent Skills compatibility")
182    parser.add_argument(
183        "--require-reference-validator",
184        action="store_true",
185        help="Fail if the official agentskills CLI from skills-ref is unavailable.",
186    )
187    args = parser.parse_args()
188 
189    errors: list[str] = []
190    skill_dirs = published_skill_dirs()
191    skill_names = sorted(path.name for path in skill_dirs)
192    if not skill_dirs:
193        error("no published skills found under skills/", errors)
194 
195    for skill_dir in skill_dirs:
196        validate_skill_dir(skill_dir, errors)
197    validate_manifests(skill_names, errors)
198    validate_platform_install_layouts(skill_dirs, errors)
199    run_reference_validator(skill_dirs, args.require_reference_validator, errors)
200 
201    if errors:
202        for item in errors:
203            print(f"ERROR: {item}", file=sys.stderr)
204        return 1
205 
206    print(
207        "Platform compatibility passed: "
208        f"{len(skill_dirs)} skills, {len(PLATFORM_SKILL_ROOTS)} local install layouts"
209    )
210    return 0
211 
212 
213if __name__ == "__main__":
214    raise SystemExit(main())
215