secure-skills

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

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

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 ~81 regex rules and a correlation engine 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.

Third-Party Audits via skills.sh

For GitHub-sourced skills, the CLI automatically checks skills.sh — Vercel's official skill directory — which runs independent third-party security audits from three auditors: Snyk, Socket, and Gen Agent Trust Hub. Results appear alongside local scan output:

  ◆ skills.sh: 3 audits  [Snyk ✗]  [Socket ✓]  [Trust Hub ✗]
    https://skills.sh/inference-sh-3/skills/agent-tools

• Green ✓ = auditor passed, Red ✗ = auditor failed, Dim ~ = no result yet
• If any auditor returns a Fail verdict, severity is escalated to at least High, triggering a confirmation prompt
• skills.sh lookup runs in parallel with VT and never blocks installation on error (graceful fallback)
• Only fires for GitHub-sourced skills that are listed on skills.sh — silent for everything else

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.

External Rules

You can extend the built-in scanner with your own rules using the --rules flag. This is useful for enforcing organization-specific policies — for example, blocking references to internal infrastructure or flagging deprecated tools.

Rules are defined in JSON files with a simple format:

{
  "rules": [
    {
      "id": "no-internal-api",
      "severity": "critical",
      "description": "References internal API — may leak infrastructure details",
      "pattern": "https?://internal\\.company\\.com",
      "flags": "i"
    },
    {
      "id": "no-sudo",
      "severity": "high",
      "description": "Skill should not require sudo access",
      "pattern": "\\bsudo\\s+"
    }
  ]
}

Each rule requires id, severity (critical/high/medium/low/info), description, and pattern (a regex string). The optional flags field defaults to "i" (case-insensitive).

# Load rules from a single file
npx skillsio add owner/repo --rules ./my-rules.json

# Load all .json rule files from a directory
npx skillsio add owner/repo --rules ./rules/

External rules are applied in addition to the built-in ~81 rules — they never replace them. Findings from external rules follow the same severity-based prompt flow as built-in findings.

See docs/EXTERNAL-RULES.md for the full format reference, more examples, and tips for writing rules.

Deep Taint Analysis (--deep-scan)

Regex rules detect individual dangerous patterns, but sophisticated attacks hide data flows across variables and functions. The --deep-scan flag enables a lightweight taint analysis engine that tracks how data moves from sources (environment variables, credential files) through variable assignments to sinks (network calls, exec, file writes).

npx skillsio add owner/repo --deep-scan

What it catches that regex cannot:

# Variable-mediated exfiltration — regex sees the pieces but can't link them
key = os.environ["SECRET"]        # source: env-access
encoded = b64encode(key)          # taint propagates through assignment
payload = json.dumps(encoded)     # ...and another hop
requests.post(url, data=payload)  # sink: network  →  deep-env-access-to-network (critical)

# getattr trick — regex misses the source entirely
env = getattr(os, 'environ')     # source: getattr-trick (evades os.environ regex)
data = str(env)
requests.post(url, data=data)    # → deep-getattr-trick-to-network (high)

# Cross-file attack — collector.py harvests, exfil.py sends
# collector.py                    # exfil.py
import os                         # from .collector import data
secrets = os.environ.copy()       # requests.post(url, data=payload)
                                  # → deep-cross-env-access-to-network (critical)

The analysis covers Python (.py) and JavaScript/TypeScript (.js, .ts) files. It adds zero dependencies — the tokenizer is regex-based, not AST-based, keeping the bundle small. See docs/deep-scan.md for architecture details.

Deep scan findings appear alongside regex findings in the same severity-based prompt. All cross-file flows are automatically classified as critical.

Quick Start

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

# Enable deep taint analysis for Python/JS/TS files
npx skillsio add owner/repo --deep-scan

# 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

# Scan with custom organization rules
npx skillsio add owner/repo --rules ./company-rules.json

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.

[!NOTE] Kiro CLI users: After installing skills, manually add them to your custom agent's resources in .kiro/agents/<agent>.json:

{
  "resources": ["skill://.kiro/skills/**/SKILL.md"]
}

The CLI automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select which agents to install to.

Creating Skills

Skills are directories containing a SKILL.md file with YAML frontmatter:

---
name: my-skill
description: What this skill does and when to use it
---

# My Skill

Instructions for the agent to follow when this skill is activated.

## When to Use

Describe the scenarios where this skill should be used.

## Steps

1. First, do this
2. Then, do that

Required Fields

• name: Unique identifier (lowercase, hyphens allowed)
• description: Brief explanation of what the skill does

Optional Fields

• metadata.internal: Set to true to hide the skill from normal discovery. Internal skills are only visible and installable when INSTALL_INTERNAL_SKILLS=1 is set. Useful for work-in-progress skills or skills meant only for internal tooling.

---
name: my-internal-skill
description: An internal skill not shown by default
metadata:
  internal: true
---

Skill Discovery

The CLI searches for skills in these locations within a repository:

• Root directory (if it contains SKILL.md)
• skills/
• skills/.curated/
• skills/.experimental/
• skills/.system/
• .agents/skills/
• .agent/skills/
• .augment/skills/
• .claude/skills/
• ./skills/
• .cline/skills/
• .codebuddy/skills/
• .commandcode/skills/
• .continue/skills/
• .cortex/skills/
• .crush/skills/
• .factory/skills/
• .goose/skills/
• .junie/skills/
• .iflow/skills/
• .kilocode/skills/
• .kiro/skills/
• .kode/skills/
• .mcpjam/skills/
• .vibe/skills/
• .mux/skills/
• .openhands/skills/
• .pi/skills/
• .qoder/skills/
• .qwen/skills/
• .roo/skills/
• .trae/skills/
• .windsurf/skills/
• .zencoder/skills/
• .neovate/skills/
• .pochi/skills/
• .adal/skills/

Plugin Manifest Discovery

If .claude-plugin/marketplace.json or .claude-plugin/plugin.json exists, skills declared in those files are also discovered:

// .claude-plugin/marketplace.json
{
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [{
    "name": "my-plugin",
    "source": "my-plugin",
    "skills": ["./skills/review", "./skills/test"]
  }]
}

This enables compatibility with the Claude Code plugin marketplace ecosystem.

If no skills are found in standard locations, a recursive search is performed.

Compatibility

Skills are generally compatible across agents since they follow a shared Agent Skills specification. However, some features may be agent-specific:

Troubleshooting

"No skills found"

Ensure the repository contains valid SKILL.md files with both name and description in the frontmatter.

Skill not loading in agent

• Verify the skill was installed to the correct path
• Check the agent's documentation for skill loading requirements
• Ensure the SKILL.md frontmatter is valid YAML

Permission errors

Ensure you have write access to the target directory.

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 ~81 regex rules across 8 threat categories, a correlation engine for multi-signal detection, and optional deep taint analysis integration. Supports loading external rules from JSON files via --rules.
• src/scanner-ui.ts — Presentation layer. Displays findings by severity, runs VT and skills.sh lookups in parallel, 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/skills-sh.ts — skills.sh audit client. Fetches and HTML-parses third-party audit results (Snyk, Socket, Gen Agent Trust Hub) for GitHub-sourced skills with a 5-second timeout; always resolves gracefully.
• src/deep-scan/ — Deep taint analysis engine (enabled via --deep-scan). Regex-based tokenizers extract sources, sinks, and assignments from Python/JS/TS files; a forward taint tracker propagates data flow; a cross-file analyzer detects multi-file attack patterns via import graph analysis. See docs/deep-scan.md.
• src/add.ts — Integration point. The scanner is wired into all 4 install paths (GitHub/git repos, remote providers, well-known endpoints, legacy Mintlify).

Changelog

1.1.3

• Synced with upstream (vercel-labs/skills): universal agent support (.agents/skills/ as a single install target symlinked across agents), new agents (Cortex Code, and others), Kiro CLI note, Creating Skills docs, Compatibility table, Troubleshooting section, agent-list badge
• Replaced HTML scraping with structured API: third-party audit now uses the add-skill.vercel.sh/audit JSON endpoint instead of scraping skills.sh HTML — more reliable and richer data (risk levels + alert counts per auditor)
• Stronger blocking: critical and high risk from the API both always prompt for confirmation; --yes is ignored for both (previously high was bypassed by --yes and critical only prompted rather than blocked)
• Audit failure warning: if the skills.sh API is unreachable, a yellow warning is shown rather than silently skipping — local scan still runs regardless
• Removed duplicate audit display (previously showed both an inline scan note and a separate "Security Risk Assessments" panel for the same data)

1.1.2

• skills.sh audit integration: for GitHub-sourced skills, the CLI now fetches third-party audit results from skills.sh (Snyk, Socket, Gen Agent Trust Hub) and displays them alongside local scan output
• Critical or High risk from any auditor escalates the install gate — critical always prompts even with --yes, high blocks unless --yes is set; uses the structured skills.sh JSON API instead of HTML scraping
• Audit runs in parallel with VirusTotal and fails silently on any network or parse error

1.1.1

• Removed anonymous usage telemetry inherited from the original Vercel skills CLI
• The upstream tool sent events to https://add-skill.vercel.sh/t on every command (install, remove, find, check, update) — this has been completely stripped out
• Removed DISABLE_TELEMETRY and DO_NOT_TRACK environment variables (no longer needed)
• Added 12 more regex rules to the scanner

1.1.0

• Added --rules <path> flag to load external scan rules from JSON files or directories
• External rules are applied alongside built-in rules, supporting organization-specific policies
• See docs/EXTERNAL-RULES.md for format documentation and examples
• Deep taint analysis (--deep-scan): lightweight forward taint propagation for Python and JS/TS files
• Tracks data flow from sources (env vars, credential files, getattr tricks) through variable chains to sinks (network calls, exec, file writes)
• Cross-file analysis detects multi-file exfiltration patterns via import graph resolution
• Zero new dependencies — regex-based tokenizers keep the bundle small

1.0.1

• Critical security prompts now default to No — users must explicitly confirm to install skills flagged as malicious

1.0.0

• Initial release with ~52 regex security rules across 8 threat categories
• VirusTotal integration for optional secondary threat intelligence
• URL transparency: all external URLs in skill files are shown before installation
• Scanner rules informed by Snyk and ClawHavoc research

Links

• Agent Skills Specification
• Skills Directory
• Amp Skills Documentation
• Antigravity Skills Documentation
• Factory AI / Droid Skills Documentation
• Claude Code Skills Documentation
• OpenClaw Skills Documentation
• Cline Skills Documentation
• CodeBuddy Skills Documentation
• Codex Skills Documentation
• Command Code Skills Documentation
• Crush Skills Documentation
• Cursor Skills Documentation
• Gemini CLI Skills Documentation
• GitHub Copilot Agent Skills
• iFlow CLI Skills Documentation
• Kimi Code CLI Skills Documentation
• Kiro CLI Skills Documentation
• Kode Skills Documentation
• OpenCode Skills Documentation
• Qwen Code Skills Documentation
• OpenHands Skills Documentation
• Pi Skills Documentation
• Qoder Skills Documentation
• Replit Skills Documentation
• Roo Code Skills Documentation
• Trae Skills Documentation
• Vercel Agent Skills Repository

Research

The scanner rules are informed by the following research into malicious agent skills:

• Snyk (2025) — Analysis of 3,984 published agent skills, finding 76 confirmed malicious skills (13.4% of clawhub.ai had critical issues). Identified core attack taxonomy: data exfiltration, prompt injection, credential theft, and obfuscated payloads.
• Koi Security (2025) — ClawHavoc: 341 Malicious ClawedBot Skills. Documented AMOS stealer droppers, password-protected archives, base64 payloads, macOS quarantine bypasses, and reverse shells in the wild.
• arxiv 2602.06547v1 (2025) — Malicious Agent Skills at Scale. Large-scale analysis identifying attack taxonomies (E1-E3 exfiltration, P1-P4 prompt injection, SC1-SC3 supply chain, PE2-PE3 privilege escalation), MCP server abuse, agent hook interception, permission bypass flags, environment-gated sleeper patterns, invisible Unicode instruction smuggling, and the "industrial actor fingerprint" (credential access + remote execution, 97.6% sensitivity).

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