Agent Skills Validator and Security Scanner Tool - Check SKILL.md Frontmatter Compliance and Flag Risky Patterns
First Published:
Last Updated:
Paste or drop a SKILL.md (an Agent Skill / Claude Code skill file) to (1) check its YAML frontmatter against the current specification and (2) statically flag risky patterns - dangerous commands, hardcoded secrets, invisible characters, render-time and lifecycle shell hooks, and prompt-injection signals. All processing is performed entirely in your browser - your data never leaves your device.
⚠️ IMPORTANT DISCLAIMER:
- This tool is provided "AS IS" without any warranties of any kind.
- This tool performs static checks only. A clean result does not guarantee that a skill is safe - runtime behavior, bundled binaries, and future updates are out of scope.
- Every finding is a flag for manual review, not a verdict of safe or malicious. The tool never executes a skill and never fetches any URL.
- Always review skills from untrusted sources manually before installing.
- By using this tool, you accept full responsibility for any outcomes.
This tool uses client-side JavaScript for all processing. No data is transmitted to servers, no files are uploaded online, all processing happens locally in your browser. Once loaded, this tool continues to work even without an internet connection. For more details, please refer to our Web Tools Disclaimer.
SKILL.md Input
Frontmatter Validation
Checks the YAML frontmatter against the Agent Skills standard / Claude API requirements and the Claude Code field set. Results are line-numbered Error / Warning / Info, each labeled spec (from the official documentation) or recommendation (this tool's suggestion).
About This Tool
An Agent Skill (also called a Claude Code skill) is a folder whose entry point is a SKILL.md file: YAML frontmatter (metadata such as name and description) followed by Markdown instructions Claude loads on demand. Because a skill can grant tool access, attach hooks, and bundle scripts, a third-party skill is, in effect, code you are installing. This tool helps you review one before you trust it, entirely in your browser:
- Validator: checks the frontmatter against the current specification and reports line-numbered Error / Warning / Info results, labeling each as derived from the spec or as this tool's recommendation.
- Security Scan: statically flags risky patterns - over-broad tool permissions, render-time and lifecycle shell hooks, dangerous command shapes, hardcoded secrets, network egress, invisible / bidirectional characters, and prompt-injection signals - across the SKILL.md and its supporting files.
Frontmatter rules and detection patterns were validated against the official documentation as of 2026-06-14. The specification evolves quickly; re-check the sources below for the current field set.
Frontmatter Spec and Detection Sources
- Agent Skills overview (Anthropic / Claude API), including
nameanddescriptionconstraints: platform.claude.com/docs/en/agents-and-tools/agent-skills/overview - Claude Code skills, including the full SKILL.md frontmatter field reference and render-time shell injection syntax: code.claude.com/docs/en/skills
Validation Rules
The required fields (name, description) and their constraints come from the Agent Skills standard / Claude API. All other frontmatter keys are the recognized Claude Code field set; a key outside that set is reported as Info (possible typo). "Origin" distinguishes a documented requirement (spec) from this tool's suggestion (recommendation).
| ID | Level | Origin | What it checks |
|---|---|---|---|
E1 | Error | spec | No YAML frontmatter block (file does not start with ---) |
E2 | Error | spec | Frontmatter opening --- is not terminated |
E3 | Error | spec | description missing or empty (required, non-empty) |
E4 | Error | spec | name exceeds 64 characters |
E5 | Error | spec | name contains characters other than a-z 0-9 - |
E6 | Error | spec | name contains < or > (XML tags forbidden) |
E7 | Error | spec | name contains a reserved word (anthropic / claude) |
E8 | Error | spec | description contains XML tags |
W1 | Warning | spec | description exceeds the 1024-character Claude API limit |
W2 | Warning | recommendation | name is not strict kebab-case |
W3 | Warning | spec | Field value outside its documented set (context, shell, effort, booleans, agent without context: fork) |
W4 | Warning | spec | name omitted (required for API / claude.ai; Claude Code uses the directory name) |
W5 | Warning | spec | Duplicate frontmatter key |
I1 | Info | spec | description + when_to_use exceeds the 1,536-char default (configurable via maxSkillDescriptionChars; Claude Code truncates the listing) |
I2 | Info | recommendation | Unknown frontmatter key (not a recognized field) |
I3 | Info | recommendation | Empty body, or body over 500 lines (Claude Code guidance) |
I4 | Info | recommendation | description does not state when to use the skill |
Detection Categories
Every detection below produces a flag for manual review, never a verdict. Severity reflects how dangerous the pattern is if malicious, not a probability that it is. Categories follow the taxonomy in the companion Agent Skills Security Vetting Guide.
| ID | Severity | Category | What it flags |
|---|---|---|---|
S1 | High / Medium | Over-broad tool permissions | Bare Bash, Tool(*), or wildcard in allowed-tools (which grants, not restricts), or an unusually large grant |
S2 | High | Render-time shell / lifecycle hooks | Inline !`cmd` and fenced ```! blocks run before Claude sees the content; a hooks: block runs shell at the skill's lifecycle events |
S3 | High / Medium | Dangerous command shapes | Pipe-to-interpreter, rm -rf, chmod 777, eval, schedulers/persistence, and credential-file paths |
S4 | High / Medium | Hardcoded secrets | Token formats (AWS, GitHub, Slack, Google, Stripe), private-key blocks, and generic credential assignments (value masked) |
S5 | Medium / Low | Network egress / external content | Network commands and external URLs - fetched content can carry instructions (this tool does not fetch them) |
S6 | High / Medium | Obfuscation / invisible characters | Zero-width and bidirectional control characters, Unicode tag characters, and long base64 / hex / escape blobs |
S7 | Low | Instruction-embedded direction | Phrases resembling prompt-injection (lowest-confidence heuristic - natural-language intent is what static tools cannot judge) |
S8 | Low | Trigger hijacking / interference | Over-broad paths globs or activation scope that can hijack triggers from other skills |
How to Use
- Paste or drop a SKILL.md into the input area (or click an Example).
- Validator tab: click "Validate" (or press Ctrl+Enter / Cmd+Enter) to see line-numbered frontmatter Errors, Warnings, and Info notes, each labeled spec or recommendation.
- Security Scan tab: optionally "Add Supporting File" to include bundled scripts and references, then click "Scan" to see High / Medium / Low flags for manual review.
- Copy Report on either tab to take the results into a pull-request comment or review checklist.
Features:
- ✅ Frontmatter Validation: Line-numbered Error / Warning / Info against the Agent Skills standard, Claude API, and Claude Code field set
- 🏷️ Spec vs. Recommendation: Every finding is labeled as a documented requirement or this tool's suggestion - no invented rules
- 🛡️ Eight Detection Categories: Tool permissions, render-time and lifecycle hooks, dangerous commands, secrets, network egress, invisible characters, injection signals, and trigger hijacking
- 📂 Multi-file Scan: Add the skill's bundled scripts and reference files to scan them alongside the SKILL.md
- 🔍 Honest Severity: Flags are for manual review, never a verdict; secret values are masked in the output
- 🔒 Privacy First: All processing happens locally in your browser - no data sent to servers, the skill is never executed, no URL is ever fetched
- ⌨️ Keyboard Shortcut: Ctrl+Enter (Cmd+Enter) runs the active tab
FAQ
What is SKILL.md?
SKILL.md is the entry-point file of an Agent Skill: YAML frontmatter (between --- markers) that tells Claude the skill's name and description (and optional behavior such as allowed-tools), followed by Markdown instructions that load only when the skill is used. The same file format powers custom skills in Claude Code, the Claude API, and claude.ai.
Does a clean scan mean the skill is safe?
No. A clean scan means none of this tool's static patterns matched - it is a fast, repeatable baseline, not a safety certificate. Use it the way you use a dependency-vulnerability scanner: as one input to a manual review, not a gate you wave skills through because the light was green.
Can this tool execute or sandbox the skill?
No. The tool performs static text analysis only. It never runs the skill, never installs it, and never fetches any URL it finds. Runtime behavior, bundled binaries, and what a fetched response actually returns are all out of scope.
What does this tool NOT do?
It does not judge intent in natural language, predict runtime behavior, decompile or de-obfuscate beyond flagging that obfuscation is present, verify that URLs or files exist, or claim a skill is "safe" or "malicious". It flags patterns a human should look at.
Which specification is the validator checked against?
The required name and description constraints follow the Agent Skills standard / Claude API; the remaining frontmatter keys follow the Claude Code field reference. Both were confirmed against the official documentation as of 2026-06-14 (see Sources above). Because the specification changes quickly, re-check those pages for the current field set.
Important Notes
- This tool performs static checks only. A clean result does not guarantee that a skill is safe - runtime behavior, bundled binaries, and future updates are out of scope. Always review skills from untrusted sources manually before installing.
- A static scanner fundamentally cannot do three things, so never mistake a clean scan for safety:
- Judge intent in natural language - an instruction-embedded payload can be grammatically ordinary; "does this instruction serve the skill's purpose?" is a human question.
- Predict runtime behavior - what a script does depends on the environment, the response it fetches, and conditions the static text does not reveal.
- See the future - a skill that passes today can be changed tomorrow, which is why pinning versions and re-reviewing matters.
- Every finding is a flag for manual review, not a verdict. Heuristic categories (especially instruction-embedded direction) can both miss real issues and flag benign text.
- Specifications change quickly. The validator reflects the documentation confirmed on 2026-06-14; verify the current field set against the official sources listed above before relying on a result.
Related Tools
- llms.txt Generator and Validator Tool - generate and validate llms.txt / llms-full.txt with line-numbered spec checks
- JSON Schema Generator and Validator Tool - generate JSON Schema from samples and validate JSON against a schema
- Diff Text Compare Tool - compare two versions of a SKILL.md or script side by side
- Hash Generator Tool - compute SHA-256 and other hashes to pin a reviewed skill file
Related Articles
- Claude Code Agent Skills Complete Guide - how SKILL.md, frontmatter, and progressive disclosure work
- Agent Skills Security Vetting Guide - the malicious-pattern taxonomy and the static vetting checklist this tool implements
References:
Tech Blog with curated related content
Web Tools Collection