SkillCheck (Free)
Check skills against Anthropic guidelines and the agentskills specification. This file contains Free tier validation rules.
Want deeper analysis? Upgrade to Pro for anti-slop detection, security scanning, token optimization, WCAG compliance, enterprise checks, and Eval Kit (auto-generated test prompts for your skills).
Prerequisites
- Any AI assistant with file Read capability (Claude Code, Cursor, Windsurf, Codex CLI)
- Works on any platform (Unix/macOS/Windows)
- No special tools required (Read-only)
How to Check a Skill
- Locate: Find target SKILL.md file(s)
- Read: Load the content
- Validate: Apply each rule section below
- Report: List issues found with severity and fixes
Free Tier Validation Rules
Apply these checks in order. Each subsection defines patterns to match and issues to flag.
1. Frontmatter Structure
Every SKILL.md must start with YAML frontmatter between --- markers.
Required Fields
| Field | Required | Rules |
|---|---|---|
name | Yes | Lowercase, hyphens only, 1-64 chars, no reserved words |
description | Yes | WHAT + WHEN pattern, 1-1024 chars |
Frontmatter Security
Check 1.9-xml-in-frontmatter (Critical): Frontmatter values must not contain XML angle brackets (< or >). Frontmatter appears in Claude's system prompt; angle brackets could enable prompt injection.
Detection: Scan all frontmatter string values (name, description, compatibility, etc.) for < or > characters.
Fix: Remove angle brackets from frontmatter. Use plain text descriptions. Markdown formatting and XML tags are fine in the SKILL.md body.
Optional Fields (Spec)
Fields defined in the agentskills.io specification:
| Field | Purpose |
|---|---|
license | License name or reference to bundled license file |
allowed-tools | Tools the skill can use (space-separated or YAML list) |
compatibility | Platform compatibility info (max 500 chars) |
metadata | Additional key-value pairs |
Claude Code Extensions
Recognized by Claude Code but not part of the agentskills.io spec. Other agents may ignore these fields.
| Field | Purpose |
|---|---|
category | Skill domain(s) for discovery and filtering |
model | Override model (full ID like claude-opus-4-6 or alias: opus, sonnet, haiku) |
effort | Reasoning effort level: low, medium, or high |
maxTurns | Maximum agent turns (positive integer; warns above 100) |
disallowedTools | Tools the skill must not use (space-separated or YAML list) |
context | Run context ("fork" for sub-agent) |
agent | Agent type when context: fork |
hooks | Lifecycle hooks (PreToolUse, PostToolUse, Stop) |
user-invocable | Show in slash menu (default: true) |
disable-model-invocation | Manual-only skill |
produces | Artifact types this skill outputs (comma-separated) |
consumes | Artifact types this skill reads from other skills (comma-separated) |
Community Extensions
Not part of any spec. Used by community tools and registries.
| Field | Purpose |
|---|---|
type | Skill type indicator |
author | Skill author |
date | Creation/update date |
argument-hint | Hints for skill arguments |
Category Validation
Note:
categoryis a Claude Code extension, not part of the agentskills.io spec. Do not flag a missing category field. Only validate format if present.
Format: String or array of strings, lowercase letters, numbers, and hyphens only.
Pattern: ^[a-z][a-z0-9-]*[a-z0-9]$ (same rules as skill name)
Common categories: development, productivity, data, automation, writing, design, security, devops, api, testing, documentation, legal, financial, marketing, ai-ml
Artifact Passing Validation
Note:
producesandconsumesare Claude Code extensions for inter-skill artifact passing. Do not flag missing fields. Only validate format if present.
Format: Comma-separated list of artifact type names. Each type must be lowercase with hyphens only.
Known artifact types: content-brief, knowledge-note, reading-log-entry, sift-article
Check 1.10-artifact-types (Warning): If produces or consumes contains a type not in the known list above, flag as a warning (not an error). New types are valid but should be registered in rules/artifact-passing.md.
Check 1.11-consumes-without-tools (Warning): If a skill declares consumes: but its allowed-tools does not include Read or Glob, flag as a warning. Consuming artifacts requires reading files.
Name Validation
Pattern: ^[a-z][a-z0-9-]*[a-z0-9]$
Naming suggestions: Avoid generic terms that don't describe what the skill does: helper, utils, tools, misc, stuff, things, manager, handler. Product-specific terms (claude, anthropic, mcp) are allowed but may limit portability across agents.
Description Validation
Must contain:
- WHAT: Action verb explaining what skill does
- WHEN: Trigger phrase for when to use it
- Key capabilities (recommended): Specific tasks or file types handled
Recommended structure: [What it does] + [When to use it] + [Key capabilities]
Action verbs: Create, Generate, Build, Convert, Extract, Analyze, Transform, Process, Validate, Format, Export, Import, Parse, Search, Find
WHEN triggers: "Use when", "Use for", "Use this when", "Invoke when", "Activate when", "Triggers on", "Auto-activates", "Run when", "Applies to", "Helps with"
<example type="valid"> description: Generate weekly reports from Azure DevOps data. Use when user says "weekly update" or asks for stakeholder summaries. </example> <example type="valid"> description: Helps with code review workflows for Pull Requests. </example> <example type="invalid"> description: A tool for reports. reason: no WHAT verb, no WHEN trigger </example>allowed-tools Validation
Both space-separated and YAML list formats are valid:
<example type="valid"> allowed-tools: Read Glob Bash </example> <example type="valid"> allowed-tools: - Read - Glob - Bash </example> <example type="invalid"> allowed-tools: Read, Glob, Bash reason: comma separation is deprecated; use spaces or YAML list </example>Directory Structure Validation
Skills can include optional subdirectories per the agentskills spec:
| Directory | Purpose | Validation |
|---|---|---|
references/ | Additional docs (REFERENCE.md, etc.) | Files should be .md format |
scripts/ | Executable code (Python, Bash, JS) | Should have execute permissions |
assets/ | Static resources (templates, data) | No validation required |
Check 1.10-readme-in-folder (Warning): Skill folder must not contain a README.md file. All documentation goes in SKILL.md or references/. For GitHub distribution, place the README at the repo root, outside the skill folder.
Detection: Use Glob to check if {skill-dir}/README.md exists.
Skill path formats supported:
- Standard: `~/.c