secure-skills

A security-hardened fork of the skills CLI that scans agent skills for malicious content before installation.

The open agent skills ecosystem makes it trivial to install third-party instruction sets into coding agents — but that same ease of installation is a vector for prompt injection, data exfiltration, and credential theft. Snyk's analysis of 3,984 published skills found that 13.4% had critical security issues and 76 were confirmed malicious. Separately, Koi's ClawHavoc investigation uncovered 341 malicious ClawedBot skills using techniques like AMOS stealer droppers, password-protected archives, base64-encoded payloads, macOS quarantine bypasses (xattr -c), and reverse shells. skillsio adds an automated security gate so you can still move fast without running untrusted code.

What It Does

Every skillsio add command runs a local security scan before anything is installed. The scanner applies ~52 regex rules derived from the Snyk and ClawHavoc research, organized into 8 threat categories:

Findings are categorized by severity:

• Critical / High — always prompts for confirmation (critical prompts even with --yes)
• Medium and below — noted and auto-continued

URL Transparency

The scanner extracts all external URLs found in skill files and displays them before installation. Even if the local scan is clean, skills that reference external URLs will prompt you to review them before proceeding. This catches deceptive domain patterns that regex rules can't — letting you eyeball where a skill wants to send traffic.

◆  External URLs found in skill files (2):
│  https://example.com/setup
│  https://hooks.slack.com/services/T00/B00/xxx
│
◆  This skill references external URLs. Continue with installation?

With --yes, URL-only prompts are auto-continued. Skills with high/critical findings always show URLs alongside the findings summary.

Optional: VirusTotal Integration

When a VirusTotal API key is provided, the CLI also hashes each skill's content (SHA-256) and checks it against VT's database. If the file has been seen before, VT's verdict is displayed alongside local findings — including engine detection counts and Gemini-powered Code Insight analysis.

◆ VirusTotal: ✗ malicious (14/72 engines)
   Code Insight: Downloads and executes external binary...
   https://www.virustotal.com/gui/file/{hash}

◆ VirusTotal: ✓ clean (0/72 engines)

◆ VirusTotal: not found (local scan only)

A VT malicious verdict escalates the scan to critical severity regardless of local findings.

VT is purely additive — no key means no VT calls, and VT errors (rate limits, network issues) are handled gracefully without blocking installation.

# Via CLI flag
npx skillsio add owner/repo --vt-key YOUR_API_KEY

# Via environment variable
VT_API_KEY=YOUR_API_KEY npx skillsio add owner/repo

--vt-key flag takes precedence over VT_API_KEY env var.

Quick Start

# Install a skill (scanned automatically)
npx skillsio add vercel-labs/agent-skills

# Skip the scan if you trust the source
npx skillsio add vercel-labs/agent-skills --skip-scan

# Scan with VirusTotal threat intelligence
VT_API_KEY=xxx npx skillsio add owner/repo

CLI Reference

add <source>

Install skills from GitHub, GitLab, git URLs, direct URLs, or local paths.

npx skillsio add vercel-labs/agent-skills           # GitHub shorthand
npx skillsio add https://github.com/org/repo        # Full URL
npx skillsio add git@github.com:org/repo.git        # Git URL
npx skillsio add ./my-local-skills                   # Local path

Other Commands

Installation Scope

Supported Agents

Supports OpenCode, Claude Code, Codex, Cursor, and 35 more.

The CLI automatically detects which coding agents you have installed.

Environment Variables

Development

pnpm install          # Install dependencies
pnpm build            # Build
pnpm dev <cmd>        # Run CLI in dev mode (e.g., pnpm dev add owner/repo)
pnpm test             # Run all tests
pnpm type-check       # TypeScript type checking
pnpm format           # Format code with Prettier

Scanner Architecture

• src/scanner.ts — Rules engine. Defines ~52 regex rules across 8 threat categories, runs them against all skill files (.md, .txt, .yaml, .json, .sh, .py, .js, .ts, .ps1, .bat, .cmd).
• src/scanner-ui.ts — Presentation layer. Displays findings by severity, runs optional VT lookups, handles escalation logic and user confirmation prompts.
• src/vt.ts — VirusTotal API client. SHA-256 hashing, GET /api/v3/files/{hash} lookup, verdict mapping, graceful error handling.
• src/add.ts — Integration point. The scanner is wired into all 4 install paths (GitHub/git repos, remote providers, well-known endpoints, legacy Mintlify).

Acknowledgments

This project is a fork of skills by Vercel Labs. All upstream CLI functionality — skill discovery, installation, agent support, update checking — comes from the original project. The security scanning layer, VirusTotal integration, and related tests are additions by this fork.

License

MIT