skill-guardian

name

skill-guardian

description

Pre-installation security gate for agent skills. This skill should be used when the user or agent attempts to install any skill — including requests like "install X", "add X skill", "help me set up the X skill", "npx skills add", or when the agent autonomously decides to install a skill. Also triggers on skill cleanup and audit requests like "clean up my skills", "check installed skills", "any unused skills", "review my skills", or "audit my skill list". Do NOT use for MCP server installation, npm/pip package installation, or non-skill tooling.

Skill Guardian

Pre-installation security scan + necessity assessment gate. Cleanup auditor for installed skills.

Hard Rule

Before executing ANY npx skills add, complete ALL steps in the Installation Gate below.

• Never install without completing the full gate.
• Never install without explicit user confirmation.
• Never skip steps for efficiency.
• Never install silently in the background.

Installation Gate

Execute these 4 steps sequentially when intercepting any skill installation request.

Step 1: Security Scan

1. Parse the target skill: extract <owner>/<repo> and <skill-name>.

2. Clone to temp — do NOT install to the agent skill directory:

   git clone --depth 1 https://github.com/<owner>/<repo>.git /tmp/sg-scan-$$
   

3. Run security scanner. Try in order, use the first available:

   Option A — snyk-agent-scan (preferred; requires SNYK_TOKEN env var):

   uvx snyk-agent-scan@latest --skills /tmp/sg-scan-$$/<skill-name>/SKILL.md --json
   

   Option B — Legacy mcp-scan (no token needed, outdated):

   uvx mcp-scan@latest --skills /tmp/sg-scan-$$/<skill-name>/SKILL.md
   

   Option C — Neither available → skip to Step 1b.

4. Interpret scan results by issue code prefix:

   Code prefix	Severity	Action
   E (E001–E006)	Critical	Block. Report threat details. No override option.
   TF (TF001–TF002)	Critical	Block. Toxic multi-tool attack chain detected.
   W (W007–W013)	Warning	Warn user with specifics. Ask whether to proceed.
   None	Clean	Continue to Step 2.

5. Clean up temp: rm -rf /tmp/sg-scan-$$

Step 1b: skills.sh Audit Data (supplementary or fallback)

No public API exists. Fetch audit pages via web fetch and extract risk levels:

https://skills.sh/<owner>/<repo>/<skill-name>/security/snyk
https://skills.sh/<owner>/<repo>/<skill-name>/security/agent-trust-hub

Risk levels to look for: Safe, Low Risk, Med Risk, High Risk, Critical.

If unreachable → note "audit data unavailable", continue. Do not block on this.

Step 2: Necessity Assessment

Run npx skills list to get all installed skills. Evaluate three dimensions:

Duplicates — Compare the new skill's name and description against every installed skill. Flag if functional overlap exists.

❌ pdf already installed → installing nano-pdf adds nothing. ❌ web-search already installed → installing tavily-search duplicates it.

Environment overlap — Check if existing MCP tools or agent built-in capabilities already cover the same functionality.

❌ Exa Search MCP installed → web-search skill is redundant. ❌ Agent has built-in file read/write → file-util skill adds no value.

Quality signals — Fetch from the skill's page on skills.sh if available:

Signal	Red flag
Install count	< 100
Source repo stars	< 10
Last updated	> 6 months ago
Publisher	Not a verified org (anthropics/, vercel-labs/, microsoft/)

Step 3: Report and Confirm

Present a single consolidated report covering:

1. Security — scan result and specific findings
2. Duplicates — overlap with installed skills (if any)
3. Environment — overlap with existing MCP tools (if any)
4. Quality — signal summary
5. Recommendation — one of: Install / Install with caution / Skip recommended / Blocked

CRITICAL: Wait for explicit user confirmation before proceeding. Do not auto-install.

Step 4: Execute

• User confirms → npx skills add <owner>/<repo>/<skill-name> → verify with npx skills list.
• User declines → report "Installation cancelled." Clean up any remaining temp files.

---

Cleanup Mode

Trigger: user asks to clean up, audit, or review installed skills.

1. Run npx skills list to enumerate all installed skills.
2. Assess each skill:
   • Redundant with another installed skill?
   • Covered by an existing MCP tool or agent built-in?
   • Source repo still maintained? (check GitHub last push date)
   • New security issues? (re-check skills.sh audit pages)
3. Present numbered removal recommendations with reasons.
4. User selects items → run npx skills remove <skill> for each. Confirm each removal.

---

Fallback Behavior

Condition	Action
snyk-agent-scan unavailable, no SNYK_TOKEN	Try legacy mcp-scan. If also unavailable → skills.sh only.
skills.sh unreachable	Note "audit data unavailable". Continue with scanner results.
Scanner + skills.sh both unavailable	Warn user: no security data could be obtained. Recommend manual review. Still require user confirmation before install.