skillprint 0.1.0__tar.gz

skillprint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mekala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skillprint-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: skillprint
+Version: 0.1.0
+Summary: See what an agent skill pack loads and runs before you install it.
+Author: mekala
+License: MIT
+Project-URL: Homepage, https://github.com/mekala540/skillprint
+Project-URL: Issues, https://github.com/mekala540/skillprint/issues
+Keywords: ai-agents,agent-skills,claude-code,cursor,codex,security,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# skillprint
+
+[![tests](https://github.com/mekala540/skillprint/actions/workflows/tests.yml/badge.svg)](https://github.com/mekala540/skillprint/actions/workflows/tests.yml) ![license](https://img.shields.io/badge/license-MIT-blue) ![python](https://img.shields.io/badge/python-3.9%2B-blue)
+
+**See what an agent skill pack loads and runs — before you install it.**
+
+Skill packs for Claude Code, Cursor, Codex and OpenClaw now collect hundreds of thousands of stars. Stars tell you a pack is popular. They don't tell you that it adds 25,000 tokens to every session, or registers 27 hooks that run code before your agent's tool calls.
+
+`skillprint` reads a pack and reports:
+
+- **Context cost** — tokens loaded up front every session (skill names and descriptions) and tokens loaded when skills are used
+- **Auto-run hooks** — what runs without you asking, grouped per tool config, and how many fire on every prompt or tool call
+- **What its code can do** — shell commands, destructive commands, package installs, credential and secret access, download-into-shell, hidden Unicode, network domains
+- **A footprint level** — `low` (instructions only), `medium` (ships scripts or session hooks), `high` (hooks on every action, download-into-shell, or hidden characters)
+
+It is not a malware scanner. Snyk Agent Scan, Mondoo, Socket and VirusTotal already do that. skillprint answers a different question: *what am I actually signing up for?*
+
+## Install
+
+```bash
+pipx install skillprint        # or: pip install skillprint
+```
+
+No dependencies. Python 3.9+.
+
+## Use
+
+```bash
+skillprint ./my-skills                              # a local folder
+skillprint https://github.com/obra/superpowers      # any git URL
+skillprint ./my-skills --details                    # every hook, finding, and the largest skills
+skillprint ./my-skills --json                       # machine-readable
+skillprint ./my-skills --badge                      # README badge markdown
+skillprint ./my-skills --fail-on high               # exit 1 in CI if footprint is high
+```
+
+## What the biggest packs look like (scanned 11 Oct 2026)
+
+| Pack | Stars | Footprint | Skills | Tokens up front | Auto-run hooks (main config) | Scripts |
+| --- | --- | --- | --- | --- | --- | --- |
+| [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) | 212k | low | 1 | ≈60 | 0 | 0 |
+| [obra/superpowers](https://github.com/obra/superpowers) | 285k | medium | 15 | ≈670 | 1 (session start) | 23 |
+| [mattpocock/skills](https://github.com/mattpocock/skills) | 260k | medium | 38 | ≈1,500 | 0 | 7 |
+| [affaan-m/ECC](https://github.com/affaan-m/ECC) | 257k | high | 314 | ≈25,600 | 27, of which 15 fire on every prompt or tool call | 736 |
+
+None of these showed signs of malice. They differ by 400× in context cost and from zero to dozens of auto-run hooks — which is exactly what a star count hides.
+
+## How it decides
+
+- **Skills** are found by `SKILL.md`. Copies of the same skill (per-tool folders, translations) count once; the canonical copy is preferred.
+- **Up-front tokens** = name + description of each skill, which agents load into every session so they know what's available. **On-use tokens** = the skill bodies. Both are estimated as characters ÷ 4.
+- **Hooks** are read from any JSON config with a `hooks` block (Claude Code, Cursor, Codex, Qoder formats), grouped by file, since you install one tool's config.
+- **Capability patterns** are matched only where code can run: scripts, hook commands, and fenced code blocks inside `SKILL.md`. Mentions in docs and prose are counted separately and ignored — a security guide that says "never `curl | bash`" is not a finding. Test files are skipped.
+- Counts describe **capability, not intent**. A `rm -rf "$TMP_DIR"` in a cleanup script is normal. Read the `--details` output before judging.
+
+## Use it in CI
+
+```yaml
+# .github/workflows/skillprint.yml
+name: skillprint
+on: [pull_request]
+jobs:
+  footprint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install skillprint
+      - run: skillprint . --details --fail-on high
+```
+
+## Roadmap
+
+- [x] Footprint: context cost, hooks, capabilities, badge, CI mode
+- [ ] Exact token counts per model tokenizer
+- [ ] Diff mode: what changed between two versions of a pack
+- [ ] **Lift**: run a fixed task suite with and without a skill, per model, and report whether it actually helps
+- [ ] Public ratings page for the most-starred skills
+- [ ] Pull in Snyk / Socket / VirusTotal verdicts where they exist
+
+## Contributing
+
+Found a false positive or a pattern we miss? Open an issue with the file and line. Rules live in `skillprint/scan.py` and every rule has a test in `tests/`.
+
+```bash
+pip install -e . pytest && pytest
+```
+
+## License
+
+MIT

skillprint-0.1.0/README.md

@@ -0,0 +1,92 @@
+# skillprint
+
+[![tests](https://github.com/mekala540/skillprint/actions/workflows/tests.yml/badge.svg)](https://github.com/mekala540/skillprint/actions/workflows/tests.yml) ![license](https://img.shields.io/badge/license-MIT-blue) ![python](https://img.shields.io/badge/python-3.9%2B-blue)
+
+**See what an agent skill pack loads and runs — before you install it.**
+
+Skill packs for Claude Code, Cursor, Codex and OpenClaw now collect hundreds of thousands of stars. Stars tell you a pack is popular. They don't tell you that it adds 25,000 tokens to every session, or registers 27 hooks that run code before your agent's tool calls.
+
+`skillprint` reads a pack and reports:
+
+- **Context cost** — tokens loaded up front every session (skill names and descriptions) and tokens loaded when skills are used
+- **Auto-run hooks** — what runs without you asking, grouped per tool config, and how many fire on every prompt or tool call
+- **What its code can do** — shell commands, destructive commands, package installs, credential and secret access, download-into-shell, hidden Unicode, network domains
+- **A footprint level** — `low` (instructions only), `medium` (ships scripts or session hooks), `high` (hooks on every action, download-into-shell, or hidden characters)
+
+It is not a malware scanner. Snyk Agent Scan, Mondoo, Socket and VirusTotal already do that. skillprint answers a different question: *what am I actually signing up for?*
+
+## Install
+
+```bash
+pipx install skillprint        # or: pip install skillprint
+```
+
+No dependencies. Python 3.9+.
+
+## Use
+
+```bash
+skillprint ./my-skills                              # a local folder
+skillprint https://github.com/obra/superpowers      # any git URL
+skillprint ./my-skills --details                    # every hook, finding, and the largest skills
+skillprint ./my-skills --json                       # machine-readable
+skillprint ./my-skills --badge                      # README badge markdown
+skillprint ./my-skills --fail-on high               # exit 1 in CI if footprint is high
+```
+
+## What the biggest packs look like (scanned 11 Oct 2026)
+
+| Pack | Stars | Footprint | Skills | Tokens up front | Auto-run hooks (main config) | Scripts |
+| --- | --- | --- | --- | --- | --- | --- |
+| [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) | 212k | low | 1 | ≈60 | 0 | 0 |
+| [obra/superpowers](https://github.com/obra/superpowers) | 285k | medium | 15 | ≈670 | 1 (session start) | 23 |
+| [mattpocock/skills](https://github.com/mattpocock/skills) | 260k | medium | 38 | ≈1,500 | 0 | 7 |
+| [affaan-m/ECC](https://github.com/affaan-m/ECC) | 257k | high | 314 | ≈25,600 | 27, of which 15 fire on every prompt or tool call | 736 |
+
+None of these showed signs of malice. They differ by 400× in context cost and from zero to dozens of auto-run hooks — which is exactly what a star count hides.
+
+## How it decides
+
+- **Skills** are found by `SKILL.md`. Copies of the same skill (per-tool folders, translations) count once; the canonical copy is preferred.
+- **Up-front tokens** = name + description of each skill, which agents load into every session so they know what's available. **On-use tokens** = the skill bodies. Both are estimated as characters ÷ 4.
+- **Hooks** are read from any JSON config with a `hooks` block (Claude Code, Cursor, Codex, Qoder formats), grouped by file, since you install one tool's config.
+- **Capability patterns** are matched only where code can run: scripts, hook commands, and fenced code blocks inside `SKILL.md`. Mentions in docs and prose are counted separately and ignored — a security guide that says "never `curl | bash`" is not a finding. Test files are skipped.
+- Counts describe **capability, not intent**. A `rm -rf "$TMP_DIR"` in a cleanup script is normal. Read the `--details` output before judging.
+
+## Use it in CI
+
+```yaml
+# .github/workflows/skillprint.yml
+name: skillprint
+on: [pull_request]
+jobs:
+  footprint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install skillprint
+      - run: skillprint . --details --fail-on high
+```
+
+## Roadmap
+
+- [x] Footprint: context cost, hooks, capabilities, badge, CI mode
+- [ ] Exact token counts per model tokenizer
+- [ ] Diff mode: what changed between two versions of a pack
+- [ ] **Lift**: run a fixed task suite with and without a skill, per model, and report whether it actually helps
+- [ ] Public ratings page for the most-starred skills
+- [ ] Pull in Snyk / Socket / VirusTotal verdicts where they exist
+
+## Contributing
+
+Found a false positive or a pattern we miss? Open an issue with the file and line. Rules live in `skillprint/scan.py` and every rule has a test in `tests/`.
+
+```bash
+pip install -e . pytest && pytest
+```
+
+## License
+
+MIT

skillprint-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skillprint"
+version = "0.1.0"
+description = "See what an agent skill pack loads and runs before you install it."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "mekala" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["ai-agents", "agent-skills", "claude-code", "cursor", "codex", "security", "mcp"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Security",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+skillprint = "skillprint.cli:main"
+
+[tool.setuptools]
+packages = ["skillprint"]
+
+[project.urls]
+Homepage = "https://github.com/mekala540/skillprint"
+Issues = "https://github.com/mekala540/skillprint/issues"

skillprint-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skillprint-0.1.0/skillprint/__init__.py

@@ -0,0 +1,2 @@
+"""skillprint: see what an agent skill pack loads and runs before you install it."""
+__version__ = "0.1.0"

skillprint-0.1.0/skillprint/cli.py

@@ -0,0 +1,128 @@
+"""Command line: skillprint <path-or-git-url> [--json] [--badge] [--details]"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from urllib.parse import quote
+
+from . import __version__
+from .scan import scan, Report, HOOK_EVENTS_EVERY_ACTION
+
+LABELS = {
+    "shell_exec": "runs shell commands",
+    "pipe_to_shell": "pipes a download into a shell",
+    "destructive": "destructive commands (rm -rf, force push)",
+    "secrets_access": "reads credential files",
+    "env_secrets": "reads secret env vars",
+    "auto_install": "installs packages",
+    "hidden_unicode": "hidden Unicode characters",
+}
+COLORS = {"none": "brightgreen", "low": "green", "medium": "yellow", "high": "orange"}
+
+
+def _fmt(n: int) -> str:
+    return f"{n:,}"
+
+
+def badge(r: Report) -> str:
+    biggest = max((len(v) for v in r.hooks_by_config().values()), default=0)
+    msg = f"{r.footprint} footprint · {_fmt(r.upfront_tokens)} tokens · {biggest} hooks"
+    url = f"https://img.shields.io/badge/skillprint-{quote(msg.replace('-', '--'))}-{COLORS[r.footprint]}"
+    return f"[![skillprint]({url})](https://github.com/mekala540/skillprint)"
+
+
+def text_report(r: Report, details: bool) -> str:
+    out = []
+    out.append(f"skillprint {__version__} · {r.root}")
+    out.append("")
+    out.append(f"  Footprint            {r.footprint.upper()}")
+    copies = f" ({_fmt(r.skill_files)} SKILL.md files incl. copies)" if r.skill_files != len(r.skills) else ""
+    out.append(f"  Skills               {_fmt(len(r.skills))}{copies}")
+    out.append(f"  Loaded up front      ≈{_fmt(r.upfront_tokens)} tokens (names + descriptions, every session)")
+    out.append(f"  Loaded when used     ≈{_fmt(r.on_use_tokens)} tokens (all skill bodies)")
+    out.append(f"  Scripts              {_fmt(len(r.scripts))}")
+    groups = r.hooks_by_config()
+    if not groups:
+        out.append("  Auto-run hooks       0")
+    for i, (src, hs) in enumerate(groups.items()):
+        every = sum(1 for h in hs if h.event.lower() in HOOK_EVENTS_EVERY_ACTION)
+        events = ", ".join(sorted({h.event for h in hs}))
+        head = "  Auto-run hooks       " if i == 0 else "                       "
+        tail = f", {every} on every prompt or tool call" if every else ""
+        out.append(f"{head}{len(hs):>3} in {src}{tail}")
+        out.append(f"                         [{events}]")
+    counts = r.finding_counts()
+    out.append("")
+    out.append("  What its code can do (scripts, hook commands, code blocks in skills):")
+    if not counts:
+        out.append("    nothing flagged")
+    for k, v in sorted(counts.items(), key=lambda kv: -kv[1]):
+        out.append(f"    {v:>5}  {LABELS.get(k, k)}")
+    if r.network_domains:
+        top = ", ".join(list(dict(sorted(r.network_domains.items(), key=lambda kv: -kv[1])))[:6])
+        out.append(f"    domains: {top}")
+    ignored = sum(r.doc_mentions.values())
+    if ignored:
+        out.append(f"  ({_fmt(ignored)} pattern matches in docs and prose ignored: they describe, they don't run)")
+    if r.test_files:
+        out.append(f"  ({_fmt(r.test_files)} test files skipped: they don't ship to the agent)")
+    if details:
+        out.append("")
+        out.append("  Hooks:")
+        for h in r.hooks:
+            out.append(f"    {h.event:<20} {h.command[:90]}   ({h.source})")
+        out.append("  Findings:")
+        for f in r.findings:
+            out.append(f"    {f.kind:<15} {f.path}:{f.line}  {f.excerpt}")
+        out.append("  Largest skills (tokens up front / when used):")
+        for s in sorted(r.skills, key=lambda s: -s.body_tokens)[:10]:
+            out.append(f"    {s.description_tokens:>5} / {s.body_tokens:>6}  {s.name}")
+    out.append("")
+    out.append("  Counts describe capability, not intent. Token figures are estimates (chars / 4).")
+    return "\n".join(out)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="skillprint", description="Measure what an agent skill pack loads and runs.")
+    p.add_argument("target", help="path to a skill pack, or a git URL")
+    p.add_argument("--json", action="store_true", help="machine-readable output")
+    p.add_argument("--badge", action="store_true", help="print a README badge")
+    p.add_argument("--details", action="store_true", help="list every hook, finding and the largest skills")
+    p.add_argument("--fail-on", choices=["medium", "high"], help="exit 1 if footprint is at least this (for CI)")
+    p.add_argument("--version", action="version", version=__version__)
+    a = p.parse_args(argv)
+
+    tmp = None
+    target = a.target
+    if target.startswith(("https://", "git@")):
+        tmp = tempfile.mkdtemp(prefix="skillprint-")
+        res = subprocess.run(["git", "clone", "--depth", "1", "-q", target, tmp], capture_output=True, text=True)
+        if res.returncode:
+            print(f"could not clone {target}: {res.stderr.strip()}", file=sys.stderr)
+            return 2
+        target = tmp
+    try:
+        r = scan(target)
+        if tmp:
+            r.root = a.target
+        if a.json:
+            print(json.dumps(r.to_dict(), indent=2))
+        elif a.badge:
+            print(badge(r))
+        else:
+            print(text_report(r, a.details))
+        order = ["none", "low", "medium", "high"]
+        if a.fail_on and order.index(r.footprint) >= order.index(a.fail_on):
+            return 1
+        return 0
+    finally:
+        if tmp:
+            shutil.rmtree(tmp, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

skillprint-0.1.0/skillprint/scan.py

@@ -0,0 +1,289 @@
+"""Core scanner: walks a skill pack and measures what it loads and what it runs."""
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+
+SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", "dist", "build"}
+BINARY_EXT = {
+    "png", "jpg", "jpeg", "gif", "webp", "ico", "svg", "pdf", "zip", "gz", "tgz",
+    "woff", "woff2", "ttf", "otf", "mp4", "mov", "mp3", "wav", "so", "dylib", "dll",
+    "exe", "bin", "lock",
+}
+SCRIPT_EXT = {"sh", "bash", "zsh", "py", "js", "mjs", "cjs", "ts", "ps1", "cmd", "bat", "rb", "pl"}
+CONFIG_EXT = {"json", "yaml", "yml", "toml"}
+MAX_BYTES = 1_000_000
+
+# Hook events that fire on every prompt or tool call (Claude Code, Cursor, Codex naming).
+HOOK_EVENTS_EVERY_ACTION = {
+    "pretooluse", "posttooluse", "posttoolusefailure", "userpromptsubmit",
+    "beforeshellexecution", "aftershellexecution", "beforemcpexecution", "aftermcpexecution",
+    "beforereadfile", "afterfileedit", "beforesubmitprompt", "beforetabfileread", "aftertabfileedit",
+}
+TEST_PATH = re.compile(r"(^|/)(tests?|__tests__|spec|fixtures?)(/|$)|(\.test\.|\.spec\.|_test\.py$|(^|/)test_[^/]*\.py$)")
+PLACEHOLDER_DOMAIN = re.compile(r"(^|\.)(example\.(com|org|net|test)|localhost|w3\.org|schema\.org|test|invalid)$")
+
+# Capability patterns. They describe what code CAN do, not intent.
+PATTERNS = {
+    "shell_exec": r"(subprocess\.|child_process|\bexecSync\(|\bexec\(|os\.system\(|\bspawn(Sync)?\(|\bbash -c\b)",
+    "pipe_to_shell": r"(curl|wget)\b[^\n|]*\|\s*(sudo\s+)?(ba|z)?sh\b",
+    "destructive": r"(rm\s+-[a-z]*r[a-z]*f|rm\s+-[a-z]*f[a-z]*r|git\s+push\s+(-f|--force)|git\s+reset\s+--hard|DROP\s+TABLE|mkfs\.)",
+    "secrets_access": r"(~/\.ssh|\.ssh/id_|~/\.aws|\.aws/credentials|security\s+find-(generic|internet)-password|SecItemCopyMatching|\bkeytar\b|\.netrc\b|~/\.npmrc|~/\.pypirc)",
+    "env_secrets": r"(process\.env\.[A-Z_]*(KEY|TOKEN|SECRET)|os\.environ(\.get)?\(?\[?['\"][A-Z_]*(KEY|TOKEN|SECRET))",
+    "auto_install": r"(\bnpm\s+(i|install)\b|\bpip3?\s+install\b|\bnpx\s+-y\b|\bbrew\s+install\b|\bcargo\s+install\b|\bgo\s+install\b)",
+}
+HIDDEN_UNICODE = re.compile("[​‌‍⁠‪-‮⁦-⁩]")
+URL_RE = re.compile(r"https?://([A-Za-z0-9.-]+\.[A-Za-z]{2,})")
+FRONTMATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n", re.S)
+
+
+def est_tokens(text: str) -> int:
+    """Rough token estimate (characters / 4). Good enough to compare packs."""
+    return (len(text) + 3) // 4
+
+
+@dataclass
+class Skill:
+    name: str
+    path: str
+    description_tokens: int
+    body_tokens: int
+
+
+@dataclass
+class Hook:
+    event: str
+    command: str
+    source: str
+
+
+@dataclass
+class Finding:
+    kind: str
+    path: str
+    line: int
+    excerpt: str
+
+
+@dataclass
+class Report:
+    root: str
+    files: int = 0
+    skills: list[Skill] = field(default_factory=list)
+    skill_files: int = 0
+    scripts: list[str] = field(default_factory=list)
+    hooks: list[Hook] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+    doc_mentions: dict[str, int] = field(default_factory=dict)
+    test_files: int = 0
+    network_domains: dict[str, int] = field(default_factory=dict)
+
+    # ---- derived numbers -------------------------------------------------
+    @property
+    def upfront_tokens(self) -> int:
+        return sum(s.description_tokens for s in self.skills)
+
+    @property
+    def on_use_tokens(self) -> int:
+        return sum(s.body_tokens for s in self.skills)
+
+    @property
+    def hooks_every_action(self) -> int:
+        return sum(1 for h in self.hooks if h.event.lower() in HOOK_EVENTS_EVERY_ACTION)
+
+    def hooks_by_config(self) -> dict[str, list[Hook]]:
+        """Packs often ship one hook config per tool; a user installs one of them."""
+        out: dict[str, list[Hook]] = {}
+        for h in self.hooks:
+            out.setdefault(h.source, []).append(h)
+        return dict(sorted(out.items(), key=lambda kv: -len(kv[1])))
+
+    def finding_counts(self) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for f in self.findings:
+            out[f.kind] = out.get(f.kind, 0) + 1
+        return out
+
+    @property
+    def footprint(self) -> str:
+        """none < low < medium < high, from what runs without being asked."""
+        c = self.finding_counts()
+        if self.hooks_every_action or c.get("pipe_to_shell") or c.get("hidden_unicode"):
+            return "high"
+        if self.hooks or self.scripts:
+            return "medium"
+        if self.skills:
+            return "low"
+        return "none"
+
+    def to_dict(self) -> dict:
+        return {
+            "root": self.root,
+            "footprint": self.footprint,
+            "files": self.files,
+            "skills_unique": len(self.skills),
+            "skill_files": self.skill_files,
+            "upfront_tokens": self.upfront_tokens,
+            "on_use_tokens": self.on_use_tokens,
+            "scripts": len(self.scripts),
+            "hooks": len(self.hooks),
+            "hooks_every_action": self.hooks_every_action,
+            "hook_events": sorted({h.event for h in self.hooks}),
+            "hooks_by_config": {k: len(v) for k, v in self.hooks_by_config().items()},
+            "test_files_skipped": self.test_files,
+            "findings": self.finding_counts(),
+            "doc_mentions_ignored": self.doc_mentions,
+            "network_domains": dict(sorted(self.network_domains.items(), key=lambda kv: -kv[1])),
+            "skills": [asdict(s) for s in self.skills],
+            "hook_list": [asdict(h) for h in self.hooks],
+            "finding_list": [asdict(f) for f in self.findings],
+        }
+
+
+# ---- helpers -------------------------------------------------------------
+
+def _iter_files(root: Path):
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        for name in filenames:
+            yield Path(dirpath) / name
+
+
+def _read_text(path: Path) -> str | None:
+    if path.suffix.lower().lstrip(".") in BINARY_EXT:
+        return None
+    try:
+        if path.stat().st_size > MAX_BYTES:
+            return None
+        raw = path.read_bytes()
+    except OSError:
+        return None
+    if b"\x00" in raw[:4096]:
+        return None
+    return raw.decode("utf-8", errors="ignore")
+
+
+def _is_script(path: Path, text: str) -> bool:
+    return path.suffix.lower().lstrip(".") in SCRIPT_EXT or text.startswith("#!")
+
+
+def _parse_frontmatter(text: str) -> dict[str, str]:
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return {}
+    fields: dict[str, str] = {}
+    key = None
+    for line in m.group(1).splitlines():
+        km = re.match(r"^([A-Za-z_][\w-]*):\s*(.*)$", line)
+        if km:
+            key = km.group(1).lower()
+            fields[key] = km.group(2).strip()
+        elif key and line.startswith((" ", "\t")):
+            fields[key] += " " + line.strip()
+    return fields
+
+
+def _rank(path: str) -> tuple:
+    """Prefer the canonical copy of a skill: not under docs/, then the shortest path."""
+    return (path.startswith("docs"), path.count("/"), len(path))
+
+
+def _code_blocks(markdown: str) -> str:
+    """Only fenced code in a SKILL.md is something the agent may run."""
+    return "\n".join(re.findall(r"```[^\n]*\n(.*?)```", markdown, re.S))
+
+
+def _collect_hooks(data, source: str) -> list[Hook]:
+    hooks: list[Hook] = []
+    block = data.get("hooks") if isinstance(data, dict) else None
+    if not isinstance(block, dict):
+        return hooks
+    for event, entries in block.items():
+        if not isinstance(entries, list):
+            continue
+        for entry in entries:
+            inner = entry.get("hooks") if isinstance(entry, dict) else None
+            cmds = inner if isinstance(inner, list) else [entry]
+            for c in cmds:
+                cmd = c.get("command", "") if isinstance(c, dict) else str(c)
+                hooks.append(Hook(event=event, command=str(cmd)[:200], source=source))
+    return hooks
+
+
+def _scan_text(rel: str, text: str, report: Report, as_findings: bool) -> None:
+    for kind, pat in PATTERNS.items():
+        for m in re.finditer(pat, text, re.I):
+            if as_findings:
+                line = text.count("\n", 0, m.start()) + 1
+                excerpt = text.splitlines()[line - 1].strip()[:140] if text else ""
+                report.findings.append(Finding(kind, rel, line, excerpt))
+            else:
+                report.doc_mentions[kind] = report.doc_mentions.get(kind, 0) + 1
+    if as_findings:
+        for m in HIDDEN_UNICODE.finditer(text):
+            line = text.count("\n", 0, m.start()) + 1
+            report.findings.append(Finding("hidden_unicode", rel, line, f"U+{ord(m.group()):04X}"))
+            break
+        for m in URL_RE.finditer(text):
+            d = m.group(1).lower()
+            if PLACEHOLDER_DOMAIN.search(d):
+                continue
+            report.network_domains[d] = report.network_domains.get(d, 0) + 1
+
+
+# ---- main entry ----------------------------------------------------------
+
+def scan(root: str | os.PathLike) -> Report:
+    root = Path(root).resolve()
+    report = Report(root=str(root))
+    seen_skills: dict[str, Skill] = {}
+
+    for path in _iter_files(root):
+        rel = str(path.relative_to(root))
+        text = _read_text(path)
+        report.files += 1
+        if text is None:
+            continue
+
+        if path.name == "SKILL.md":
+            report.skill_files += 1
+            fm = _parse_frontmatter(text)
+            name = fm.get("name") or path.parent.name
+            desc = fm.get("description", "")
+            body = FRONTMATTER_RE.sub("", text, count=1)
+            key = name.strip().lower()
+            cand = Skill(name, rel, est_tokens(f"{name}: {desc}"), est_tokens(body))
+            prev = seen_skills.get(key)  # copies for other tools or languages count once
+            if prev is None or _rank(cand.path) < _rank(prev.path):
+                seen_skills[key] = cand
+            _scan_text(rel, _code_blocks(text), report, as_findings=True)
+            _scan_text(rel, re.sub(r"```.*?```", "", text, flags=re.S), report, as_findings=False)
+            continue
+
+        if TEST_PATH.search(rel.replace(os.sep, "/")):
+            report.test_files += 1  # tests are not installed into the agent
+            continue
+
+        if _is_script(path, text):
+            report.scripts.append(rel)
+            _scan_text(rel, text, report, as_findings=True)
+            continue
+
+        if path.suffix.lower().lstrip(".") == "json" and "hooks" in text:
+            try:
+                new = _collect_hooks(json.loads(text), rel)
+                report.hooks.extend(new)
+                for h in new:  # a hook command runs without asking, so it counts
+                    _scan_text(rel, h.command, report, as_findings=True)
+            except ValueError:
+                pass
+            continue
+
+        if path.suffix.lower().lstrip(".") not in CONFIG_EXT:
+            _scan_text(rel, text, report, as_findings=False)  # docs: counted, not flagged
+
+    report.skills = sorted(seen_skills.values(), key=lambda s: s.path)
+    return report

skillprint-0.1.0/skillprint.egg-info/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: skillprint
+Version: 0.1.0
+Summary: See what an agent skill pack loads and runs before you install it.
+Author: mekala
+License: MIT
+Project-URL: Homepage, https://github.com/mekala540/skillprint
+Project-URL: Issues, https://github.com/mekala540/skillprint/issues
+Keywords: ai-agents,agent-skills,claude-code,cursor,codex,security,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# skillprint
+
+[![tests](https://github.com/mekala540/skillprint/actions/workflows/tests.yml/badge.svg)](https://github.com/mekala540/skillprint/actions/workflows/tests.yml) ![license](https://img.shields.io/badge/license-MIT-blue) ![python](https://img.shields.io/badge/python-3.9%2B-blue)
+
+**See what an agent skill pack loads and runs — before you install it.**
+
+Skill packs for Claude Code, Cursor, Codex and OpenClaw now collect hundreds of thousands of stars. Stars tell you a pack is popular. They don't tell you that it adds 25,000 tokens to every session, or registers 27 hooks that run code before your agent's tool calls.
+
+`skillprint` reads a pack and reports:
+
+- **Context cost** — tokens loaded up front every session (skill names and descriptions) and tokens loaded when skills are used
+- **Auto-run hooks** — what runs without you asking, grouped per tool config, and how many fire on every prompt or tool call
+- **What its code can do** — shell commands, destructive commands, package installs, credential and secret access, download-into-shell, hidden Unicode, network domains
+- **A footprint level** — `low` (instructions only), `medium` (ships scripts or session hooks), `high` (hooks on every action, download-into-shell, or hidden characters)
+
+It is not a malware scanner. Snyk Agent Scan, Mondoo, Socket and VirusTotal already do that. skillprint answers a different question: *what am I actually signing up for?*
+
+## Install
+
+```bash
+pipx install skillprint        # or: pip install skillprint
+```
+
+No dependencies. Python 3.9+.
+
+## Use
+
+```bash
+skillprint ./my-skills                              # a local folder
+skillprint https://github.com/obra/superpowers      # any git URL
+skillprint ./my-skills --details                    # every hook, finding, and the largest skills
+skillprint ./my-skills --json                       # machine-readable
+skillprint ./my-skills --badge                      # README badge markdown
+skillprint ./my-skills --fail-on high               # exit 1 in CI if footprint is high
+```
+
+## What the biggest packs look like (scanned 11 Oct 2026)
+
+| Pack | Stars | Footprint | Skills | Tokens up front | Auto-run hooks (main config) | Scripts |
+| --- | --- | --- | --- | --- | --- | --- |
+| [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) | 212k | low | 1 | ≈60 | 0 | 0 |
+| [obra/superpowers](https://github.com/obra/superpowers) | 285k | medium | 15 | ≈670 | 1 (session start) | 23 |
+| [mattpocock/skills](https://github.com/mattpocock/skills) | 260k | medium | 38 | ≈1,500 | 0 | 7 |
+| [affaan-m/ECC](https://github.com/affaan-m/ECC) | 257k | high | 314 | ≈25,600 | 27, of which 15 fire on every prompt or tool call | 736 |
+
+None of these showed signs of malice. They differ by 400× in context cost and from zero to dozens of auto-run hooks — which is exactly what a star count hides.
+
+## How it decides
+
+- **Skills** are found by `SKILL.md`. Copies of the same skill (per-tool folders, translations) count once; the canonical copy is preferred.
+- **Up-front tokens** = name + description of each skill, which agents load into every session so they know what's available. **On-use tokens** = the skill bodies. Both are estimated as characters ÷ 4.
+- **Hooks** are read from any JSON config with a `hooks` block (Claude Code, Cursor, Codex, Qoder formats), grouped by file, since you install one tool's config.
+- **Capability patterns** are matched only where code can run: scripts, hook commands, and fenced code blocks inside `SKILL.md`. Mentions in docs and prose are counted separately and ignored — a security guide that says "never `curl | bash`" is not a finding. Test files are skipped.
+- Counts describe **capability, not intent**. A `rm -rf "$TMP_DIR"` in a cleanup script is normal. Read the `--details` output before judging.
+
+## Use it in CI
+
+```yaml
+# .github/workflows/skillprint.yml
+name: skillprint
+on: [pull_request]
+jobs:
+  footprint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install skillprint
+      - run: skillprint . --details --fail-on high
+```
+
+## Roadmap
+
+- [x] Footprint: context cost, hooks, capabilities, badge, CI mode
+- [ ] Exact token counts per model tokenizer
+- [ ] Diff mode: what changed between two versions of a pack
+- [ ] **Lift**: run a fixed task suite with and without a skill, per model, and report whether it actually helps
+- [ ] Public ratings page for the most-starred skills
+- [ ] Pull in Snyk / Socket / VirusTotal verdicts where they exist
+
+## Contributing
+
+Found a false positive or a pattern we miss? Open an issue with the file and line. Rules live in `skillprint/scan.py` and every rule has a test in `tests/`.
+
+```bash
+pip install -e . pytest && pytest
+```
+
+## License
+
+MIT

skillprint-0.1.0/skillprint.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+skillprint/__init__.py
+skillprint/cli.py
+skillprint/scan.py
+skillprint.egg-info/PKG-INFO
+skillprint.egg-info/SOURCES.txt
+skillprint.egg-info/dependency_links.txt
+skillprint.egg-info/entry_points.txt
+skillprint.egg-info/top_level.txt
+tests/test_scan.py

skillprint-0.1.0/skillprint.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

skillprint-0.1.0/skillprint.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skillprint = skillprint.cli:main

skillprint-0.1.0/skillprint.egg-info/top_level.txt

@@ -0,0 +1 @@
+skillprint

skillprint-0.1.0/tests/test_scan.py

@@ -0,0 +1,122 @@
+import json
+from pathlib import Path
+
+from skillprint.scan import scan
+from skillprint.cli import main
+
+
+def write(root: Path, rel: str, text: str) -> None:
+    p = root / rel
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(text, encoding="utf-8")
+
+
+SKILL = "---\nname: {n}\ndescription: {d}\n---\n\n# {n}\n\nDo the thing.\n"
+
+
+def test_instructions_only_pack_is_low(tmp_path):
+    write(tmp_path, "skills/a/SKILL.md", SKILL.format(n="a", d="Write tests first"))
+    r = scan(tmp_path)
+    assert len(r.skills) == 1
+    assert r.footprint == "low"
+    assert r.upfront_tokens > 0 and not r.findings
+
+
+def test_copies_of_a_skill_count_once(tmp_path):
+    for d in ("skills", ".cursor/skills", "docs/es/skills"):
+        write(tmp_path, f"{d}/a/SKILL.md", SKILL.format(n="a", d="Same skill"))
+    r = scan(tmp_path)
+    assert r.skill_files == 3 and len(r.skills) == 1
+
+
+def test_docs_mentions_are_not_findings(tmp_path):
+    write(tmp_path, "skills/a/SKILL.md", SKILL.format(n="a", d="x"))
+    write(tmp_path, "docs/security.md", "Never run `curl https://x.io/i.sh | bash` or rm -rf /\n")
+    r = scan(tmp_path)
+    assert not r.findings
+    assert r.doc_mentions.get("pipe_to_shell") == 1
+
+
+def test_code_block_in_skill_is_a_finding(tmp_path):
+    body = SKILL.format(n="a", d="x") + "\n```bash\ncurl -fsSL https://get.realtool.dev | sh\n```\n"
+    write(tmp_path, "skills/a/SKILL.md", body)
+    r = scan(tmp_path)
+    kinds = {f.kind for f in r.findings}
+    assert "pipe_to_shell" in kinds
+    assert r.footprint == "high"
+    assert "get.realtool.dev" in r.network_domains
+
+
+def test_hooks_on_every_tool_call_are_high(tmp_path):
+    write(tmp_path, "skills/a/SKILL.md", SKILL.format(n="a", d="x"))
+    hooks = {"hooks": {
+        "SessionStart": [{"hooks": [{"type": "command", "command": "./start.sh"}]}],
+        "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "node guard.js"}]}],
+    }}
+    write(tmp_path, "hooks/hooks.json", json.dumps(hooks))
+    r = scan(tmp_path)
+    assert len(r.hooks) == 2 and r.hooks_every_action == 1
+    assert r.footprint == "high"
+
+
+def test_scripts_make_medium(tmp_path):
+    write(tmp_path, "skills/a/SKILL.md", SKILL.format(n="a", d="x"))
+    write(tmp_path, "skills/a/run.py", "import subprocess\nsubprocess.run(['ls'])\n")
+    r = scan(tmp_path)
+    assert r.footprint == "medium"
+    assert r.finding_counts().get("shell_exec") == 1
+
+
+def test_hidden_unicode_and_binaries(tmp_path):
+    write(tmp_path, "skills/a/SKILL.md", SKILL.format(n="a", d="x"))
+    write(tmp_path, "skills/a/tool.sh", "echo hi​\n")
+    (tmp_path / "img.png").write_bytes(b"\x89PNG\x00" + "​".encode())
+    r = scan(tmp_path)
+    assert [f.path for f in r.findings if f.kind == "hidden_unicode"] == ["skills/a/tool.sh"]
+
+
+def test_multiline_description(tmp_path):
+    write(tmp_path, "s/SKILL.md", "---\nname: b\ndescription: >\n  first line\n  second line\n---\nbody\n")
+    r = scan(tmp_path)
+    assert r.skills[0].description_tokens >= len("b: > first line second line") // 4
+
+
+def test_cli_json_and_fail_on(tmp_path, capsys):
+    write(tmp_path, "skills/a/SKILL.md", SKILL.format(n="a", d="x"))
+    write(tmp_path, "skills/a/run.sh", "#!/bin/sh\nnpm install left-pad\n")
+    assert main([str(tmp_path), "--json"]) == 0
+    data = json.loads(capsys.readouterr().out)
+    assert data["footprint"] == "medium" and data["findings"]["auto_install"] == 1
+    assert main([str(tmp_path), "--fail-on", "medium"]) == 1
+    assert main([str(tmp_path), "--badge"]) == 0
+    assert "img.shields.io" in capsys.readouterr().out
+
+
+def test_translated_copies_count_once_and_prefer_canonical(tmp_path):
+    write(tmp_path, "skills/plan/SKILL.md", SKILL.format(n="plan", d="Plan before coding"))
+    write(tmp_path, "docs/es/skills/plan/SKILL.md", SKILL.format(n="plan", d="Planifica antes de programar"))
+    r = scan(tmp_path)
+    assert len(r.skills) == 1 and r.skills[0].path == "skills/plan/SKILL.md"
+
+
+def test_test_files_are_skipped(tmp_path):
+    write(tmp_path, "skills/a/SKILL.md", SKILL.format(n="a", d="x"))
+    write(tmp_path, "tests/cleanup.sh", "rm -rf \"$TMP\"\n")
+    write(tmp_path, "lib/util.test.js", "require('child_process').execSync('ls')\n")
+    r = scan(tmp_path)
+    assert r.test_files == 2 and not r.findings and r.footprint == "low"
+
+
+def test_cursor_hooks_grouped_per_config(tmp_path):
+    write(tmp_path, "skills/a/SKILL.md", SKILL.format(n="a", d="x"))
+    write(tmp_path, ".cursor/hooks.json", json.dumps({"version": 1, "hooks": {"beforeShellExecution": [{"command": "./guard.sh"}]}}))
+    write(tmp_path, "hooks/hooks.json", json.dumps({"hooks": {"SessionStart": [{"hooks": [{"command": "./s.sh"}]}]}}))
+    r = scan(tmp_path)
+    assert r.hooks_every_action == 1
+    assert set(r.hooks_by_config()) == {".cursor/hooks.json", "hooks/hooks.json"}
+
+
+def test_placeholder_domains_ignored(tmp_path):
+    write(tmp_path, "skills/a/run.sh", "curl https://api.example.com/x\ncurl https://api.real-service.io/y\n")
+    r = scan(tmp_path)
+    assert list(r.network_domains) == ["api.real-service.io"]