|
| 1 | +#!/usr/bin/env python3 |
| 2 | + |
| 3 | +from __future__ import annotations |
| 4 | + |
| 5 | +import argparse |
| 6 | +import html |
| 7 | +import re |
| 8 | +import sys |
| 9 | +from dataclasses import dataclass |
| 10 | +from pathlib import Path |
| 11 | + |
| 12 | +try: |
| 13 | + import yaml # type: ignore |
| 14 | +except Exception: # pragma: no cover - optional dependency |
| 15 | + yaml = None |
| 16 | + |
| 17 | + |
| 18 | +@dataclass(frozen=True) |
| 19 | +class SkillMetadata: |
| 20 | + name: str |
| 21 | + description: str |
| 22 | + skill_md: Path |
| 23 | + |
| 24 | + |
| 25 | +class SkillMetadataError(Exception): |
| 26 | + pass |
| 27 | + |
| 28 | + |
| 29 | +def _parse_frontmatter(skill_md: Path) -> tuple[str, str]: |
| 30 | + text = skill_md.read_text(encoding="utf-8") |
| 31 | + lines = text.splitlines() |
| 32 | + if not lines or lines[0].strip() != "---": |
| 33 | + raise SkillMetadataError("Missing YAML frontmatter start ('---') at line 1.") |
| 34 | + |
| 35 | + end_index = None |
| 36 | + for i in range(1, len(lines)): |
| 37 | + if lines[i].strip() == "---": |
| 38 | + end_index = i |
| 39 | + break |
| 40 | + if end_index is None: |
| 41 | + raise SkillMetadataError("Missing YAML frontmatter end ('---').") |
| 42 | + |
| 43 | + frontmatter_text = "\n".join(lines[1:end_index]).strip() |
| 44 | + |
| 45 | + if yaml is not None: |
| 46 | + try: |
| 47 | + data = yaml.safe_load(frontmatter_text) or {} |
| 48 | + except Exception as e: |
| 49 | + raise SkillMetadataError(f"Invalid YAML frontmatter: {e}") from e |
| 50 | + |
| 51 | + if not isinstance(data, dict): |
| 52 | + raise SkillMetadataError("YAML frontmatter must be a mapping (key/value object).") |
| 53 | + |
| 54 | + name_value = data.get("name") |
| 55 | + description_value = data.get("description") |
| 56 | + |
| 57 | + if not isinstance(name_value, str) or not name_value.strip(): |
| 58 | + raise SkillMetadataError("Missing YAML 'name'.") |
| 59 | + if not isinstance(description_value, str) or not description_value.strip(): |
| 60 | + raise SkillMetadataError("Missing YAML 'description'.") |
| 61 | + |
| 62 | + if "\n" in name_value or "\r" in name_value: |
| 63 | + raise SkillMetadataError("YAML 'name' must be a single line.") |
| 64 | + if "\n" in description_value or "\r" in description_value: |
| 65 | + raise SkillMetadataError("YAML 'description' must be a single line.") |
| 66 | + |
| 67 | + return name_value, description_value |
| 68 | + |
| 69 | + # Fallback parser (no PyYAML installed): only supports single-line `key: value` scalars. |
| 70 | + name_value: str | None = None |
| 71 | + description_value: str | None = None |
| 72 | + |
| 73 | + for raw in lines[1:end_index]: |
| 74 | + line = raw.strip() |
| 75 | + if not line or line.startswith("#"): |
| 76 | + continue |
| 77 | + |
| 78 | + match = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", line) |
| 79 | + if not match: |
| 80 | + continue |
| 81 | + key, value = match.group(1), match.group(2).strip() |
| 82 | + |
| 83 | + if value in {"|", ">", "|-", ">-"}: |
| 84 | + raise SkillMetadataError( |
| 85 | + f"Unsupported multi-line YAML value for '{key}'. Use a single-line scalar." |
| 86 | + ) |
| 87 | + |
| 88 | + if len(value) >= 2 and value[0] in {"'", '"'} and value[-1] == value[0]: |
| 89 | + value = value[1:-1] |
| 90 | + |
| 91 | + if key == "name": |
| 92 | + name_value = value |
| 93 | + elif key == "description": |
| 94 | + description_value = value |
| 95 | + |
| 96 | + if not name_value: |
| 97 | + raise SkillMetadataError("Missing YAML 'name'.") |
| 98 | + if not description_value: |
| 99 | + raise SkillMetadataError("Missing YAML 'description'.") |
| 100 | + |
| 101 | + return name_value, description_value |
| 102 | + |
| 103 | + |
| 104 | +def _collect_skills(skills_root: Path) -> list[SkillMetadata]: |
| 105 | + skills: list[SkillMetadata] = [] |
| 106 | + for child in sorted(skills_root.iterdir()): |
| 107 | + if not child.is_dir(): |
| 108 | + continue |
| 109 | + skill_md = child / "SKILL.md" |
| 110 | + if not skill_md.exists(): |
| 111 | + continue |
| 112 | + name, description = _parse_frontmatter(skill_md) |
| 113 | + skills.append(SkillMetadata(name=name, description=description, skill_md=skill_md)) |
| 114 | + return sorted(skills, key=lambda s: s.name) |
| 115 | + |
| 116 | + |
| 117 | +def _detect_skills_dir() -> str: |
| 118 | + candidates = (Path(".codex/skills"), Path(".claude/skills"), Path("skills")) |
| 119 | + |
| 120 | + def contains_skills(dir_path: Path) -> bool: |
| 121 | + if not dir_path.exists() or not dir_path.is_dir(): |
| 122 | + return False |
| 123 | + for child in dir_path.iterdir(): |
| 124 | + if not child.is_dir(): |
| 125 | + continue |
| 126 | + if (child / "SKILL.md").is_file(): |
| 127 | + return True |
| 128 | + return False |
| 129 | + |
| 130 | + for candidate in candidates: |
| 131 | + if contains_skills(candidate): |
| 132 | + return str(candidate) |
| 133 | + |
| 134 | + for candidate in candidates: |
| 135 | + if candidate.exists() and candidate.is_dir(): |
| 136 | + return str(candidate) |
| 137 | + |
| 138 | + return "skills" |
| 139 | + |
| 140 | + |
| 141 | +def main() -> int: |
| 142 | + parser = argparse.ArgumentParser( |
| 143 | + description="Generate an <available_skills> XML block from */SKILL.md metadata under a skills directory." |
| 144 | + ) |
| 145 | + parser.add_argument( |
| 146 | + "skills_dir", |
| 147 | + nargs="?", |
| 148 | + default=_detect_skills_dir(), |
| 149 | + help="Path to skills directory (default: auto-detect .codex/skills, .claude/skills, or ./skills).", |
| 150 | + ) |
| 151 | + parser.add_argument( |
| 152 | + "--absolute", |
| 153 | + action="store_true", |
| 154 | + help="Use absolute paths in <location> (recommended for filesystem-based agents).", |
| 155 | + ) |
| 156 | + args = parser.parse_args() |
| 157 | + |
| 158 | + skills_root = Path(args.skills_dir).resolve() |
| 159 | + if not skills_root.exists() or not skills_root.is_dir(): |
| 160 | + print(f"ERROR: Skills directory does not exist: {skills_root}", file=sys.stderr) |
| 161 | + return 2 |
| 162 | + |
| 163 | + try: |
| 164 | + skills = _collect_skills(skills_root) |
| 165 | + except SkillMetadataError as e: |
| 166 | + print(f"ERROR: {e}", file=sys.stderr) |
| 167 | + return 2 |
| 168 | + |
| 169 | + if not skills: |
| 170 | + print(f"ERROR: No skills found under: {skills_root}", file=sys.stderr) |
| 171 | + return 2 |
| 172 | + |
| 173 | + print("<available_skills>") |
| 174 | + for skill in skills: |
| 175 | + location = str(skill.skill_md.resolve() if args.absolute else skill.skill_md.relative_to(Path.cwd())) |
| 176 | + print(" <skill>") |
| 177 | + print(f" <name>{html.escape(skill.name)}</name>") |
| 178 | + print(f" <description>{html.escape(skill.description)}</description>") |
| 179 | + print(f" <location>{html.escape(location)}</location>") |
| 180 | + print(" </skill>") |
| 181 | + print("</available_skills>") |
| 182 | + |
| 183 | + return 0 |
| 184 | + |
| 185 | + |
| 186 | +if __name__ == "__main__": |
| 187 | + raise SystemExit(main()) |
0 commit comments