agentskill-toolkit 0.1.0__py3-none-any.whl

agentskill_kit/scan.py

@@ -0,0 +1,303 @@
+"""Heuristic security scanner for skills.
+
+Skills are instructions that an agent follows, often with shell access, so a
+malicious or careless skill can do real damage. This scanner looks for common
+red flags: prompt injection phrasing, hidden unicode, dangerous shell
+patterns, embedded secrets and signs of credential exfiltration. It is a
+heuristic filter, not a guarantee. Review skills from sources you do not trust.
+
+Silence a deliberate match by adding ``askit-ignore`` (optionally followed by
+rule ids, e.g. ``askit-ignore: SC103``) on the same line.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Pattern
+
+from .skillfile import SkillError, iter_skill_files
+
+SEVERITY_WEIGHT = {"high": 40, "medium": 15, "low": 3}
+SEVERITY_RANK = {"high": 3, "medium": 2, "low": 1}
+MAX_FILE_BYTES = 2_000_000
+BINARY_SUFFIXES = {".exe", ".dll", ".so", ".dylib", ".bin", ".jar", ".msi", ".dmg", ".app",
+                   ".class", ".o", ".a", ".whl", ".pyd"}
+CODE_SUFFIXES = {".py", ".js", ".ts", ".mjs", ".cjs", ".sh", ".bash", ".zsh", ".ps1", ".rb", ".pl",
+                 ".php", ".bat", ".cmd"}
+
+
+@dataclass
+class Rule:
+    id: str
+    severity: str
+    title: str
+    pattern: Pattern[str]
+    code_only: bool = False
+    accept: Optional[Callable[[str], bool]] = None
+
+
+def _r(pattern: str, flags: int = re.I) -> Pattern[str]:
+    return re.compile(pattern, flags)
+
+
+def _is_placeholder(text: str) -> bool:
+    low = text.lower()
+    return any(w in low for w in ("example", "your", "xxxx", "changeme", "placeholder", "dummy",
+                                  "sample", "<", "redacted", "0000", "1234", "abcd"))
+
+
+def _public_ip(text: str) -> bool:
+    m = re.search(r"(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})", text)
+    if not m:
+        return False
+    a, b = int(m.group(1)), int(m.group(2))
+    if a in (0, 10, 127) or (a == 192 and b == 168) or (a == 172 and 16 <= b <= 31) or (a == 169 and b == 254):
+        return False
+    return True
+
+
+SECRET_PATTERNS: List[Pattern[str]] = [
+    _r(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b", 0),
+    _r(r"\bgh[pousr]_[A-Za-z0-9]{36,}\b", 0),
+    _r(r"\bgithub_pat_[A-Za-z0-9_]{50,}\b", 0),
+    _r(r"\bsk-ant-[A-Za-z0-9_-]{20,}", 0),
+    _r(r"\bsk-or-v1-[A-Za-z0-9]{20,}", 0),
+    _r(r"\bsk-proj-[A-Za-z0-9_-]{20,}", 0),
+    _r(r"\bsk-[A-Za-z0-9]{32,}\b", 0),
+    _r(r"\bgsk_[A-Za-z0-9]{40,}\b", 0),
+    _r(r"\bAIza[0-9A-Za-z_-]{35}\b", 0),
+    _r(r"\bxox[abprs]-[A-Za-z0-9-]{10,}", 0),
+    _r(r"\bnpm_[A-Za-z0-9]{36}\b", 0),
+    _r(r"\bpypi-AgEIcHlwaS5vcmc[A-Za-z0-9_-]{20,}", 0),
+]
+
+RULES: List[Rule] = [
+    # Prompt injection and hidden instructions
+    Rule("SC001", "high", "Instruction override phrasing",
+         _r(r"\bignore\s+(?:all\s+|any\s+|the\s+)*(?:previous|prior|above|earlier|preceding)\s+"
+            r"(?:instructions?|prompts?|rules|messages|directions)")),
+    Rule("SC002", "high", "Attempt to discard system rules",
+         _r(r"\bdisregard\s+(?:all\s+|any\s+)*(?:your|the|previous|prior)\s+(?:system\s+)?"
+            r"(?:prompt|instructions?|rules|guidelines)")),
+    Rule("SC003", "high", "Instruction to hide actions from the user",
+         _r(r"\b(?:do\s+not|don't|never)\s+(?:tell|inform|mention|reveal|show|notify)\s+(?:this\s+)?(?:to\s+)?the\s+user\b"
+            r"|\bwithout\s+(?:telling|informing|notifying|alerting)\s+the\s+user\b"
+            r"|\bhide\s+(?:this|it)\s+from\s+the\s+user\b")),
+    Rule("SC004", "medium", "Jailbreak style phrasing",
+         _r(r"\b(?:developer\s+mode|jailbreak(?:ed)?|do\s+anything\s+now|you\s+are\s+now\s+(?:in\s+)?"
+            r"(?:a\s+|an\s+)?(?:unrestricted|unfiltered|dan)\b)")),
+    Rule("SC005", "medium", "Asks the agent to reveal its hidden prompt",
+         _r(r"\b(?:reveal|print|output|repeat|leak|dump)\s+(?:your|the)\s+(?:system\s+prompt|"
+            r"hidden\s+instructions|initial\s+instructions)")),
+    Rule("SC006", "high", "Invisible or bidirectional unicode characters",
+         re.compile("[\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\U000e0000-\U000e007f]")),
+    Rule("SC007", "medium", "Instruction hidden inside an HTML comment",
+         _r(r"<!--(?:(?!-->).){0,400}?\b(?:ignore|you\s+must|always\s+run|execute|exfiltrate|send\s+the)\b"
+            r"(?:(?!-->).){0,400}?-->", re.I | re.S)),
+    # Dangerous commands
+    Rule("SC101", "high", "Downloads and pipes straight into a shell",
+         _r(r"\b(?:curl|wget)\b[^\n|;]*\|\s*(?:sudo\s+)?(?:ba|z|da|k)?sh\b"
+            r"|\b(?:iwr|irm|invoke-webrequest|invoke-restmethod)\b[^\n|]*\|\s*(?:iex|invoke-expression)\b")),
+    Rule("SC102", "high", "Recursive delete of a broad path",
+         _r(r"\brm\s+-(?:[a-z]*r[a-z]*f|[a-z]*f[a-z]*r)[a-z]*\s+(?:--no-preserve-root\s+)?"
+            r"(?:/|~|\$HOME|\$\{HOME\}|\*)(?:\s|$|/)")),
+    Rule("SC103", "medium", "Uses sudo or elevated privileges",
+         _r(r"(?:^|[;&|(`$]|\b(?:run|then|and|exec)\b)[ \t]*sudo[ \t]+[a-z-]", re.I | re.M)),
+    Rule("SC104", "medium", "World-writable permissions", _r(r"\bchmod\s+(?:-R\s+)?(?:777|a\+rwx|0777)\b")),
+    Rule("SC105", "high", "Decodes and runs obfuscated payload",
+         _r(r"\bbase64\s+(?:-d|--decode)\b[^\n|]*\|\s*(?:ba|z)?sh\b"
+            r"|\b(?:powershell|pwsh)\b[^\n]*\s-e(?:nc|ncodedcommand)?\s+[A-Za-z0-9+/=]{20,}")),
+    Rule("SC106", "high", "Reverse shell pattern",
+         _r(r"/dev/tcp/|\bnc(?:at)?\s+(?:-[a-z]*e|-c)\b|\bbash\s+-i\s*>&|\bmkfifo\b[^\n]*\bnc\b")),
+    Rule("SC107", "medium", "Dynamic code execution (eval/exec)",
+         _r(r"\b(?:eval|exec)\s*\("), code_only=True),
+    Rule("SC108", "low", "Shell execution from code",
+         _r(r"\bos\.system\s*\(|\bshell\s*=\s*True\b|\bchild_process\.exec\s*\("), code_only=True),
+    Rule("SC109", "high", "Destructive disk or fork bomb command",
+         _r(r":\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:|\bdd\s+if=\S+\s+of=/dev/(?:sd|nvme|disk|hd)|\bmkfs\.\w+\s+/dev/")),
+    Rule("SC110", "low", "Force push or hard reset",
+         _r(r"\bgit\s+push\s+(?:[^\n]*\s)?(?:-f|--force)\b|\bgit\s+reset\s+--hard\b")),
+    Rule("SC111", "medium", "Installs a package from an arbitrary URL",
+         _r(r"\bpip3?\s+install\s+(?:-[A-Za-z-]+\s+)*(?:https?://|git\+)")),
+    # Secrets
+    Rule("SC201", "high", "AWS access key", SECRET_PATTERNS[0]),
+    Rule("SC202", "high", "GitHub token", _r(SECRET_PATTERNS[1].pattern + "|" + SECRET_PATTERNS[2].pattern, 0)),
+    Rule("SC203", "high", "LLM or cloud API key",
+         _r("|".join(p.pattern for p in SECRET_PATTERNS[3:9]), 0)),
+    Rule("SC204", "high", "Slack, npm or PyPI token", _r("|".join(p.pattern for p in SECRET_PATTERNS[9:]), 0)),
+    Rule("SC205", "high", "Private key material",
+         _r(r"-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----", 0)),
+    Rule("SC206", "medium", "Hardcoded credential assignment",
+         _r(r"\b(?:api[_-]?key|secret|token|passwd|password)\b[\"']?\s*[:=]\s*[\"'][A-Za-z0-9/+_\-]{16,}[\"']"),
+         accept=lambda s: not _is_placeholder(s)),
+    # Credential access and exfiltration
+    Rule("SC301", "medium", "Reads credential files or keys",
+         _r(r"(?:~|\$HOME|%USERPROFILE%|/home/\w+)[/\\]\.(?:ssh|aws|gnupg|kube|docker[/\\]config\.json)\b"
+            r"|/etc/(?:shadow|sudoers)\b|\bid_rsa\b|\.netrc\b|\bcredentials\.json\b")),
+    Rule("SC302", "low", "Sends data over the network",
+         _r(r"\brequests\.(?:post|put|patch)\s*\(|\burllib\.request\.urlopen\s*\(|\bhttp\.client\.\w+\s*\("
+            r"|\bcurl\b[^\n]*\s(?:-d|--data\S*|-F|-T|--upload-file)\b|\bfetch\s*\(\s*[\"'`]https?://"
+            r"|\bsocket\.socket\s*\("), code_only=True),
+    Rule("SC303", "medium", "Suspicious host (raw IP, shortener or request catcher)",
+         _r(r"https?://(?:\d{1,3}\.){3}\d{1,3}\b|\b(?:bit\.ly|tinyurl\.com|t\.co|goo\.gl|is\.gd)/"
+            r"|\b(?:pastebin\.com|webhook\.site|requestbin\.\w+|ngrok\.(?:io|app|dev)|interact\.sh|"
+            r"burpcollaborator\.net|discord(?:app)?\.com/api/webhooks)\b"),
+         accept=lambda s: _public_ip(s) if re.match(r"https?://\d", s) else True),
+    Rule("SC401", "medium", "Persistence mechanism (shell rc, cron, ssh keys)",
+         _r(r"\bauthorized_keys\b|\bcrontab\s+-|\blaunchctl\s+load\b|\bsystemctl\s+enable\b"
+            r"|>>\s*~?/?\.(?:bashrc|zshrc|profile|bash_profile)\b|\bschtasks\s+/create\b")),
+]
+
+RULES_BY_ID = {r.id: r for r in RULES}
+IGNORE_RE = re.compile(r"askit-ignore(?::\s*([A-Z0-9, ]+))?")
+
+
+@dataclass
+class Finding:
+    rule: str
+    severity: str
+    message: str
+    file: str
+    line: int
+    snippet: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"rule": self.rule, "severity": self.severity, "message": self.message,
+                "file": self.file, "line": self.line, "snippet": self.snippet}
+
+
+@dataclass
+class ScanResult:
+    skill: str
+    path: str
+    findings: List[Finding] = field(default_factory=list)
+    files_scanned: int = 0
+
+    def count(self, severity: str) -> int:
+        return sum(1 for f in self.findings if f.severity == severity)
+
+    @property
+    def risk(self) -> int:
+        return min(100, sum(SEVERITY_WEIGHT[f.severity] for f in self.findings))
+
+    @property
+    def safety(self) -> int:
+        return 100 - self.risk
+
+    @property
+    def verdict(self) -> str:
+        if self.count("high"):
+            return "risky"
+        if self.count("medium"):
+            return "review"
+        return "clean"
+
+    def worst(self) -> str:
+        for sev in ("high", "medium", "low"):
+            if self.count(sev):
+                return sev
+        return "none"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"skill": self.skill, "path": self.path, "verdict": self.verdict, "safety": self.safety,
+                "high": self.count("high"), "medium": self.count("medium"), "low": self.count("low"),
+                "files_scanned": self.files_scanned, "findings": [f.to_dict() for f in self.findings]}
+
+
+def _ignored(line_text: str, rule_id: str) -> bool:
+    m = IGNORE_RE.search(line_text)
+    if not m:
+        return False
+    ids = m.group(1)
+    if not ids:
+        return True
+    return rule_id in {p.strip() for p in ids.split(",")}
+
+
+def scan_text(text: str, filename: str = "SKILL.md") -> List[Finding]:
+    suffix = Path(filename).suffix.lower()
+    is_code = suffix in CODE_SUFFIXES
+    lines = text.split("\n")
+    findings: List[Finding] = []
+    for rule in RULES:
+        if rule.code_only and not is_code:
+            continue
+        for m in rule.pattern.finditer(text):
+            matched = m.group(0)
+            if rule.accept and not rule.accept(matched):
+                continue
+            line_no = text.count("\n", 0, m.start()) + 1
+            line_text = lines[line_no - 1] if line_no - 1 < len(lines) else ""
+            if _ignored(line_text, rule.id):
+                continue
+            snippet = line_text.strip()
+            if rule.id == "SC006":
+                snippet = "U+%04X" % ord(matched[0])
+            elif rule.id.startswith("SC2") and len(matched) > 8:
+                snippet = matched[:4] + "..." + matched[-2:]
+            if any(f.rule == rule.id and f.line == line_no for f in findings):
+                continue
+            findings.append(Finding(rule.id, rule.severity, rule.title, filename, line_no, snippet[:120]))
+    # Reading credentials and sending data in the same file is a stronger signal.
+    ids = {f.rule for f in findings}
+    if "SC301" in ids and "SC302" in ids:
+        first = next(f for f in findings if f.rule == "SC301")
+        findings.append(Finding("SC310", "high", "Reads credentials and sends data over the network",
+                                filename, first.line, first.snippet))
+    return findings
+
+
+def scan_skill(target: Any) -> ScanResult:
+    base = Path(target)
+    if base.is_file():
+        base = base.parent
+    if not base.is_dir():
+        raise SkillError("not found: %s" % target)
+    res = ScanResult(skill=base.name, path=str(base))
+    for rel in iter_skill_files(base):
+        full = base / rel
+        name = rel.as_posix()
+        if full.suffix.lower() in BINARY_SUFFIXES:
+            res.findings.append(Finding("SC601", "medium", "Compiled or binary file bundled in skill", name, 0))
+            continue
+        try:
+            size = full.stat().st_size
+        except OSError:
+            continue
+        if size > MAX_FILE_BYTES:
+            res.findings.append(Finding("SC602", "low", "Very large file (not scanned)", name, 0))
+            continue
+        try:
+            data = full.read_bytes()
+        except OSError:
+            continue
+        if b"\x00" in data[:4096]:
+            continue
+        text = data.decode("utf-8", errors="replace")
+        res.files_scanned += 1
+        res.findings.extend(scan_text(text, name))
+    res.findings.sort(key=lambda f: (-SEVERITY_RANK[f.severity], f.file, f.line))
+    return res
+
+
+def exceeds(result: ScanResult, fail_on: str) -> bool:
+    """True when the scan has a finding at or above the given severity."""
+    if fail_on == "never":
+        return False
+    rank = SEVERITY_RANK.get(fail_on, 3)
+    return any(SEVERITY_RANK[f.severity] >= rank for f in result.findings)
+
+
+def redact(text: str) -> str:
+    """Mask secrets in free text (used when showing shell history)."""
+    out = text
+    for pat in SECRET_PATTERNS:
+        out = pat.sub("<redacted>", out)
+    out = re.sub(r"(?i)(--?(?:password|passwd|pass|token|secret|api[-_]?key|key)(?:=|\s+))(\S+)", r"\1<redacted>", out)
+    out = re.sub(r"\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD)[A-Z0-9_]*)=(\S+)", r"\1=<redacted>", out)
+    out = re.sub(r"(\bmysql(?:dump|admin)?\b[^\n]*?\s-p)(\S+)", r"\1<redacted>", out)
+    out = re.sub(r"(?i)(authorization:\s*(?:bearer|basic|token)\s+)\S+", r"\1<redacted>", out)
+    out = re.sub(r"(://[^/\s:@]+:)[^@\s/]+(@)", r"\1<redacted>\2", out)
+    return out

agentskill_kit/scoring.py

@@ -0,0 +1,93 @@
+"""Combine lint, scan and test results into a single quality score."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from . import runner
+from .lint import LintResult, lint_skill
+from .scan import ScanResult, scan_skill
+from .skillfile import SkillError, load_skill
+
+WEIGHTS_TESTED = {"lint": 0.30, "safety": 0.25, "tests": 0.35, "docs": 0.10}
+WEIGHTS_UNTESTED = {"lint": 0.45, "safety": 0.35, "docs": 0.20}
+
+
+@dataclass
+class Quality:
+    skill: str
+    score: float
+    grade: str
+    tested: bool
+    breakdown: Dict[str, float] = field(default_factory=dict)
+    lint: Optional[LintResult] = None
+    scan: Optional[ScanResult] = None
+    tests: Optional[runner.TestReport] = None
+
+    @property
+    def passes_gate(self) -> bool:
+        return bool(self.lint and not self.lint.errors and self.scan and self.scan.count("high") == 0
+                    and not (self.tests and self.tests.has_tests and self.tests.rate < 1.0))
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"skill": self.skill, "score": round(self.score, 3), "grade": self.grade,
+                "tested": self.tested, "breakdown": {k: round(v, 3) for k, v in self.breakdown.items()},
+                "lint": self.lint.to_dict() if self.lint else None,
+                "scan": self.scan.to_dict() if self.scan else None,
+                "tests": self.tests.to_dict() if self.tests else None}
+
+
+def grade_for(score: float) -> str:
+    for cutoff, letter in ((0.9, "A"), (0.8, "B"), (0.7, "C"), (0.5, "D")):
+        if score >= cutoff:
+            return letter
+    return "F"
+
+
+def docs_score(skill_dir: Path) -> float:
+    try:
+        skill = load_skill(skill_dir)
+    except SkillError:
+        return 0.0
+    body = skill.body
+    lines = [ln for ln in body.splitlines() if ln.strip()]
+    pts = 0.0
+    if len(skill.description) >= 60:
+        pts += 0.3
+    if re.search(r"^#{1,3}\s+\S", body, re.M):
+        pts += 0.2
+    if re.search(r"\bexamples?\b", body, re.I) or "```" in body:
+        pts += 0.2
+    if 12 <= len(lines) <= 500:
+        pts += 0.2
+    if skill.license or skill.version or skill.tags:
+        pts += 0.1
+    return min(1.0, pts)
+
+
+def evaluate_skill(skill_dir: Any, run_tests: bool = True, timeout: float = 20.0) -> Quality:
+    base = Path(skill_dir).resolve()
+    lint = lint_skill(base)
+    scan = scan_skill(base) if base.is_dir() else None
+    tests = runner.run_skill_tests(base, timeout=timeout) if (run_tests and base.is_dir()) else None
+    tested = bool(tests and tests.has_tests)
+    parts: Dict[str, float] = {
+        "lint": lint.score / 100.0,
+        "safety": (scan.safety / 100.0) if scan else 0.0,
+        "docs": docs_score(base) if base.is_dir() else 0.0,
+    }
+    if tested and tests is not None:
+        parts["tests"] = tests.rate
+        weights = WEIGHTS_TESTED
+    else:
+        weights = WEIGHTS_UNTESTED
+    score = sum(parts[k] * w for k, w in weights.items())
+    if lint.errors:
+        score = min(score, 0.59)
+    if scan and scan.count("high"):
+        score = min(score, 0.49)
+    return Quality(skill=lint.skill, score=score, grade=grade_for(score), tested=tested,
+                   breakdown=parts, lint=lint, scan=scan, tests=tests)

agentskill_kit/server.py

@@ -0,0 +1,69 @@
+"""Local web UI for browsing the skills on this machine."""
+
+from __future__ import annotations
+
+import json
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from . import registry
+from .site import render_site
+
+
+def default_roots() -> List[Path]:
+    cwd = Path.cwd()
+    cands = [cwd / "skills", cwd / ".claude" / "skills", cwd / ".hermes" / "skills",
+             Path.home() / ".claude" / "skills", Path.home() / ".hermes" / "skills"]
+    out, seen = [], set()
+    for c in cands:
+        if c.is_dir() and str(c.resolve()) not in seen:
+            out.append(c)
+            seen.add(str(c.resolve()))
+    return out
+
+
+def make_handler(build: Callable[[], Dict[str, Any]]):
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, fmt, *args):  # keep the terminal quiet
+            return
+
+        def _send(self, code: int, body: bytes, ctype: str) -> None:
+            self.send_response(code)
+            self.send_header("Content-Type", ctype)
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Cache-Control", "no-store")
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self):
+            path = self.path.split("?", 1)[0]
+            if path in ("/", "/index.html"):
+                self._send(200, render_site(build(), "Local skills").encode("utf-8"), "text/html; charset=utf-8")
+            elif path == "/index.json":
+                self._send(200, json.dumps(build(), ensure_ascii=False).encode("utf-8"), "application/json")
+            else:
+                self._send(404, b"not found", "text/plain; charset=utf-8")
+
+    return Handler
+
+
+def serve(roots: List[Path], host: str = "127.0.0.1", port: int = 8765, open_browser: bool = False,
+          on_ready: Optional[Callable[[str], None]] = None) -> None:
+    def build() -> Dict[str, Any]:
+        return registry.build_index(roots, name="local skills", run_tests=False, relative_to=Path.cwd())
+
+    server = ThreadingHTTPServer((host, port), make_handler(build))
+    url = "http://%s:%d/" % (host, server.server_address[1])
+    if on_ready:
+        on_ready(url)
+    if open_browser:
+        webbrowser.open(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()

agentskill_kit/site.py

@@ -0,0 +1,24 @@
+"""Render the registry web page (static file, used by `registry site` and `serve`)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict
+
+TEMPLATE = Path(__file__).with_name("templates") / "site.html"
+
+
+def render_site(index: Dict[str, Any], title: str = "agentskill-kit skill registry") -> str:
+    html = TEMPLATE.read_text(encoding="utf-8")
+    data = json.dumps(index, ensure_ascii=False).replace("</", "<\\/").replace("\u2028", "\\u2028").replace("\u2029", "\\u2029")
+    return html.replace("__TITLE__", title.replace("<", "&lt;")).replace("__DATA__", data)
+
+
+def write_site(index: Dict[str, Any], out_dir: Any, title: str = "agentskill-kit skill registry") -> Path:
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "index.html").write_text(render_site(index, title), encoding="utf-8")
+    (out / "index.json").write_text(json.dumps(index, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (out / ".nojekyll").write_text("", encoding="utf-8")
+    return out / "index.html"