Skill Authoring skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Skill Authoring"
  short_description: "From repeated prompt to a skill that triggers"
  default_prompt: "$skill-authoring Turn our release checklist into a Codex skill"

#!/usr/bin/env python3
"""Lint an Agent Skill folder before installing or sharing it with Codex.

Checks the SKILL.md frontmatter against the Agent Skills specification
(name rules, description length, known keys), the body size, that every
relative file the body links to exists, that every bundled file is
mentioned somewhere in SKILL.md, and that scripts have a shebang.

Usage:
  python3 scripts/check_skill.py PATH/TO/skill-folder [PATH ...]
  python3 scripts/check_skill.py ~/.agents/skills/*        # many at once
  python3 scripts/check_skill.py my-skill --ignore notes.txt   # skip a file in the unreferenced-file check

Exit codes: 0 no errors (warnings allowed), 1 errors found, 2 usage error.
"""
from __future__ import annotations

import re
import sys
from pathlib import Path

KNOWN_KEYS = {"name", "description", "license", "compatibility", "metadata", "allowed-tools"}
NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
LINK_RE = re.compile(r"\]\(([^)#\s]+)(?:#[^)]*)?\)")
PATH_RE = re.compile(r"(?<![\w/.-])((?:scripts|references|assets|agents)/[\w./-]+)")


def parse_frontmatter(text: str) -> tuple[dict[str, str], str, list[str]]:
    errors: list[str] = []
    if not text.startswith("---\n"):
        return {}, text, ["SKILL.md must start with '---' on line 1"]
    end = text.find("\n---", 4)
    if end == -1:
        return {}, text, ["frontmatter is not closed with '---'"]
    block, body = text[4:end], text[end + 4:].lstrip("\n")
    data: dict[str, str] = {}
    key = None
    for line in block.splitlines():
        if not line.strip() or line.lstrip().startswith("#"):
            continue
        m = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", line)
        if m and not line.startswith((" ", "\t")):
            key, value = m.group(1), m.group(2).strip()
            if value in ("|", ">", "|-", ">-"):
                value = ""
            elif len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
                value = value[1:-1]
            elif re.search(r":\s", value) or re.search(r"\s#", value):
                errors.append(f"unquoted value for '{key}' contains ': ' or ' #'; wrap it in double quotes")
            data[key] = value
        elif key is not None:
            data[key] = (data[key] + " " + line.strip()).strip()
    return data, body, errors


def check(folder: Path, ignore: set[str]) -> tuple[list[str], list[str]]:
    errors: list[str] = []
    warnings: list[str] = []
    skill = folder / "SKILL.md"
    if not skill.is_file():
        return [f"{skill} not found"], warnings
    text = skill.read_text(encoding="utf-8")
    meta, body, fm_errors = parse_frontmatter(text)
    errors += fm_errors

    name = meta.get("name", "")
    if not name:
        errors.append("missing 'name'")
    else:
        if len(name) > 64 or not NAME_RE.match(name):
            errors.append(f"name '{name}' must be 1-64 chars of a-z, 0-9 and single hyphens, not starting or ending with '-'")
        if name != folder.name:
            errors.append(f"name '{name}' must equal the folder name '{folder.name}'")

    desc = meta.get("description", "")
    if not desc:
        errors.append("missing 'description'")
    else:
        if len(desc) > 1024:
            errors.append(f"description is {len(desc)} chars (max 1024)")
        if len(desc) < 120:
            warnings.append(f"description is only {len(desc)} chars; say what it does and when to use it")
        if "<" in desc and ">" in desc:
            warnings.append("description contains angle brackets; some hosts reject XML-like text")
        if not re.search(r"\b(use when|use for|use if|when )", desc, re.I):
            warnings.append("description has no trigger clause such as 'Use when ...'")

    for key in meta:
        if key not in KNOWN_KEYS:
            warnings.append(f"frontmatter key '{key}' is not in the Agent Skills spec; other hosts may ignore or reject it")
    if "compatibility" in meta and len(meta["compatibility"]) > 500:
        errors.append("compatibility is longer than 500 chars")

    lines = text.count("\n") + 1
    if lines > 500:
        warnings.append(f"SKILL.md has {lines} lines; move detail into references/")
    if len(body.strip()) < 200:
        warnings.append("body is very short; is the procedure really in SKILL.md?")

    # Outside fenced code blocks (which hold illustrative examples), markdown links
    # must resolve (error); bare paths should resolve too but only warn.
    prose = re.sub(r"```.*?```", "", body, flags=re.S)
    links = {t for t in LINK_RE.findall(prose) if not re.match(r"^[a-z]+:", t) and not t.startswith("/")}
    for target in sorted(links):
        if not (folder / target).exists():
            errors.append(f"link to '{target}' does not resolve inside the skill folder")
    for target in sorted({t.rstrip(".,;:`") for t in PATH_RE.findall(prose)} - links - {"agents/openai.yaml"}):
        if not (folder / target).exists():
            warnings.append(f"mentions '{target}', which is not in the skill folder")

    for path in sorted(folder.rglob("*")):
        if path.is_dir() or path.name == "SKILL.md" or "__pycache__" in path.parts or path.name.startswith("."):
            continue
        rel = path.relative_to(folder).as_posix()
        if rel == "agents/openai.yaml" or path.name in ignore or path.name.upper().startswith("LICENSE"):
            continue
        if rel not in text and path.name not in text:
            warnings.append(f"{rel} is never mentioned in SKILL.md, so the agent will not know to use it")
        if rel.startswith("scripts/") and path.suffix in {".py", ".sh", ".mjs", ".js"}:
            first = path.read_text(encoding="utf-8", errors="replace").splitlines()[:1]
            if not first or not first[0].startswith("#!"):
                warnings.append(f"{rel} has no shebang line")
    return errors, warnings


def main(argv: list[str]) -> int:
    if not argv or argv[0] in ("-h", "--help"):
        print(__doc__)
        return 2 if not argv else 0
    ignore: set[str] = set()
    folders: list[str] = []
    args = iter(argv)
    for arg in args:
        if arg == "--ignore":
            ignore.add(next(args, ""))
        else:
            folders.append(arg)
    failed = False
    for arg in folders:
        folder = Path(arg).expanduser().resolve()
        if not folder.is_dir():
            print(f"{arg}: not a directory", file=sys.stderr)
            failed = True
            continue
        errors, warnings = check(folder, ignore)
        status = "FAIL" if errors else "ok"
        print(f"{status}  {folder.name}")
        for e in errors:
            print(f"  error: {e}")
        for w in warnings:
            print(f"  warn:  {w}")
        failed = failed or bool(errors)
    return 1 if failed else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))