Skill Checker

Security checker for Claude Code skills — detect injection, malicious code, and supply chain risks before installation.

Features

• 57 security rules across 6 categories: structural validity, content quality, injection detection, code safety, supply chain, and resource abuse
• Scoring system: Grade A–F with 0–100 score
• Dual entry: CLI tool + PreToolUse hook for automatic interception
• Configurable policies: strict / balanced / permissive approval strategies
• Context-aware detection: severity reduction in code blocks and documentation sections, with zero reduction for injection rules
• IOC threat intelligence: built-in seed data for known malicious hashes, C2 IPs, and typosquat names
• Multiple output formats: terminal (color), JSON, hook response

Security Standard & Benchmark

Skill Checker's 57 rules are aligned with established security frameworks including OWASP Top 10 for LLM Applications (2025), MITRE CWE, and MITRE ATT&CK. The tool ships with a reproducible benchmark dataset of nine fixture skills covering all rule categories. This alignment is an internal mapping exercise — Skill Checker does not claim third-party certification or external audit status.

See docs/SECURITY_BENCHMARK.md for the full rule mapping matrix, benchmark methodology, scoring model, and known limitations.

Quick Start

# Install globally
npm install -g skill-checker

# Scan a skill directory
skill-checker scan ./path/to/skill/

# Or run without installing
npx skill-checker scan ./path/to/skill/

Usage

skill-checker scan <path> [options]

Option	Description
-f, --format <format>	Output format: terminal (default), json, hook
-p, --policy <policy>	Approval policy: strict, balanced (default), permissive
-c, --config <path>	Path to config file
--no-ignore	Disable inline suppression comments

# Colored terminal report
skill-checker scan ./my-skill

# JSON output for CI/programmatic use
skill-checker scan ./my-skill --format json

# Hook response format (for PreToolUse integration)
skill-checker scan ./my-skill --format hook

# Strict policy — deny on HIGH and above
skill-checker scan ./my-skill --policy strict

Exit code 0 = no critical issues, 1 = critical issues detected.

Recommended Scan Path

Skill Checker is designed to scan individual skill directories containing a SKILL.md file at the root. Running scan . from a project root or non-skill directory will produce noisy results (e.g. STRUCT-001 for missing SKILL.md).

# Correct: point to a skill directory
skill-checker scan ./path/to/my-skill/

# Avoid: scanning project root or arbitrary directories
skill-checker scan .

Hook Integration

Skill Checker can run automatically as a Claude Code PreToolUse hook, intercepting skill file writes before they happen.

Setup

npx tsx hook/install.ts

This adds a hook entry to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hook": "/path/to/skill-gate.sh"
      }
    ]
  }
}

How It Works

1. Claude Code intercepts Write/Edit operations targeting SKILL.md files
2. skill-gate.sh receives the file content via stdin (JSON)
3. Runs skill-checker scan --format hook on the content
4. Returns a permission decision: allow, ask, or deny

The hook is fail-closed — if the scanner is unavailable, JSON parsing fails, or any unexpected error occurs, it returns ask (never silently allows).

Requirements

• jq must be installed for JSON parsing
• skill-checker must be globally installed or available via npx

Scoring

Base score starts at 100. Each finding deducts points by severity:

Severity	Deduction
CRITICAL	-25
HIGH	-10
MEDIUM	-3
LOW	-1

Grade	Score	Meaning
A	90–100	Safe to install
B	75–89	Minor issues
C	60–74	Review advised
D	40–59	Significant risk
F	0–39	Not recommended

Configuration

Create .skillcheckerrc.yaml in your project root or home directory:

# Approval policy
policy: balanced    # strict / balanced / permissive

# Override severity for specific rules
overrides:
  CODE-006: LOW     # env var access is expected in my skills
  SUPPLY-002: LOW   # I trust npx -y in my workflow

# Ignore rules entirely
ignore:
  - CONT-006        # reference-heavy skills are fine

Config is resolved in order: CLI --config flag → project directory (walks up) → home directory → defaults.

Inline Suppression

Suppress specific findings directly in SKILL.md using comments:

<!-- skill-checker-ignore CODE-002 -->
Run `soffice --convert-to pdf` to convert documents.

<!-- skill-checker-ignore-file CONT-001 -->

subprocess.run("soffice") // skill-checker-ignore CODE-002

• <!-- skill-checker-ignore RULE --> suppresses the finding on the next line only
• <!-- skill-checker-ignore-file RULE --> suppresses the finding for the entire file
• // skill-checker-ignore RULE as a trailing comment suppresses the finding on the same line
• Multiple rules can be space-separated: <!-- skill-checker-ignore CODE-002 CONT-001 -->
• INJ rules cannot be suppressed — attempts produce a warning
• Directives only affect findings from the same source file (no cross-file suppression)
• Suppressed findings are excluded from scoring but remain visible in the report
• Use --no-ignore to disable all inline suppression

Policy Matrix

Severity	strict	balanced	permissive
CRITICAL	deny	deny	ask
HIGH	deny	ask	report
MEDIUM	ask	report	report
LOW	report	report	report

Rule Categories

Category	Rules	Examples
Structural (STRUCT)	8	Missing SKILL.md, invalid frontmatter, binary files
Content (CONT)	7	Placeholder text, lorem ipsum, promotional content
Injection (INJ)	10	Zero-width chars, prompt override, tag injection, social engineering, encoded payloads
Code Safety (CODE)	16	eval/exec, shell execution, reverse shell, data exfiltration, API key leakage, persistence mechanisms, rm -rf, obfuscation
Supply Chain (SUPPLY)	10	Unknown MCP servers, suspicious domains, malicious hashes, typosquat
Resource Abuse (RES)	6	Unrestricted tool access, disable safety checks, ignore project rules

See docs/SECURITY_BENCHMARK.md for the complete rule mapping with OWASP/CWE/ATT&CK references.

Programmatic API

import { scanSkillDirectory } from 'skill-checker';

const report = scanSkillDirectory('./my-skill', {
  policy: 'strict',
  overrides: { 'CODE-006': 'LOW' },
  ignore: ['CONT-001'],
});

console.log(report.grade, report.score, report.results.length);

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3) — see the LICENSE file for details.

Commercial License (商业授权)

If you want to integrate this tool into a closed-source commercial product or SaaS, or cannot comply with AGPLv3 due to company policy, contact Alexander.kinging@gmail.com for a commercial license.