SkillGuard is a security scanner for AI agent "skills" defined in Markdown. It evaluates skill definitions for security risks, malicious intents, and supply chain vulnerabilities, providing transparency to developers and end-users.
AI Agents are only as safe as the skills they are given. As the ecosystem of AI agents grows, so does the risk of:
- Malicious skills - Skills designed to exfiltrate data or perform harmful actions
- Prompt injection - Skills that can be manipulated to ignore safety guidelines
- Supply chain attacks - Compromised skill repositories
- Excessive permissions - Skills requesting unnecessary system access
SkillGuard provides the first line of defense by analyzing skill definitions before they're loaded into an agent.
- YAML frontmatter parsing - Extracts skill metadata from Markdown files
- Multi-category security scoring - Weighted scoring with exponential decay
- Risk detection:
- Shell command execution patterns
- Credential and secret exposure
- Unrestricted tool access (wildcards)
- Prompt injection vectors
- Untrusted external URLs
- Obfuscated code (eval, Function, setTimeout)
- HTTP/Git dependencies
- Hidden characters (zero-width, RTL override, homoglyphs)
- Referenced script analysis (scans .py, .js, .ts, .sh files)
- Missing metadata (transparency gaps)
- CI/CD integration - Threshold-based exit codes for automated pipelines
- Multiple output formats - Colored CLI output and JSON reports
- Configurable - Custom thresholds, paths, and trusted domains
Download the latest release for your platform from the releases page.
brew install skillguard/skillguard/skillguard# GitHub Container Registry (Chainguard-based, distroless)
docker pull ghcr.io/ossafrica/skillguard:latest
# Or from Docker Hub
docker pull OSSAfrica/skillguard:latestgit clone https://github.com/OSSAfrica/skillguard.git
cd skillguard
go build -o skillguard .skillguard scanskillguard scan --path ./my-skillsskillguard scan --threshold 70
echo $? # 0 = pass, 1 = fail, 2 = errorskillguard scan --output report.jsonDisplay available commands and options:
Scan a skills directory (e.g., cloudflare skills):
Scan the AI SDK skills directory:
Scan multiple paths (comma-separated) and handle errors gracefully:
| Flag | Short | Description | Default |
|---|---|---|---|
--path |
-p |
Path to scan (file, directory, or comma-separated paths) | ~/.agents/skills |
--threshold |
-t |
Minimum score to pass (0-100) | 70 |
--output |
-o |
Output JSON report to file | (stdout) |
--quiet |
-q |
Minimal output - just pass/fail status | false |
| Code | Meaning |
|---|---|
0 |
Scan completed, all skills passed threshold |
1 |
Scan completed, one or more skills failed threshold |
2 |
Scan failed (file not found, parse error, etc.) |
SkillGuard reads configuration from ~/.skillguard.yaml. Create or modify this file to set defaults:
default_path: ~/.agents/skills
threshold: 70Or use the config command:
skillguard config set --path ~/my-skills --threshold 80
skillguard config showSkillGuard uses a multi-category scoring system with weighted averages. Skills start with 100 points in each category, with deductions based on severity and exponential decay for repeated findings.
| Category | Weight | Description |
|---|---|---|
| Security | 3.0 | Shell access, file access, credentials, obfuscated code |
| Supply Chain | 2.0 | External scripts, git/http dependencies, source verification |
| Transparency | 1.5 | Metadata completeness, prompt injection risks |
| Quality | 1.5 | Tool access patterns, allowed tools |
| Maintenance | 1.0 | Telemetry, protestware detection |
| Level | Base Deduction | Decay Factor |
|---|---|---|
| Critical | 40 | e^-10x |
| High | 20 | e^-x |
| Medium | 10 | e^-x/20 |
| Low | 5 | e^-x/40 |
| Category | Risk | Severity |
|---|---|---|
| Shell Execution | Command execution patterns | High/Critical |
| File Access | File write/delete operations | High |
| Network | Untrusted external URLs | Medium |
| Credentials | Secret/credential references | High |
| Obfuscated Code | eval, Function, setTimeout patterns | Critical |
| HTTP Dependencies | curl/wget with pipe to shell | Critical |
| Git Dependencies | Git clone/fetch operations | Medium |
| Hidden Characters | Zero-width, RTL, homoglyphs | High |
| Prompt Injection | Dynamic prompt construction | Medium |
| Supply Chain | No source URL provided | Low |
| Metadata | Missing description/triggers | Low |
A score of 70 or higher is considered passing by default.
Score: 77/100
Category Scores:
security: 62/100 (3 findings)
supply_chain: 55/100 (2 findings)
quality: 100/100
maintenance: 100/100
transparency: 95/100 (1 findings)
SkillGuard includes built-in trust for known safe domains:
- Code hosts:
github.com,gitlab.com,bitbucket.org - Package managers:
npmjs.com,pypi.org,crates.io - Cloud platforms:
vercel.app,vercel.sh,cloudflare.com,google.com - Documentation:
github.io,readthedocs.io,netlify.app
External URLs to domains not in this list are flagged as medium-risk.
docker run --rm -v ~/path/to/skills:/skills ghcr.io/ossafrica/skillguard scan --path /skillsCopy the appropriate example to your skill repository:
| Platform | Example Location |
|---|---|
| GitHub Actions | examples/github-actions/skill-scan.yml |
| GitLab CI | examples/gitlab-ci/.gitlab-ci.yml |
| Docker Compose | examples/docker/docker-compose.yml |
skillguard/
├── cmd/ # CLI commands (Cobra)
│ ├── root.go # Main entry point
│ ├── scan.go # Scan command
│ └── config.go # Config management
├── internal/
│ ├── model/ # Data structures
│ ├── parser/ # Markdown/YAML parsing
│ └── analyzer/ # Security scoring engine
├── examples/ # CI/CD integration examples
│ ├── github-actions/
│ ├── gitlab-ci/
│ └── docker/
├── Dockerfile # Container image definition
└── main.go # Application entry
Contributions are welcome. Please see CONTRIBUTING.md for guidelines on how to contribute to this project.
See DEVELOPMENT.md for instructions on setting up a development environment.
MIT License - see LICENSE for details.
Inspired by tools like Snyk, Socket.dev, and npm audit for bringing security transparency to software ecosystems.