Agent Skills: Skill Security Scanner

Skill Security Scanner

Scan agent skills for security issues before adoption. Detects prompt injection, malicious code, excessive permissions, secret exposure, and supply chain risks.

Requires: The uv CLI for python package management, install guide at https://docs.astral.sh/uv/getting-started/installation/

Important: Run all scripts from the repository root. Script paths like scripts/scan_skill.py are relative to this skill's root directory (the directory containing this SKILL.md), not relative to the target repository.

Bundled Script

scripts/scan_skill.py

Static analysis scanner that detects deterministic patterns. Outputs structured JSON.

uv run scripts/scan_skill.py <skill-directory>

Returns JSON with findings, URLs, structure info, and severity counts. The script catches patterns mechanically — your job is to evaluate intent and filter false positives.

Workflow

Phase 1: Input & Discovery

Determine the scan target:

• If the user provides a skill directory path, use it directly
• If the user names a skill, look for it under .agents/skills/<name>/ first, then other established layouts such as skills/<name>/ when the repo uses a canonical root skill tree, .claude/skills/<name>/, plugins/*/skills/<name>/, or another repo-managed skill root with clear prior art
• If the user says "scan all skills", discover all */SKILL.md files and scan each

Validate the target contains a SKILL.md file. List the skill structure:

ls -la <skill-directory>/
ls <skill-directory>/references/ 2>/dev/null
ls <skill-directory>/scripts/ 2>/dev/null

Phase 2: Automated Static Scan

Run the bundled scanner:

uv run scripts/scan_skill.py <skill-directory>

Parse the JSON output. The script produces findings with severity levels, URL analysis, and structure information. Use these as leads for deeper analysis.

Fallback: If the script fails, proceed with manual analysis using Grep patterns from the reference files.

Phase 3: Frontmatter Validation

Read the SKILL.md and check:

• Required fields: name and description must be present
• Name consistency: name field should match the directory name
• Tool assessment: Review allowed-tools — is Bash justified? Are tools unrestricted (*)?
• Model override: Is a specific model forced? Why?
• Description quality: Does the description accurately represent what the skill does?

Phase 4: Prompt Injection Analysis

Load references/prompt-injection-patterns.md for context.

Review scanner findings in the "Prompt Injection" category. For each finding:

1. Read the surrounding context in the file
2. Determine if the pattern is performing injection (malicious) or discussing/detecting injection (legitimate)
3. Skills about security, testing, or education commonly reference injection patterns — this is expected

Critical distinction: A security review skill that lists injection patterns in its references is documenting threats, not attacking. Only flag patterns that would execute against the agent running the skill.

Phase 5: Behavioral Analysis

This phase is agent-only — no pattern matching. Read the full SKILL.md instructions and evaluate:

Description vs. instructions alignment:

• Does the description match what the instructions actually tell the agent to do?
• A skill described as "code formatter" that instructs the agent to read ~/.ssh is misaligned

Config/memory poisoning:

• Instructions to modify CLAUDE.md, MEMORY.md, settings.json, .mcp.json, or hook configurations
• Instructions to add itself to allowlists or auto-approve permissions
• Writing to ~/.claude/, ~/.agents/, or any agent configuration directory
• Scripts that append to global config files — the poisoned instructions persist after skill removal

Scope creep:

• Instructions that exceed the skill's stated purpose
• Unnecessary data gathering (reading files unrelated to the skill's function)
• Instructions to install other skills, plugins, or dependencies not mentioned in the description

Information gathering:

• Reading environment variables beyond what's needed
• Listing directory contents outside the skill's scope
• Accessing git history, credentials, or user data unnecessarily

Structural attacks (check scanner output for these):

• Symlinks: Files that resolve outside the skill directory — can disguise reads of ~/.ssh/id_rsa, ~/.aws/credentials, etc. as "example" files
• Frontmatter hooks: PostToolUse/PreToolUse hooks in YAML — execute shell commands automatically, the model cannot prevent it
• !command`` syntax: Runs shell commands at skill load time during template expansion, before the model sees the prompt
• Test files: conftest.py, test_*.py, *.test.js — test runners auto-discover and execute these as side effects of pytest or npm test
• npm lifecycle hooks: postinstall scripts in bundled package.json — run automatically on npm install
• Image metadata: PNG files with text in metadata chunks (tEXt/iTXt) — multimodal LLMs can read hidden instructions from image metadata

Phase 6: Script Analysis

If the skill has a scripts/ directory:

1. Load references/dangerous-code-patterns.md for context
2. Read each script file fully (do not skip any)
3. Check scanner findings in the "Malicious Code" category
4. For each finding, evaluate:
   • Data exfiltration: Does the script send data to external URLs? What data?
   • Reverse shells: Socket connections with redirected I/O
   • Credential theft: Reading SSH keys, .env files, tokens from environment
   • Dangerous execution: eval/exec with dynamic input, shell=True with interpolation
   • Config modification: Writing to agent settings, shell configs, git hooks
5. Check PEP 723 dependencies — are they legitimate, well-known packages?
6. Verify the script's behavior matches the SKILL.md description of what it does

Legitimate patterns: gh CLI calls, git commands, reading project files, JSON output to stdout are normal for skill scripts.

Phase 7: Supply Chain Assessment

Review URLs from the scanner output and any additional URLs found in scripts:

• Trusted domains: GitHub, PyPI, official docs — normal
• Untrusted domains: Unknown domains, personal sites, URL shorteners — flag for review
• Remote instruction loading: Any URL that fetches content to be executed or interpreted as instructions is high risk
• Dependency downloads: Scripts that download and execute binaries or code at runtime
• Unverifiable sources: References to packages or tools not on standard registries

Phase 8: Permission Analysis

Load references/permission-analysis.md for the tool risk matrix.

Evaluate:

• Least privilege: Are all granted tools actually used in the skill instructions?
• Tool justification: Does the skill body reference operations that require each tool?
• Risk level: Rate the overall permission profile using the tier system from the reference

Example assessments:

• Read Grep Glob — Low risk, read-only analysis skill
• Read Grep Glob Bash — Medium risk, needs Bash justification (e.g., running bundled scripts)
• Read Grep Glob Bash Write Edit WebFetch Task — High risk, near-full access

Confidence Levels

| Level | Criteria | Action | |-------|----------|--------| | HIGH | Pattern confirmed + malicious intent evident | Report with severity | | MEDIUM | Suspicious pattern, intent unclear | Note as "Needs verification" | | LOW | Theoretical, best practice only | Do not report |

False positive awareness is critical. The biggest risk is flagging legitimate security skills as malicious because they reference attack patterns. Always evaluate intent before reporting.

Output Format

## Skill Security Scan: [Skill Name]

### Summary
- **Findings**: X (Y Critical, Z High, ...)
- **Risk Level**: Critical / High / Medium / Low / Clean
- **Skill Structure**: SKILL.md only / +references / +scripts / full

### Findings

#### [SKILL-SEC-001] [Finding Type] (Severity)
- **Location**: `SKILL.md:42` or `scripts/tool.py:15`
- **Confidence**: High
- **Category**: Prompt Injection / Malicious Code / Excessive Permissions / Secret Exposure / Supply Chain / Validation
- **Issue**: [What was found]
- **Evidence**: [code snippet]
- **Risk**: [What could happen]
- **Remediation**: [How to fix]

### Needs Verification
[Medium-confidence items needing human review]

### Assessment
[Safe to install / Install with caution / Do not install]
[Brief justification for the assessment]

Risk level determination:

• Critical: Any high-confidence critical finding (prompt injection, credential theft, data exfiltration)
• High: High-confidence high-severity findings or multiple medium findings
• Medium: Medium-confidence findings or minor permission concerns
• Low: Only best-practice suggestions
• Clean: No findings after thorough analysis

Reference Files

| File | Purpose | |------|---------| | references/prompt-injection-patterns.md | Injection patterns, jailbreaks, obfuscation techniques, false positive guide | | references/dangerous-code-patterns.md | Script security patterns: exfiltration, shells, credential theft, eval/exec | | references/permission-analysis.md | Tool risk tiers, least privilege methodology, common skill permission profiles |