skill-check

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

1. Locate: Find target SKILL.md file(s)
2. Read: Load the content
3. Validate: Apply each rule section below
4. 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: category is 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

<example type="valid"> category: development </example>

<example type="valid"> category:

• development
• automation

</example>

<example type="invalid"> category: Dev_Tools reason: uppercase and underscore not allowed </example>

<example type="invalid"> category: my--category reason: consecutive hyphens not allowed </example>

Artifact Passing Validation

Note: produces and consumes are 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.

<example type="valid"> produces: content-brief, knowledge-note </example>

<example type="valid"> consumes: content-brief </example>

<example type="invalid"> produces: Content_Brief reason: uppercase and underscore not allowed </example>

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.

<example type="valid"> name: weekly-report-generator </example>

<example type="invalid"> name: helper-tool reason: vague term "helper" </example>

<example type="invalid"> name: Claude_Skill reason: uppercase and underscore not allowed </example>

Description Validation

Must contain:

1. WHAT: Action verb explaining what skill does
2. WHEN: Trigger phrase for when to use it
3. 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