1#!/usr/bin/env python3
2"""
3Skill Validator - Validates a skill directory structure
4 
5Usage:
6    python validate_skill.py <path/to/skill-folder>
7 
8Example:
9    python validate_skill.py ./workspace/skills/my-skill
10"""
11 
12import re
13import sys
14from pathlib import Path
15 
16# Try to import yaml, fallback to basic parsing if not available
17try:
18    import yaml
19    HAS_YAML = True
20except ImportError:
21    HAS_YAML = False
22 
23 
24def extract_frontmatter(content: str) -> tuple:
25    """Extract YAML frontmatter from markdown content."""
26    if not content.startswith("---"):
27        return None, content
28 
29    # Find the closing ---
30    end_match = re.search(r"\n---\n", content[3:])
31    if not end_match:
32        return None, content
33 
34    frontmatter_text = content[3:end_match.start() + 3]
35    body = content[end_match.end() + 3:]
36 
37    if HAS_YAML:
38        try:
39            frontmatter = yaml.safe_load(frontmatter_text)
40        except yaml.YAMLError as e:
41            return {"_error": str(e)}, body
42    else:
43        # Basic parsing without yaml library
44        frontmatter = {}
45        for line in frontmatter_text.split("\n"):
46            if ":" in line:
47                key, value = line.split(":", 1)
48                frontmatter[key.strip()] = value.strip()
49 
50    return frontmatter, body
51 
52 
53def lint_warnings(frontmatter: dict, body: str) -> list:
54    """
55    Check for non-fatal issues and return warnings.
56    These are suggestions, not errors — the skill is still valid.
57    """
58    warnings = []
59 
60    # emoji at top level instead of inside metadata.starchild
61    if "emoji" in frontmatter:
62        meta = frontmatter.get("metadata")
63        has_starchild_emoji = (
64            isinstance(meta, dict)
65            and isinstance(meta.get("starchild"), dict)
66            and meta["starchild"].get("emoji")
67        )
68        if not has_starchild_emoji:
69            warnings.append(
70                "emoji is at top level — move it to metadata.starchild.emoji "
71                "so the loader picks it up correctly"
72            )
73 
74    # requires at top level instead of inside metadata.starchild
75    if "requires" in frontmatter:
76        meta = frontmatter.get("metadata")
77        has_starchild_requires = (
78            isinstance(meta, dict)
79            and isinstance(meta.get("starchild"), dict)
80            and meta["starchild"].get("requires")
81        )
82        if not has_starchild_requires:
83            warnings.append(
84                "requires is at top level — move it to metadata.starchild.requires "
85                "so the loader picks it up correctly"
86            )
87 
88    # any_bins used instead of anyBins (camelCase)
89    meta = frontmatter.get("metadata")
90    if isinstance(meta, dict):
91        sc = meta.get("starchild") or meta.get("openclaw")
92        if isinstance(sc, dict):
93            req = sc.get("requires")
94            if isinstance(req, dict) and "any_bins" in req:
95                warnings.append(
96                    "requires.any_bins should be requires.anyBins (camelCase) "
97                    "in metadata.starchild"
98                )
99 
100    # Also check top-level requires for any_bins
101    top_req = frontmatter.get("requires")
102    if isinstance(top_req, dict) and "any_bins" in top_req:
103        warnings.append(
104            "requires.any_bins should be requires.anyBins (camelCase)"
105        )
106 
107    # Description missing "Use when" trigger pattern
108    desc = frontmatter.get("description", "")
109    if desc and "[TODO" not in desc:
110        desc_lower = desc.lower()
111        if "use when" not in desc_lower and "use for" not in desc_lower:
112            warnings.append(
113                'description lacks a "Use when" trigger — consider adding '
114                '"Use when <specific scenarios>" to help the agent decide '
115                "when to activate this skill"
116            )
117 
118    return warnings
119 
120 
121def validate_skill(skill_path: Path) -> tuple:
122    """
123    Validate a skill directory.
124 
125    Returns:
126        (is_valid, message, warnings)
127    """
128    skill_path = Path(skill_path).resolve()
129 
130    # Check directory exists
131    if not skill_path.exists():
132        return False, f"Directory not found: {skill_path}", []
133 
134    if not skill_path.is_dir():
135        return False, f"Not a directory: {skill_path}", []
136 
137    # Check SKILL.md exists
138    skill_md = skill_path / "SKILL.md"
139    if not skill_md.exists():
140        return False, "SKILL.md not found", []
141 
142    # Read and parse SKILL.md
143    try:
144        content = skill_md.read_text(encoding="utf-8")
145    except Exception as e:
146        return False, f"Error reading SKILL.md: {e}", []
147 
148    # Extract frontmatter
149    frontmatter, body = extract_frontmatter(content)
150 
151    if frontmatter is None:
152        return False, "SKILL.md must start with YAML frontmatter (---)", []
153 
154    if "_error" in frontmatter:
155        return False, f"Invalid YAML frontmatter: {frontmatter['_error']}", []
156 
157    # Check required fields
158    if not frontmatter.get("name"):
159        return False, "Frontmatter missing required field: name", []
160 
161    if not frontmatter.get("description"):
162        return False, "Frontmatter missing required field: description", []
163 
164    # Check description is not placeholder
165    desc = frontmatter.get("description", "")
166    if "[TODO" in desc or not desc.strip():
167        return False, "Description contains TODO or is empty - please complete it", []
168 
169    # Check skill name format
170    name = frontmatter.get("name", "")
171    normalized = re.sub(r"[^a-z0-9-]", "", name.lower())
172    if name != normalized:
173        return False, f"Skill name should be lowercase hyphen-case: '{name}' -> '{normalized}'", []
174 
175    # Check body has content
176    if len(body.strip()) < 50:
177        return False, "SKILL.md body is too short (< 50 chars)", []
178 
179    # Collect lint warnings
180    warns = lint_warnings(frontmatter, body)
181 
182    # Warn about TODOs in body
183    todo_count = body.count("[TODO")
184    if todo_count > 0:
185        return True, f"Valid (but has {todo_count} TODO items remaining)", warns
186 
187    # Check line count
188    line_count = len(content.split("\n"))
189    if line_count > 500:
190        return True, f"Valid (but {line_count} lines - consider splitting to references/)", warns
191 
192    return True, "Valid skill", warns
193 
194 
195def main():
196    if len(sys.argv) < 2:
197        print("Usage: python validate_skill.py <path/to/skill-folder>")
198        print("\nExample:")
199        print("  python validate_skill.py ./workspace/skills/my-skill")
200        sys.exit(1)
201 
202    skill_path = sys.argv[1]
203    print(f"Validating skill: {skill_path}\n")
204 
205    is_valid, message, warnings = validate_skill(skill_path)
206 
207    if is_valid:
208        print(f"[OK] {message}")
209    else:
210        print(f"[ERROR] {message}")
211 
212    # Print warnings
213    for warn in warnings:
214        print(f"[WARN] {warn}")
215 
216    sys.exit(0 if is_valid else 1)
217 
218 
219if __name__ == "__main__":
220    main()
221