Skip to content

Marketing skills for Claude Code and AI agents. CRO, copywriting, SEO, analytics, and growth engineering.

10.8 KB
Raw Blame
#!/usr/bin/env python3
"""Build deterministic, single-skill ZIPs from a frozen Git revision."""

import argparse
import hashlib
import io
import json
import re
import subprocess
import sys
import zipfile
from pathlib import Path, PurePosixPath


DESCRIPTION_MAP = "scripts/claude-web-descriptions.json"
SKILL_NAME = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
EXCLUDED_PARTS = {"evals", "__pycache__", "node_modules", ".cache", ".DS_Store"}


def git(repo, *args):
    return subprocess.check_output(["git", "-C", str(repo), *args], stderr=subprocess.PIPE)


def sha256(data):
    return hashlib.sha256(data).hexdigest()


def metadata(data):
    text = data.decode("utf-8")
    front = re.match(r"\A---\r?\n(.*?)\r?\n---(?:\r?\n|$)", text, re.S)
    if not front:
        raise ValueError("SKILL.md is missing YAML frontmatter")
    fields = {}
    for key in ("name", "description"):
        matches = list(re.finditer(r"^" + key + r":[ \t]*(.*)$", front[1], re.M))
        if len(matches) != 1:
            raise ValueError(f"SKILL.md requires one single-line {key}")
        value = matches[0][1].rstrip("\r").strip()
        if value.startswith('"'):
            value = json.loads(value)
        elif value.startswith("'") and value.endswith("'"):
            value = value[1:-1].replace("''", "'")
        elif not value or value.startswith(("|", ">")):
            raise ValueError(f"Unsupported {key} scalar; use a single-line value")
        if not isinstance(value, str) or not value.strip():
            raise ValueError(f"SKILL.md {key} must be nonempty text")
        fields[key] = value
    return fields


def replace_description(data, description):
    # Replace only the top-level metadata line; retain body and other bytes.
    front_end = re.search(rb"\r?\n---(?:\r?\n|$)", data[3:])
    if not front_end:
        raise ValueError("SKILL.md is missing closing frontmatter")
    boundary = front_end.end() + 3
    replacement = ("description: " + json.dumps(description, ensure_ascii=False)).encode()
    head, count = re.subn(rb"(?m)^description:[^\r\n]*", lambda _: replacement, data[:boundary])
    if count != 1:
        raise ValueError("SKILL.md requires one description")
    return head + data[boundary:]


def tree_files(repo, revision):
    files = {}
    for record in git(repo, "ls-tree", "-r", "-z", revision, "--", "skills", "LICENSE").split(b"\0"):
        if not record:
            continue
        entry, raw_path = record.split(b"\t", 1)
        mode, kind, object_id = entry.decode().split()
        path = raw_path.decode("utf-8")
        files[path] = (mode, kind, object_id)
    return files


def build(repo, output, target="source", skills=None, revision="HEAD", descriptions=None, max_bytes=30_000_000, mapped_only=False):
    if max_bytes <= 0:
        raise ValueError("The per-bundle size bound must be positive")
    if mapped_only and target != "claude-web":
        raise ValueError("Mapped-only selection is specific to the Claude web target")
    commit = git(repo, "rev-parse", "--verify", "--end-of-options", revision + "^{commit}").decode().strip()
    files = tree_files(repo, commit)
    available = {p.split("/")[1] for p in files if p.count("/") == 2 and p.endswith("/SKILL.md")}
    selected = sorted(set(skills) if skills else available)
    if not selected:
        raise ValueError("No skills selected")
    for name in selected:
        if not SKILL_NAME.fullmatch(name) or len(name) > 64 or name not in available:
            raise ValueError(f"Unknown or invalid skill: {name}")
    license_entry = files.get("LICENSE")
    if not license_entry or license_entry[0] not in {"100644", "100755"}:
        raise ValueError("A tracked regular LICENSE file is required")
    license_size = int(git(repo, "cat-file", "-s", license_entry[2]))
    if license_size > max_bytes:
        raise ValueError("Bundle exceeds the configured uncompressed size bound: LICENSE")
    license_data = git(repo, "cat-file", "blob", license_entry[2])

    overrides = {}
    map_hash = None
    if target == "claude-web":
        raw_map = Path(descriptions).read_bytes() if descriptions else git(repo, "show", f"{commit}:{DESCRIPTION_MAP}")
        map_hash = sha256(raw_map)
        overrides = json.loads(raw_map)
        if not isinstance(overrides, dict):
            raise ValueError("Web descriptions must be a skill-keyed object")
    elif target != "source":
        raise ValueError(f"Unknown target: {target}")

    bundles = []
    omitted = []
    artifacts = {}
    for name in selected:
        prefix = f"skills/{name}/"
        resources = {}
        source_bytes = license_size
        for path, (mode, kind, object_id) in files.items():
            if not path.startswith(prefix):
                continue
            relative = path[len(prefix):]
            parts = PurePosixPath(relative).parts
            if any(part in EXCLUDED_PARTS for part in parts):
                continue
            if relative != "SKILL.md" and parts[0] not in {"references", "scripts", "assets"}:
                continue
            if "\\" in relative or ":" in relative or any(part in {".", ".."} for part in parts):
                raise ValueError(f"Unsafe resource path: {path}")
            if mode not in {"100644", "100755"} or kind != "blob":
                raise ValueError(f"Resource must be a tracked regular file: {path}")
            # SKILL.md may shrink when the web description is replaced; the
            # final packaged-size check below accounts for its actual bytes.
            if relative != "SKILL.md" or target == "source":
                source_bytes += int(git(repo, "cat-file", "-s", object_id))
            if source_bytes > max_bytes:
                raise ValueError(f"Bundle exceeds the configured uncompressed size bound: {name}")
            resources[relative] = (object_id, mode, path)
        resources = {relative: (git(repo, "cat-file", "blob", object_id), mode, path)
                     for relative, (object_id, mode, path) in resources.items()}
        original = resources["SKILL.md"][0]
        fields = metadata(original)
        if fields["name"] != name:
            raise ValueError(f"Skill name does not match folder: {name}")
        override = None
        if target == "claude-web":
            override = overrides.get(name)
            if not isinstance(override, dict):
                if mapped_only:
                    omitted.append({"skill": name, "reason": "Missing reviewed web description"})
                    continue
                raise ValueError(f"Missing reviewed web description: {name}")
            short = override.get("description")
            if not isinstance(short, str) or not 1 <= len(short) <= 200 or not short.strip() or "\n" in short or "\r" in short:
                raise ValueError(f"Web description must be 1–200 characters: {name}")
            if override.get("source_description_sha256") != sha256(fields["description"].encode()):
                if mapped_only:
                    omitted.append({"skill": name, "reason": "Source triggers changed; web description needs renewed review"})
                    continue
                raise ValueError(f"Stale web description; review changed source triggers: {name}")
            resources["SKILL.md"] = (replace_description(original, short), resources["SKILL.md"][1], prefix + "SKILL.md")
        resources["LICENSE"] = (license_data, "100644", "LICENSE")
        uncompressed_bytes = sum(len(item[0]) for item in resources.values())
        if uncompressed_bytes > max_bytes:
            raise ValueError(f"Bundle exceeds the configured uncompressed size bound: {name}")
        stream = io.BytesIO()
        inventory = []
        with zipfile.ZipFile(stream, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9) as archive:
            for relative, (data, mode, source_path) in sorted(resources.items()):
                entry = zipfile.ZipInfo(f"{name}/{relative}", date_time=(1980, 1, 1, 0, 0, 0))
                entry.create_system = 3
                entry.external_attr = (0o100755 if mode == "100755" else 0o100644) << 16
                entry.compress_type = zipfile.ZIP_DEFLATED
                archive.writestr(entry, data, compresslevel=9)
                source_data = original if relative == "SKILL.md" else data
                inventory.append({"path": entry.filename, "source_path": source_path, "source_sha256": sha256(source_data), "packaged_sha256": sha256(data)})
        filename = f"{name}-{target}.zip"
        artifacts[filename] = stream.getvalue()
        bundles.append({"skill": name, "archive": filename, "sha256": sha256(artifacts[filename]), "uncompressed_bytes": uncompressed_bytes, "description_override": {"original": fields["description"], "packaged": override["description"]} if override else None, "files": inventory})

    manifest = {"format_version": 1, "source_commit": commit, "target": target, "web_description_map_sha256": map_hash, "mapped_only": mapped_only, "omitted": omitted, "bundles": bundles}
    # Validate every selection before writing any artifact; incomplete web maps
    # must not leave a plausible but partial release on disk.
    output = Path(output)
    output.mkdir(parents=True, exist_ok=True)
    for filename, data in artifacts.items():
        (output / filename).write_bytes(data)
    (output / f"{target}-manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
    return manifest


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--repo", type=Path, default=Path(__file__).resolve().parent.parent)
    parser.add_argument("--output", type=Path, required=True)
    parser.add_argument("--target", choices=("source", "claude-web"), default="source")
    parser.add_argument("--skill", action="append", help="Select one skill; repeat for several. Default: all.")
    parser.add_argument("--ref", default="HEAD", help="Frozen Git revision to package; default HEAD.")
    parser.add_argument("--web-descriptions", type=Path, help="Explicit local override map instead of the selected revision's map.")
    parser.add_argument("--mapped-only", action="store_true", help="Explicitly omit new/stale web mappings and list them in the manifest; source builds remain complete.")
    parser.add_argument("--max-uncompressed-bytes", type=int, default=30_000_000, help="Local per-bundle size bound, including LICENSE; not a verified web upload limit.")
    args = parser.parse_args()
    try:
        manifest = build(args.repo, args.output, args.target, args.skill, args.ref, args.web_descriptions, args.max_uncompressed_bytes, args.mapped_only)
    except (ValueError, OSError, subprocess.CalledProcessError) as error:
        parser.exit(1, f"Packaging failed: {error}\n")
    print(f"Built {len(manifest['bundles'])} {args.target} ZIPs from {manifest['source_commit']}")
    for item in manifest["omitted"]:
        print(f"Omitted {item['skill']}: {item['reason']}")


if __name__ == "__main__":
    main()