Skip to content

sergeyklay/.agents / .agents/skills/make-skill

make-skill

Verified

Use when creating, improving, comparing, evaluating, reviewing or packaging Agent Skills following the agentskills.io specification. Also use when deciding whether a skill is the right solution vs MCP servers, Claude Rules Files, or AGENTS.md. Handles SKILL.md authoring, frontmatter optimization, description writing, progressive disclosure, platform targeting, invocation control, vendor-specific extensions, and distribution.

FileKindSize
SKILL.mdskill md16.7 KB
references/anti-patterns.mdmarkdown3.6 KB
references/frontmatter-fields.mdmarkdown25.3 KB
references/platform-targeting.mdmarkdown5.2 KB
references/reviewing-skills.mdmarkdown2.0 KB
references/skills-ecosystem.mdmarkdown6.2 KB
references/writing-patterns.mdmarkdown13.8 KB
scripts/init_skill.pyexecutablescript3.8 KB
scripts/validate_skill.pyexecutablescript27.5 KB

scripts/validate_skill.py

View on GitHub
#!/usr/bin/env python3
# Copyright 2026 Serghei Iakovlev
# SPDX-License-Identifier: Apache-2.0
"""Validate an Agent Skill directory against the agentskills.io specification.
The bundled YAML parser covers block mappings and sequences plus plain, quoted
and block scalars; flow style and anchors are not supported."""

from __future__ import annotations

import argparse
import enum
import re
import sys
from collections.abc import Iterable
from dataclasses import dataclass
from pathlib import Path
from typing import Union

YamlValue = Union[
    None,
    bool,
    int,
    float,
    str,
    dict[str, "YamlValue"],
    list["YamlValue"],
]


NAME_PATTERN = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
XML_TAG_PATTERN = re.compile(r"<[^>]+>")
MARKDOWN_LINK_PATTERN = re.compile(r"\[([^\]]*)\]\(([^)]+)\)")
FENCED_CODE_BLOCK_START_PATTERN = re.compile(r"^( {0,3})(`{3,}|~{3,})")
INLINE_CODE_SPAN_PATTERN = re.compile(r"`+[^`\n]*`+")
# Drive-letter paths or rooted paths with at least two backslash-separated
# components. This avoids misclassifying shell escapes and regex backreferences.
WINDOWS_PATH_PATTERN = re.compile(
    r"[A-Za-z]:\\|\\[A-Za-z][A-Za-z0-9_.-]*(?:\\[A-Za-z0-9_.-]+)+"
)
BLOCK_SCALAR_HEADER = re.compile(r"^[>|][+\-1-9]*\s*(#.*)?$")

MAX_NAME_LENGTH = 64
MAX_DESCRIPTION_LENGTH = 1024
MAX_COMPATIBILITY_LENGTH = 500
MAX_BODY_LINES = 500
# The spec recommends under 5000 tokens for the body; Anthropic's glossary
# puts a token at roughly 3.5 English characters, so 5000 x 3.5 bytes.
MAX_BODY_BYTES = 17_500
MAX_REFERENCE_LINES_WITHOUT_TOC = 100

RESERVED_WORDS: tuple[str, ...] = ("anthropic", "claude")
# The complete frontmatter field list from <https://agentskills.io/specification>.
# Anything else is a vendor extension: Claude Code accepts it, while claude.ai
# uploads, the Skills API and package_skill.py reject the whole file.
SPEC_FIELDS: frozenset[str] = frozenset(
    {"name", "description", "license", "compatibility", "metadata", "allowed-tools"}
)
KNOWN_DIRECTORIES: frozenset[str] = frozenset(
    {"scripts", "references", "assets", "evals", "agents"}
)
TRIGGER_KEYWORDS: tuple[str, ...] = (
    "use when",
    "use this",
    "trigger",
    "whenever",
    "also use",
)
TOC_KEYWORDS: tuple[str, ...] = ("contents", "table of contents", "## toc")
FIRST_OR_SECOND_PERSON_PREFIXES: tuple[str, ...] = (
    "I ",
    "I can",
    "You ",
    "You can",
)


class Severity(enum.Enum):
    ERROR = "ERROR"
    WARN = "WARN"
    INFO = "INFO"


_SEVERITY_MARKER: dict[Severity, str] = {
    Severity.ERROR: "x",
    Severity.WARN: "!",
    Severity.INFO: "-",
}


@dataclass(frozen=True)
class Issue:
    severity: Severity
    message: str

    def __str__(self) -> str:
        return f"  [{_SEVERITY_MARKER[self.severity]}] {self.message}"


class FrontmatterError(ValueError):
    """Raised when frontmatter is missing or cannot be parsed."""


_DELIMITER = "---"


def split_frontmatter(text: str) -> tuple[str, str]:
    """Return (frontmatter_yaml, body) by splitting at '---' delimiters.
    The opening delimiter must be the file's very first line. Raises
    FrontmatterError when the block is missing or unterminated."""
    lines = text.splitlines(keepends=True)
    if not lines or lines[0].rstrip("\r\n") != _DELIMITER:
        raise FrontmatterError(
            "SKILL.md must begin with YAML frontmatter ('---' on the first line)"
        )

    fm_start = len(lines[0])
    cursor = fm_start
    for line in lines[1:]:
        if line.rstrip("\r\n") == _DELIMITER:
            return text[fm_start:cursor], text[cursor + len(line) :]
        cursor += len(line)

    raise FrontmatterError("frontmatter is missing closing '---' delimiter")


def parse_yaml(text: str) -> YamlValue:
    """Parse the YAML subset used in skill frontmatter."""
    parser = _Parser(text)
    value = parser.parse_root()
    parser.expect_eof()
    return value


class _Parser:
    """Recursive-descent parser for skill-frontmatter YAML."""

    def __init__(self, text: str) -> None:
        self._lines = text.splitlines()
        self._pos = 0

    def parse_root(self) -> YamlValue:
        head = self._peek()
        if head is None:
            return {}
        _, indent, body = head
        if _is_sequence_item(body):
            return self._parse_sequence(indent)
        return self._parse_mapping(indent)

    def expect_eof(self) -> None:
        head = self._peek()
        if head is not None:
            line_no, _, body = head
            raise FrontmatterError(f"line {line_no}: unexpected content {body!r}")

    def _peek(self) -> tuple[int, int, str] | None:
        """Return (line_no, indent, body) for the next significant line."""
        while self._pos < len(self._lines):
            raw = self._lines[self._pos]
            stripped = raw.strip()
            if stripped == "" or stripped.startswith("#"):
                self._pos += 1
                continue
            indent = len(raw) - len(raw.lstrip(" "))
            return self._pos + 1, indent, raw[indent:]
        return None

    def _advance(self) -> None:
        self._pos += 1

    def _parse_mapping(self, indent: int) -> dict[str, YamlValue]:
        result: dict[str, YamlValue] = {}
        while True:
            head = self._peek()
            if head is None:
                break
            line_no, cur_indent, body = head
            if cur_indent < indent:
                break
            if cur_indent > indent:
                raise FrontmatterError(
                    f"line {line_no}: unexpected indentation "
                    f"(expected {indent}, got {cur_indent})"
                )
            if _is_sequence_item(body):
                raise FrontmatterError(
                    f"line {line_no}: expected mapping key, got list item"
                )

            key, after_colon = _split_key(body, line_no)
            self._advance()
            value = self._parse_value(after_colon, indent, line_no)

            if key in result:
                raise FrontmatterError(f"line {line_no}: duplicate key {key!r}")
            result[key] = value
        return result

    def _parse_value(
        self, value_text: str, parent_indent: int, line_no: int
    ) -> YamlValue:
        if BLOCK_SCALAR_HEADER.match(value_text):
            return self._parse_block_scalar(value_text, parent_indent, line_no)

        cleaned = _strip_trailing_comment(value_text).strip()
        if cleaned == "":
            return self._parse_nested(parent_indent)
        if cleaned.startswith('"'):
            return _decode_double_quoted(cleaned, line_no)
        if cleaned.startswith("'"):
            return _decode_single_quoted(cleaned, line_no)
        if cleaned[0] in ("[", "{"):
            raise FrontmatterError(
                f"line {line_no}: flow style ([...] or {{...}}) is not supported"
            )
        return cleaned

    def _parse_nested(self, parent_indent: int) -> YamlValue:
        head = self._peek()
        if head is None:
            return ""
        _, indent, body = head
        if indent <= parent_indent:
            return ""
        if _is_sequence_item(body):
            return self._parse_sequence(indent)
        return self._parse_mapping(indent)

    def _parse_sequence(self, indent: int) -> list[YamlValue]:
        items: list[YamlValue] = []
        while True:
            head = self._peek()
            if head is None:
                break
            line_no, cur_indent, body = head
            if cur_indent < indent:
                break
            if cur_indent > indent:
                raise FrontmatterError(
                    f"line {line_no}: unexpected indentation in sequence"
                )
            if not _is_sequence_item(body):
                break

            self._advance()
            inner = body[2:] if body.startswith("- ") else ""

            if BLOCK_SCALAR_HEADER.match(inner):
                items.append(self._parse_block_scalar(inner, indent, line_no))
                continue

            cleaned = _strip_trailing_comment(inner).strip()
            if cleaned == "":
                items.append(self._parse_nested(indent))
            elif cleaned.startswith('"'):
                items.append(_decode_double_quoted(cleaned, line_no))
            elif cleaned.startswith("'"):
                items.append(_decode_single_quoted(cleaned, line_no))
            elif cleaned[0] in ("[", "{"):
                raise FrontmatterError(f"line {line_no}: flow style is not supported")
            else:
                items.append(cleaned)
        return items

    def _parse_block_scalar(
        self, indicator: str, parent_indent: int, line_no: int
    ) -> str:
        style, chomp = _parse_block_indicator(indicator, line_no)

        block_lines: list[str] = []
        block_indent: int | None = None

        while self._pos < len(self._lines):
            raw = self._lines[self._pos]
            if raw.strip() == "":
                block_lines.append("")
                self._pos += 1
                continue
            cur_indent = len(raw) - len(raw.lstrip(" "))
            if cur_indent <= parent_indent:
                break
            if block_indent is None:
                block_indent = cur_indent
            if cur_indent < block_indent:
                break
            block_lines.append(raw[block_indent:])
            self._pos += 1

        # Discard surrounding blank lines (track trailing for chomping).
        while block_lines and block_lines[0] == "":
            block_lines.pop(0)
        trailing_blanks = 0
        while block_lines and block_lines[-1] == "":
            block_lines.pop()
            trailing_blanks += 1

        if not block_lines:
            return "\n" * trailing_blanks if chomp == "+" else ""

        joined = (
            "\n".join(block_lines) if style == "|" else _fold_block_lines(block_lines)
        )

        if chomp == "-":  # strip
            return joined
        if chomp == "+":  # keep
            return joined + "\n" * (1 + trailing_blanks)
        return joined + "\n"  # clip (default)


def _is_sequence_item(body: str) -> bool:
    return body == "-" or body.startswith("- ")


def _split_key(body: str, line_no: int) -> tuple[str, str]:
    if body.startswith(("'", '"')):
        raise FrontmatterError(f"line {line_no}: quoted keys are not supported")
    colon = body.find(":")
    if colon == -1:
        raise FrontmatterError(f"line {line_no}: expected 'key: value' (no ':' found)")
    key = body[:colon].rstrip()
    if not key:
        raise FrontmatterError(f"line {line_no}: empty key")
    rest = body[colon + 1 :]
    if rest and not rest.startswith(" "):
        raise FrontmatterError(
            f"line {line_no}: expected space after ':' for key {key!r}"
        )
    return key, rest.lstrip(" ")


def _parse_block_indicator(text: str, line_no: int) -> tuple[str, str]:
    """Return (style, chomp) where style is '>' or '|' and chomp is '', '-' or '+'."""
    style = text[0]
    chomp = ""
    for ch in text[1:]:
        if ch == " ":
            continue
        if ch == "#":
            break
        if ch in ("+", "-"):
            if chomp:
                raise FrontmatterError(
                    f"line {line_no}: invalid block scalar chomping indicator"
                )
            chomp = ch
        elif ch.isdigit():
            continue  # explicit indentation indicator: accepted but auto-detected
        else:
            raise FrontmatterError(
                f"line {line_no}: invalid block scalar indicator {text!r}"
            )
    return style, chomp


def _fold_block_lines(lines: list[str]) -> str:
    """Join lines per YAML '>' (folded) semantics.
    A single break between two non-empty lines becomes a space; each empty line
    contributes one literal newline."""
    parts: list[str] = []
    blank_run = 0
    has_content = False
    for line in lines:
        if line == "":
            if has_content:
                blank_run += 1
            continue
        if blank_run:
            parts.append("\n" * blank_run)
            blank_run = 0
        elif has_content:
            parts.append(" ")
        parts.append(line)
        has_content = True
    return "".join(parts)


def _strip_trailing_comment(text: str) -> str:
    """Remove a trailing ' # comment'; respect quoted strings."""
    if not text:
        return text
    if text.lstrip().startswith("#"):
        return ""
    in_single = False
    in_double = False
    for i, ch in enumerate(text):
        if ch == "'" and not in_double:
            in_single = not in_single
        elif ch == '"' and not in_single:
            if i == 0 or text[i - 1] != "\\":
                in_double = not in_double
        elif (
            ch == "#"
            and not in_single
            and not in_double
            and i > 0
            and text[i - 1] == " "
        ):
            return text[:i].rstrip()
    return text


def _decode_double_quoted(text: str, line_no: int) -> str:
    if len(text) < 2 or not text.endswith('"'):
        raise FrontmatterError(f"line {line_no}: unterminated double-quoted string")
    inner = text[1:-1]
    out: list[str] = []
    escapes = {
        "n": "\n",
        "t": "\t",
        "r": "\r",
        "\\": "\\",
        '"': '"',
        "'": "'",
        "0": "\0",
        "/": "/",
    }
    i = 0
    while i < len(inner):
        ch = inner[i]
        if ch == "\\" and i + 1 < len(inner):
            replacement = escapes.get(inner[i + 1])
            if replacement is not None:
                out.append(replacement)
                i += 2
                continue
        out.append(ch)
        i += 1
    return "".join(out)


def _decode_single_quoted(text: str, line_no: int) -> str:
    if len(text) < 2 or not text.endswith("'"):
        raise FrontmatterError(f"line {line_no}: unterminated single-quoted string")
    return text[1:-1].replace("''", "'")


def _check_name(fm: dict[str, YamlValue], skill_dir: Path) -> Iterable[Issue]:
    raw = fm.get("name")
    if raw is None or (isinstance(raw, str) and not raw.strip()):
        yield Issue(Severity.ERROR, "Missing required field: name")
        return

    name = str(raw).strip()
    if len(name) > MAX_NAME_LENGTH:
        yield Issue(
            Severity.ERROR,
            f"name exceeds {MAX_NAME_LENGTH} chars ({len(name)})",
        )
    if not NAME_PATTERN.match(name):
        yield Issue(
            Severity.ERROR,
            f"name {name!r} must be lowercase alphanumeric with single hyphens",
        )
    if "--" in name:
        yield Issue(
            Severity.ERROR,
            "name cannot contain consecutive hyphens (--)",
        )
    for word in RESERVED_WORDS:
        if word in name.lower():
            yield Issue(
                Severity.ERROR,
                f"name contains reserved word {word!r}",
            )
    if XML_TAG_PATTERN.search(name):
        yield Issue(Severity.ERROR, "name cannot contain XML tags")
    if name != skill_dir.name:
        yield Issue(
            Severity.WARN,
            f"name {name!r} does not match directory name {skill_dir.name!r}",
        )


def _is_user_invoked_only(fm: dict[str, YamlValue]) -> bool:
    """Detect frontmatter that prevents model invocation.

    Codex's equivalent lives in a sibling `agents/openai.yaml` and is not seen."""
    val = fm.get("disable-model-invocation")
    if isinstance(val, bool):
        return val
    if isinstance(val, str):
        return val.strip().lower() in ("true", "yes", "1")
    return False


def _check_description(fm: dict[str, YamlValue]) -> Iterable[Issue]:
    raw = fm.get("description")
    if raw is None:
        yield Issue(Severity.ERROR, "Missing required field: description")
        return

    desc = str(raw).strip()
    if not desc:
        yield Issue(Severity.ERROR, "description cannot be empty")
        return

    if len(desc) > MAX_DESCRIPTION_LENGTH:
        yield Issue(
            Severity.ERROR,
            f"description exceeds {MAX_DESCRIPTION_LENGTH} chars ({len(desc)})",
        )
    if XML_TAG_PATTERN.search(desc):
        yield Issue(Severity.ERROR, "description cannot contain XML tags")
    if desc.startswith(FIRST_OR_SECOND_PERSON_PREFIXES):
        yield Issue(
            Severity.WARN,
            "description should use third person, not first or second person",
        )
    if "[TODO" in desc:
        yield Issue(
            Severity.WARN,
            "description contains [TODO marker - complete before using",
        )

    desc_lower = desc.lower()
    has_trigger = any(kw in desc_lower for kw in TRIGGER_KEYWORDS)
    user_only = _is_user_invoked_only(fm)

    if user_only:
        # Triggers are noise here: the model never reads this description.
        if has_trigger:
            yield Issue(
                Severity.WARN,
                "description contains 'Use when ...' style triggers but "
                "disable-model-invocation: true is set - the model never "
                "reads this description; triggers consume the user-facing "
                "label budget for nothing",
            )
    else:
        # Model-invoked: short descriptions without triggers will under-fire.
        if not has_trigger and len(desc) < 200:
            yield Issue(
                Severity.WARN,
                "description may lack trigger phrases - "
                "agents need explicit guidance on when to activate",
            )


def _check_compatibility(fm: dict[str, YamlValue]) -> Iterable[Issue]:
    compat = fm.get("compatibility")
    if compat is None:
        return
    if isinstance(compat, list):
        compat = ", ".join(str(x) for x in compat)
    text = str(compat)
    if len(text) > MAX_COMPATIBILITY_LENGTH:
        yield Issue(
            Severity.ERROR,
            f"compatibility exceeds {MAX_COMPATIBILITY_LENGTH} chars ({len(text)})",
        )


def _check_allowed_tools(fm: dict[str, YamlValue]) -> Iterable[Issue]:
    """Check that allowed-tools is a string, as the spec types it.
    A YAML list parses on Claude Code and fails wherever the spec is enforced."""
    if "allowed-tools" not in fm:
        return

    value = fm["allowed-tools"]
    if isinstance(value, list):
        yield Issue(
            Severity.ERROR,
            "allowed-tools must be a space-separated string, not a YAML list",
        )
    elif not isinstance(value, str):
        yield Issue(
            Severity.ERROR,
            "allowed-tools must be a space-separated string "
            f"(got {type(value).__name__})",
        )


def _check_metadata(fm: dict[str, YamlValue]) -> Iterable[Issue]:
    """Check that metadata is a map from string keys to string values."""
    if "metadata" not in fm:
        return

    metadata = fm["metadata"]
    if not isinstance(metadata, dict):
        yield Issue(
            Severity.ERROR,
            "metadata must be a map from string keys to string values",
        )
        return

    for key, value in metadata.items():
        if not isinstance(value, str):
            yield Issue(
                Severity.ERROR,
                f"metadata.{key} must be a string value (got {type(value).__name__})",
            )


def _check_spec_fields(fm: dict[str, YamlValue]) -> Iterable[Issue]:
    """Report frontmatter fields the agentskills.io spec does not define."""
    extra = sorted(key for key in fm if key not in SPEC_FIELDS)
    if extra:
        yield Issue(
            Severity.INFO,
            f"Fields outside the spec: {', '.join(extra)}. "
            f"Portable frontmatter is limited to {', '.join(sorted(SPEC_FIELDS))}; "
            f"claude.ai uploads and package_skill.py reject the rest.",
        )


def _check_body(body: str) -> Iterable[Issue]:
    line_count = len(body.splitlines())
    if line_count == 0:
        yield Issue(Severity.WARN, "SKILL.md body is empty")
        return

    if line_count > MAX_BODY_LINES:
        yield Issue(
            Severity.WARN,
            f"SKILL.md body is {line_count} lines "
            f"(recommended: under {MAX_BODY_LINES}). "
            f"Consider splitting into reference files.",
        )
    else:
        yield Issue(Severity.INFO, f"SKILL.md body: {line_count} lines")

    byte_count = len(body.encode("utf-8"))
    if byte_count > MAX_BODY_BYTES:
        yield Issue(
            Severity.WARN,
            f"SKILL.md body is {byte_count} bytes "
            f"(recommended: under {MAX_BODY_BYTES}). "
            f"Consider splitting into reference files.",
        )

    if WINDOWS_PATH_PATTERN.search(body):
        yield Issue(
            Severity.WARN,
            "Body may contain backslash paths. "
            "Use forward slashes for cross-platform compatibility.",
        )


def _without_fenced_code_blocks(text: str) -> str:
    """Return Markdown text without fenced code blocks, including indented fences."""
    kept: list[str] = []
    fence_char = ""
    fence_length = 0
    for line in text.splitlines():
        content = line.lstrip(" ")
        indent = len(line) - len(content)
        if fence_char:
            run_length = len(content) - len(content.lstrip(fence_char))
            if (
                indent <= 3
                and run_length >= fence_length
                and not content[run_length:].strip()
            ):
                fence_char = ""
                fence_length = 0
            continue

        match = FENCED_CODE_BLOCK_START_PATTERN.match(line)
        if match:
            fence = match.group(2)
            fence_char = fence[0]
            fence_length = len(fence)
            continue
        kept.append(line)
    return "\n".join(kept)


def _without_code_examples(text: str) -> str:
    """Return prose without inline or fenced code that may show example links."""
    return INLINE_CODE_SPAN_PATTERN.sub("", _without_fenced_code_blocks(text))


def _resolve_within(base: Path, relative: str) -> Path | None:
    """Resolve a Markdown link target under ``base``, or None if it escapes.
    ``Path.__truediv__`` drops the left operand for an absolute right one and ".."
    can walk out, so resolve first and require containment after."""
    candidate = (base / relative).resolve()
    try:
        candidate.relative_to(base)
    except ValueError:
        return None
    return candidate


def _check_reference_depth(skill_dir: Path, body: str) -> Iterable[Issue]:
    skill_root = skill_dir.resolve()
    for _, href in MARKDOWN_LINK_PATTERN.findall(_without_code_examples(body)):
        if href.startswith(("http://", "https://", "#")):
            continue
        href_path = href.split("#", 1)[0].split("?", 1)[0]
        if not href_path.endswith(".md"):
            continue
        ref_path = _resolve_within(skill_root, href_path)
        if ref_path is None or not ref_path.is_file():
            yield Issue(Severity.WARN, f"Missing local reference: {href_path}.")
            continue
        try:
            ref_text = ref_path.read_text(encoding="utf-8", errors="ignore")
        except OSError:
            continue
        nested: list[str] = []
        for _, target in MARKDOWN_LINK_PATTERN.findall(
            _without_code_examples(ref_text)
        ):
            if target.startswith(("http://", "https://", "#")):
                continue
            target_path = target.split("#", 1)[0].split("?", 1)[0]
            if not target_path.endswith(".md"):
                continue
            candidate = _resolve_within(ref_path.parent, target_path)
            if candidate is None or not candidate.is_file():
                yield Issue(
                    Severity.WARN,
                    f"Missing local reference: {href} links to {target_path}.",
                )
            else:
                nested.append(target)
        if nested:
            yield Issue(
                Severity.WARN,
                f"Nested reference: {href} links to {', '.join(nested)}. "
                f"Keep references one level deep from SKILL.md.",
            )


def _check_directory_structure(skill_dir: Path) -> Iterable[Issue]:
    for item in sorted(skill_dir.iterdir()):
        if not item.is_dir() or item.name.startswith("."):
            continue
        if item.name in KNOWN_DIRECTORIES:
            continue
        yield Issue(Severity.INFO, f"Non-standard directory: {item.name}/")


def _check_reference_files(skill_dir: Path) -> Iterable[Issue]:
    refs_dir = skill_dir / "references"
    if not refs_dir.is_dir():
        return
    for ref_file in sorted(refs_dir.glob("*.md")):
        try:
            ref_text = ref_file.read_text(encoding="utf-8", errors="ignore")
        except OSError:
            continue
        line_count = len(ref_text.splitlines())
        if line_count <= MAX_REFERENCE_LINES_WITHOUT_TOC:
            continue
        head = ref_text[:500].lower()
        if any(kw in head for kw in TOC_KEYWORDS):
            continue
        yield Issue(
            Severity.WARN,
            f"references/{ref_file.name} is {line_count} lines "
            f"but has no table of contents",
        )


def validate(skill_dir: Path, warnings_as_errors: bool = False) -> list[Issue]:
    """Run every check and return all issues, ending with a summary INFO line."""
    if not skill_dir.is_dir():
        return [Issue(Severity.ERROR, f"Not a directory: {skill_dir}")]

    skill_md = skill_dir / "SKILL.md"
    if not skill_md.exists():
        return [Issue(Severity.ERROR, "SKILL.md not found")]

    try:
        content = skill_md.read_text(encoding="utf-8-sig")
    except OSError as exc:
        return [Issue(Severity.ERROR, f"Cannot read SKILL.md: {exc}")]

    try:
        fm_text, body = split_frontmatter(content)
        fm = parse_yaml(fm_text)
    except FrontmatterError as exc:
        return [Issue(Severity.ERROR, str(exc))]

    if not isinstance(fm, dict):
        return [Issue(Severity.ERROR, "frontmatter must be a YAML mapping")]

    issues: list[Issue] = []
    issues.extend(_check_name(fm, skill_dir))
    issues.extend(_check_description(fm))
    issues.extend(_check_compatibility(fm))
    issues.extend(_check_allowed_tools(fm))
    issues.extend(_check_metadata(fm))
    issues.extend(_check_spec_fields(fm))
    issues.extend(_check_body(body))
    issues.extend(_check_reference_depth(skill_dir, body))
    issues.extend(_check_directory_structure(skill_dir))
    issues.extend(_check_reference_files(skill_dir))
    issues.append(_summary(issues, warnings_as_errors))
    return issues


def _summary(issues: Iterable[Issue], warnings_as_errors: bool) -> Issue:
    errors = sum(1 for i in issues if i.severity is Severity.ERROR)
    warns = sum(1 for i in issues if i.severity is Severity.WARN)
    word = "failed" if errors or (warnings_as_errors and warns) else "passed"
    return Issue(
        Severity.INFO,
        f"Validation {word}: "
        f"{errors} error{'s' if errors != 1 else ''}, "
        f"{warns} warning{'s' if warns != 1 else ''}",
    )


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="validate_skill.py",
        description="Validate an Agent Skill directory against agentskills.io.",
    )
    parser.add_argument(
        "skill_dir",
        type=Path,
        help="Path to the skill directory to validate.",
    )
    parser.add_argument(
        "--warnings-as-errors",
        action="store_true",
        help="Exit non-zero when validation emits warnings.",
    )
    return parser


def main(argv: list[str] | None = None) -> int:
    args = _build_parser().parse_args(argv)
    issues = validate(
        args.skill_dir.expanduser().resolve(),
        warnings_as_errors=args.warnings_as_errors,
    )
    for issue in issues:
        print(issue)
    return (
        1
        if any(
            i.severity is Severity.ERROR
            or (args.warnings_as_errors and i.severity is Severity.WARN)
            for i in issues
        )
        else 0
    )


if __name__ == "__main__":
    sys.exit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall