skill-guard
Pre-install security check for Agent Skills.
Scan a SKILL.md package before your agent loads it. Offline, deterministic, no code execution.
Part of aisona-lab trust tooling (prompt-guard, OrcaI, lazycoder).
Beta · LIMITATIONS · CHANGELOG
Who this is for
| You | Use it when |
|---|---|
| Teams / companies installing third-party skills | Gate CI or a pre-install script before skills touch prod agents |
| Skill authors | Catch secrets, curl|bash, and exfil patterns before you publish |
| Security / platform | Policy packs (default / strict), SARIF, exit codes 0/1/2 |
Not a runtime firewall. Not an MCP auditor. Static pre-install only.
Try it in 30 seconds
# install CLI (package name on PyPI ≠ CLI name)
uv tool install aisona-skill-guard
# if PyPI is empty yet:
# uv tool install "git+https://github.com/aisona-lab/skill-guard@v0.2.2"
git clone --depth 1 https://github.com/aisona-lab/skill-guard.git /tmp/skill-guard
cd /tmp/skill-guard
skill-guard scan dataset/fixtures/benign/tdd-checklist
# → ALLOW exit 0
skill-guard scan dataset/fixtures/malicious/curl-pipe-shell
# → BLOCK exit 2 (SG003: curl | bash)
skill-guard scan dataset/ood/safe/vercel/deploy-to-vercel
# → WARN (SG006: npm install -g in a fenced install step)
What it looks like
Malicious fixture (curl … | bash):
skill-guard verdict=BLOCK exit=2
[CRITICAL] SG003 Pipe remote content into a shell
evidence: curl | … | bash
Real public skill (Vercel deploy — legitimate but global install):
skill-guard verdict=WARN exit=1
[MEDIUM] SG006 Global package install from skill
at: SKILL.md:141
evidence: npm install -g
Clean skill (ponytail / in-repo benign):
skill-guard verdict=ALLOW exit=0
No findings.
Live results on real corpora (v0.2.2)
Policy: --fail-on block (WARN does not fail CI by default).
| Source | Skills scanned | ALLOW | WARN | BLOCK | What that means |
|---|---|---|---|---|---|
| ponytail | 5–6 | all | 0 | 0 | Docs-only npm -g tips stay quiet |
| Public skills vendored as ood | 73 | ~85% | ~15% | 0 | False BLOCK rate is the main credibility metric |
| addyosmani/agent-skills | 24 | 23 | 1 | 0 | CI ${{ secrets }} examples → WARN, not BLOCK |
| last30days-skill | 1 (116 files) | — | — | 1 | Large pack + unscoped Bash — real pre-install signal |
ECC skills/ + .agents/skills |
282 | 236 | 44 | 2 | Remaining BLOCKs: allowed-tools: Bash unscoped |
| ood-unsafe held-out attacks (in-repo) | 8 | 0 | 0 | 8 | Evasions we track (split keys, b64→shell, …) |
Reproduce gates:
uv run python eval/run_eval.py --suite all --check
uv run pytest -q
Rules (why they matter)
| ID | Why care | Typical hit |
|---|---|---|
| SG001 | Broken package → broken install | missing name / frontmatter |
| SG002 | Keys in skills land in git & agent context | sk-ant-…, "sk"+"-ant-"+… |
| SG003 | Skills tell agents to run shell | curl | bash, rm -rf / |
| SG004 | Creds + network = theft | cat ~/.ssh/id_rsa + upload |
| SG005 | Skill can reprogram the host agent | “Ignore previous instructions” |
| SG006 | Install expands trust boundary | npm install https://…, fenced npm i -g |
| SG007 | Removes human gates | allowed-tools: Bash, “bypass sandbox” |
| SG008 | Huge skills hide risk & burn tokens | multi-k line SKILL.md |
| SG009 | Fake authority | “official Anthropic skill” |
| SG010 | Cloud / CI privilege | IMDS, docker.sock, secret exfil |
Examples and nuance: docs/RULES.md.
Install & CI
pip install aisona-skill-guard # CLI: skill-guard
# package name on PyPI is aisona-skill-guard (skill-guard is unrelated)
| Exit | Meaning |
|---|---|
| 0 | ALLOW (WARN ok by default) |
| 1 | WARN (--pack strict or --fail-on warn) |
| 2 | BLOCK |
| 3 | usage error |
- uses: aisona-lab/skill-guard@v0.2.2
with:
path: ./skills/my-skill
fail-on: block
# .skill-guard.yml
pack: default # or strict
suppress: [SG008]
Status & maintenance
| Stage | Beta (v0.2.2), CI on every push |
| Scope freeze | No new detectors without a real-scan fixture — DETECTOR-FREEZE |
| Lab | Same org as prompt-guard / OrcaI / lazycoder (agent trust stack) |
| Honest limits | New project; stars ≠ quality. Judge the tables and CI, not vanity metrics. |
Issues and security notes: GitHub · LIMITATIONS · BENCHMARKS
License
MIT © aisona-lab
Metadata
Release files for aisona-skill-guard 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aisona_skill_guard-0.2.2.tar.gz | 37.7 kB | Without provenance | Details for aisona_skill_guard-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aisona_skill_guard-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for aisona_skill_guard-0.2.2-py3-none-any.whl |
Total release size: 87.0 kB
Release files / aisona_skill_guard-0.2.2.tar.gz
| Download URL | aisona_skill_guard-0.2.2.tar.gz |
|---|---|
| Size | 37.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a2a0bb5917860444e706bee8c165a48b1cf1a4c5546f382578af8041eb212750
|
|
BLAKE2b-256 checksum How to use checksums |
c0aa3063cb8d1abe81d0ee910550fc7f4e0334b1ca68b50a5d9c10ca498e3d1d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / aisona_skill_guard-0.2.2-py3-none-any.whl
| Download URL | aisona_skill_guard-0.2.2-py3-none-any.whl |
|---|---|
| Size | 49.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
90ac708bd13be4d69d1efbb8e5ad35490b5142dd8078b84ea8e95a09a8ce6643
|
|
BLAKE2b-256 checksum How to use checksums |
7238dfaaa1c13caf800b7c75e55b9a5fe6ada2d9f46cd3e4d7ba469b6f2fbf99
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for aisona-skill-guard 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.