Skill Authoring skill for Claude Code

#!/usr/bin/env python3
"""Validate an Agent Skill folder (SKILL.md frontmatter, links, size).

Usage:
    python3 validate_skill.py <skill-folder> [--portable]

--portable  also enforce claude.ai / API upload rules (only portable frontmatter
            keys, no "claude"/"anthropic" in the name).

Exit code 0 when there are no errors (warnings allowed), 1 otherwise.
Standard library only.
"""
from __future__ import annotations

import re
import sys
from pathlib import Path

PORTABLE_KEYS = {"name", "description", "license", "compatibility", "metadata", "allowed-tools"}
CLAUDE_CODE_KEYS = {
    "when_to_use", "argument-hint", "arguments", "disable-model-invocation",
    "user-invocable", "disallowed-tools", "model", "effort", "context", "agent",
    "hooks", "paths", "shell",
}
NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
LINK_RE = re.compile(r"\]\(([^)#\s]+)(?:#[^)]*)?\)")
SCRIPT_REF_RE = re.compile(r"(?:\$\{CLAUDE_SKILL_DIR\}/)?((?:scripts|references|assets)/[\w./-]+)")


def parse_frontmatter(text: str) -> tuple[dict[str, str], str, list[str]]:
    """Minimal YAML subset parser: top-level `key: value`, block scalars, nested maps skipped."""
    errors: list[str] = []
    if not text.startswith("---"):
        return {}, text, ["SKILL.md must start with '---' frontmatter"]
    parts = text.split("\n")
    try:
        end = next(i for i in range(1, len(parts)) if parts[i].strip() == "---")
    except StopIteration:
        return {}, text, ["frontmatter is not closed with '---'"]
    fm_lines = parts[1:end]
    body = "\n".join(parts[end + 1:])
    data: dict[str, str] = {}
    key = None
    block: list[str] | None = None
    for raw in fm_lines:
        if block is not None and (raw.startswith((" ", "\t")) or not raw.strip()):
            block.append(raw.strip())
            continue
        if block is not None and key:
            data[key] = " ".join(x for x in block if x)
            block = None
        if not raw.strip() or raw.lstrip().startswith("#"):
            continue
        if raw.startswith((" ", "\t", "-")):
            continue  # nested map / list content (metadata, hooks) - not validated here
        m = re.match(r"^([A-Za-z0-9_-]+):(.*)$", raw)
        if not m:
            errors.append(f"unparseable frontmatter line: {raw!r}")
            continue
        key, val = m.group(1), m.group(2).strip()
        if val in (">", "|", ">-", "|-", ">+", "|+"):
            block = []
            continue
        if val and val[0] in "\"'":
            if len(val) < 2 or val[-1] != val[0]:
                errors.append(f"{key}: unterminated quoted value")
            val = val[1:-1]
        elif ": " in val:
            errors.append(f"{key}: unquoted value contains ': ' (invalid YAML); wrap it in double quotes")
        data[key] = val
    if block is not None and key:
        data[key] = " ".join(x for x in block if x)
    return data, body, errors


def main() -> int:
    args = [a for a in sys.argv[1:] if not a.startswith("--")]
    portable = "--portable" in sys.argv
    if len(args) != 1:
        print(__doc__.strip())
        return 2
    folder = Path(args[0]).resolve()
    skill = folder / "SKILL.md"
    errors: list[str] = []
    warnings: list[str] = []
    if not skill.is_file():
        print(f"ERROR: {skill} not found")
        return 1

    text = skill.read_text(encoding="utf-8")
    fm, body, parse_errors = parse_frontmatter(text)
    errors += parse_errors

    name = fm.get("name", "")
    desc = fm.get("description", "")
    if not name:
        errors.append("missing 'name'")
    else:
        if not NAME_RE.match(name) or len(name) > 64:
            errors.append(f"name {name!r} must be 1-64 chars of lowercase letters, digits, single hyphens")
        if name != folder.name:
            errors.append(f"name {name!r} does not match folder {folder.name!r}")
        if re.search(r"claude|anthropic", name):
            (errors if portable else warnings).append(
                f"name {name!r} contains a reserved word; claude.ai/API uploads reject it")
    if not desc:
        errors.append("missing 'description'")
    else:
        if len(desc) > 1024:
            errors.append(f"description is {len(desc)} chars (max 1024)")
        elif len(desc) < 100:
            warnings.append(f"description is only {len(desc)} chars; add concrete triggers")
        if re.search(r"<[A-Za-z/][^>]*>", desc):
            errors.append("description contains XML/HTML-like tags")
        if not re.search(r"\buse (it )?(when|for|if)\b", desc, re.I):
            warnings.append("description has no 'Use when ...' trigger clause")
        if re.match(r"^(helps|a skill|this skill|useful)", desc, re.I):
            warnings.append("description opens vaguely; start with what it does")

    for key in fm:
        if key in PORTABLE_KEYS:
            continue
        if key in CLAUDE_CODE_KEYS:
            if portable:
                errors.append(f"key {key!r} is Claude Code-only; claude.ai/API uploads reject it")
        else:
            warnings.append(f"unknown frontmatter key {key!r}")

    body_lines = body.strip("\n").count("\n") + 1 if body.strip() else 0
    approx_tokens = len(body) // 4
    if body_lines == 0:
        errors.append("SKILL.md body is empty")
    elif body_lines > 500:
        errors.append(f"body is {body_lines} lines (keep under 500; move depth to references/)")
    elif body_lines > 350:
        warnings.append(f"body is {body_lines} lines; consider moving branch-only detail to references/")
    if approx_tokens > 5000:
        warnings.append(f"body is ~{approx_tokens} tokens (target < 5000)")

    # Links in prose must resolve (error). Paths inside code may be examples (warning).
    prose = re.sub(r"```.*?```", "", body, flags=re.S)
    prose = re.sub(r"`[^`\n]*`", "", prose)
    checked: set[str] = set()
    candidates = [(t, True) for t in LINK_RE.findall(prose)]
    candidates += [(t, False) for t in LINK_RE.findall(body) + SCRIPT_REF_RE.findall(body)]
    for target, strict in candidates:
        target = target.rstrip(".,)")
        if target.startswith(("http://", "https://", "mailto:")) or target in checked:
            continue
        checked.add(target)
        path = (folder / target).resolve()
        if folder not in path.parents and path != folder:
            warnings.append(f"reference points outside the skill folder: {target}")
        elif not path.exists():
            if strict:
                errors.append(f"linked file does not exist: {target}")
            else:
                warnings.append(f"path mentioned in code does not exist (fine if it is an example): {target}")

    for sub in ("references", "scripts", "assets"):
        d = folder / sub
        if d.is_dir():
            for p in d.rglob("*"):
                if p.is_file() and len(p.relative_to(d).parts) > 1 and sub == "references":
                    warnings.append(f"nested reference {p.relative_to(folder)}; keep references one level deep")
                if p.is_file() and sub != "assets" and f"{sub}/{p.name}" not in body:
                    warnings.append(f"{sub}/{p.name} is never mentioned in SKILL.md, so Claude will not use it")

    print(f"Skill: {name or '?'}  ({folder})")
    print(f"  description: {len(desc)} chars   body: {body_lines} lines, ~{approx_tokens} tokens")
    for e in errors:
        print(f"  ERROR   {e}")
    for w in warnings:
        print(f"  WARNING {w}")
    print(f"Result: {'FAIL' if errors else 'PASS'} ({len(errors)} errors, {len(warnings)} warnings)")
    return 1 if errors else 0


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