skill-check — Claude Code skill: validate SKILL.md against Anthropic rules

---
name: skill-check
description: Validate Claude Code skills against Anthropic guidelines. Use when user says "check skill", "skillcheck", "validate SKILL.md", or asks to find issues in skill definitions. Covers structural and semantic validation. Do NOT use for anti-slop detection, security scanning, token analysis, enterprise checks, or Eval Kit generation; use skill-check-pro for those. Do NOT use for LinkedIn skill engagement; use skillcheck-engage for that.
license: MIT
allowed-tools: Read Glob Grep
compatibility: claude-code
metadata:
  category: development
  version: 3.33.0
  author: olgasafonova
---

# SkillCheck (Free)

Check skills against Anthropic guidelines and the agentskills specification. This file contains Free tier validation rules.

**Want deeper analysis?** [Upgrade to Pro](https://getskillcheck.com) 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; the Invisible Unicode checks also use Grep, which stays read-only)
- No environment variables or API keys required; the checks run fully offline

## Interface

- **Input**: path(s) to SKILL.md files, plus any `references/*.md` files in the same skill folder
- **Output**: a validation report listing each issue with check ID, severity (Critical / Warning / Suggestion), line number, and fix; strengths reported in a separate list
- **Modes**: runs standalone on a single skill or over a directory of skills, one report per skill

## Workflow

Run the four stages in order for each target skill. Data flows forward: the file list from Step 1 feeds Step 2, the loaded content feeds Step 3, and the findings feed Step 4.

- **Step 1: Locate** — find target SKILL.md file(s) with Glob
- **Step 2: Read** — load the SKILL.md content and any `references/` files
- **Step 3: Validate** — apply each rule section below to the loaded content
- **Step 4: Report** — list issues found with severity, line number, and fix

**Execution limits**: maximum iterations: 1 validation pass per skill. Stop after every located skill has been reported once; abort if a SKILL.md cannot be read and say so in the report. The check is read-only and idempotent — safe to re-run, and repeated runs on unchanged files produce identical reports.

---

# Free Tier Validation Rules

> Worked valid/invalid examples for every check below are in [references/examples.md](references/examples.md). The rules are here; the examples are one file away to keep this file scannable.

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](https://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 (per the [Claude Code skills docs](https://code.claude.com/docs/en/skills)) but not part of the agentskills.io spec. Other agents may ignore these fields, and claude.ai uploads and the Skills API reject them (see 1.19).

| Field | Purpose |
|-------|---------|
| `when_to_use` | Extra trigger context, appended to `description` in the skill listing |
| `argument-hint` | Autocomplete hint for expected arguments |
| `arguments` | Named positional arguments for `$name` substitution (space-separated string or YAML list) |
| `model` | Override model (full ID like claude-opus-4-6, alias: opus, sonnet, haiku, or `inherit`) |
| `effort` | Effort level: low, medium, high, xhigh, or max |
| `disallowed-tools` | Tools removed while the skill is active (space- or comma-separated string, or YAML list) |
| `context` | Run context ("fork" for sub-agent) |
| `agent` | Agent type when context: fork |
| `background` | With `context: fork`, set false to wait for the forked result (default: true) |
| `hooks` | Lifecycle hooks (PreToolUse, PostToolUse, Stop) |
| `paths` | Glob patterns that limit when the skill auto-activates (comma-separated string or YAML list) |
| `shell` | Shell for inline commands: bash (default) or powershell |
| `user-invocable` | Show in slash menu (default: true) |
| `disable-model-invocation` | Manual-only skill |

### Community Extensions

Not part of any spec, and not read by Claude Code (it ignores them silently). Used by community tools and registries. Do not flag them under 1.8 or 1.19.

| Field | Purpose |
|-------|---------|
| `category` | Skill domain(s) for discovery and filtering |
| `produces` | Artifact types this skill outputs (comma-separated) |
| `consumes` | Artifact types this skill reads from other skills (comma-separated) |
| `type` | Skill type indicator |
| `author` | Skill author |
| `date` | Creation/update date |

### Field Recognition and Values

**Check 1.8-unexpected-field** (Suggestion): A top-level key that appears in none of the three tables above (spec, Claude Code, community). Claude Code ignores unknown keys without reporting an error, so a typo silently does nothing; claude.ai uploads and the Skills API reject the file outright. Keys under `metadata` are free-form and never flagged.

**Check 1.13-disallowed-camelcase** (Suggestion): `disallowedTools` is the subagent spelling. In SKILL.md the field is `disallowed-tools`; the camelCase key is ignored. Report this instead of 1.8.

**Check 1.12-maxturns-not-skill-field** (Suggestion): `maxTurns` is a subagent field, not a skill field. Claude Code ignores it in SKILL.md. Report this instead of 1.8.

**Check 1.19-non-portable-field** (Suggestion): One finding listing every key outside the spec that is present, from the Claude Code table and the community table alike. Claude Code loads or ignores them, but claude.ai uploads and the Skills API accept only `name`, `description`, `license`, `compatibility`, `metadata` and `allowed-tools`.

**Check 1.11-effort-invalid** (Warning): `effort` is not one of `low`, `medium`, `high`, `xhigh`, `max`.

**Check 1.18-bool-value** (Warning): `user-invocable`, `disable-model-invocation` or `background` holds something other than `true`, `false`, `yes`, `no`, `on`, `off`, `1` or `0` (any letter case).

**Check 1.14-listing-cap** (Warning): `description` plus `when_to_use` exceeds 1,536 characters. The skill listing truncates the combined text at that length, so trailing triggers are lost. Put the key use case first.

**Check 1.15-shell-invalid** (Warning): `shell` is set to anything other than `bash` or `powershell`.

**Check 1.16-background-no-fork** (Suggestion): `background` is set but `context: fork` is not. The field only applies to forked skills.

**Check 1.17-paths-invalid** (Warning): `paths` is not a glob string (comma-separated allowed) or a YAML list of glob strings, for example a map, a number, a boolean, or an empty value.

### Category Validation

> **Note**: `category` is a community 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**: `produces` and `consumes` are community 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; the known list is a starting set, not a registry.

**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:
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"

### allowed-tools Validation

Both space-separated (`allowed-tools: Read Glob`) and YAML list formats are valid. See references/examples.md for both shapes.

### 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 |

Any other files, including a `README.md`, are allowed in the skill folder per the agentskills spec. Do not flag them.

**Skill path formats supported**:
- Standard: `~/.claude/skills/{skill-name}/SKILL.md`
- Namespaced: `~/.claude/skills/{namespace}/{skill-name}/SKILL.md`

**Namespace support**: Namespaces allow organizing skills by source (personal, team, project):
- `~/.claude/skills/internal/weekly-reports/SKILL.md`
- `~/.claude/skills/shared/code-review/SKILL.md`

**Directory name must match skill name**: The parent directory name must exactly match the `name` field in frontmatter.

---

## 2. Naming Quality

Names should be descriptive compounds, not single words.

**Length Guidelines**: Minimum 3 chars, optimal 10-30 chars, maximum 64 chars.

### Anti-Pattern Format Lint

**Check 2.8-antipattern-format** (Suggestion): When a skill documents anti-patterns (sections with headers matching "anti-pattern", "what not to do", "avoid", "common mistakes", "bad practices", "pitfalls"), the content should use structured formats (tables or bullet lists) rather than wall-of-text prose.

**Fires when**:
- Anti-pattern section has a long prose line (100+ chars) containing don't/avoid/never
- Anti-pattern section has 3+ prose lines with 3+ avoidance directives

**Does NOT fire when**:
- Section already uses tables (`| col | col |`) or bullet lists (`- item`)
- Section header doesn't match anti-pattern keywords

---

## 3. Semantic Checks

Validate logical consistency and clarity of skill instructions.

### Contradiction Detection

Flag conflicting instructions that simultaneously require and forbid the same action.

### Ambiguous Terms

Flag vague language that should be more specific. Terms like "multiple items" or "correct settings" lack precision. Use exact counts or specific criteria instead.

**Exceptions** (not flagged):
- Terms inside code blocks or blockquotes
- Terms inside inline code spans (backticks); a backticked literal is a quoted example, not vague writing
- Content in example/usage/pattern sections
- Before/After and correct/incorrect comparison lines
- Terms followed by qualifiers (e.g., "some specific files")

### Output Format Specification

Skills that mention output should specify format with concrete examples.

**Detection**:
- Skill mentions "output/returns/produces" without `## Output` section
- Has output section but lacks code blocks, JSON, or tables

### Wisdom/Platitude Detection

**Check 4.6-wisdom-platitude** (Suggestion): Detects generic advice ("wisdom") that lacks actionable content. Skills should contain concrete instructions, not motivational prose.

**Three detection layers**:

1. **Opener patterns**: Lines starting with wisdom phrases like "Remember that", "It's important to", "Keep in mind that", "Think about", "Never forget that", "Always keep in mind", "Consider the importance of"
2. **Platitude structures**: Mid-line "[noun] is essential/crucial/important to [noun]" patterns
3. **Vague imperatives**: `"Ensure quality"`, `"maintain standards"`, `"strive for best practices"`

**Exceptions** (not flagged):
- Content inside code blocks or blockquotes
- Content in example/usage/pattern sections
- Before/After and positive/negative comparison lines

### Description Trigger Style

**Check 4.8-description-trigger-style** (Suggestion): The description field should read as a trigger condition, not a capability summary. Claude scans descriptions to decide "is there a skill for this request?" A trigger-oriented description activates when the request matches; a summary-oriented one gets overlooked.

**Detection**: Description opens with summary patterns instead of trigger patterns:
- Summary openers (flag): "This skill", "A tool that", "Provides", "Offers", "Handles", "Manages", "Enables"
- Trigger openers (pass): "Use when", "Generate", "Build", "Convert", "Extract", "Validate", "Run", "Create", "Find", "Search"

**Does NOT fire when**:
- Description has a summary opener but also contains a WHEN trigger phrase later ("Handles X. Use when user says Y" is fine)
- Description starts with an action verb

**Severity**: Suggestion

**Fix**: Rewrite to lead with action verb and include "Use when" clause. The description is a routing instruction, not documentation.

### Railroading Detection

**Check 4.9-railroading** (Suggestion): Skills should give Claude information and context, not dictate exact sequences. Excessive prescriptive language reduces Claude's ability to adapt to the user's actual situation.

**Detection**: Count prescriptive phrases outside example blocks, code blocks, and anti-pattern sections:
- "you must always", "always do exactly", "never deviate", "follow these exact steps", "do not change this", "this is the only way", "you are required to"

**Fires when**: 5+ prescriptive phrases in non-example content.

**Does NOT fire when**:
- Prescriptive language is inside code blocks, blockquotes, or example tags
- Prescriptive language is in anti-pattern/gotchas sections (where it describes what NOT to do)
- Skill is a safety-critical skill (security, compliance) where strict instructions are warranted

**Severity**: Suggestion

### Misplaced Routing Content

**Check 4.4**: Body contains trigger conditions that belong in the description field.

**Detection**: Body contains a heading matching `## When to Use` or `## When to Use This Skill`, or body text contains routing phrases like "Activate when user", "Trigger this skill when", "Use this skill when".

**Problem**: The skill body loads only AFTER the Skill tool is invoked. Trigger conditions placed here don't influence routing decisions. Claude reads the `description` field during routing; that's where "Use when" patterns, trigger keywords, and example phrases belong.

**Severity**: Warning

**Fix**: Merge unique trigger content from the body section into the `description` field, then remove the redundant body section.

### Hollow Content

**Check 22.7-hollow-content** (Suggestion): A gotchas/troubleshooting section that contains only generic filler and no concrete knowledge is hollow. It promises hard-won advice but delivers platitudes.

**Detection**: In a `## Gotchas` / `## Troubleshooting` / `## Tips` / `## Caveats` / `## Pitfalls` section, fire when 3+ lines match a generic filler phrase from the list below AND no line carries a concrete knowledge signal (a specific threshold/number-with-unit, a consequence "X because Y", a numbered debugging step, or a file/function reference).

```text
follow team standards
ensure proper handling
handle appropriately
consider relevant factors
use appropriate methods
maintain quality
```

**Exceptions** (not flagged): content inside code blocks; a section that includes at least one concrete threshold, consequence, or debugging step.

### Restraint Without Safety Carve-Out

**Check 28.2-restraint-without-carveout** (Warning): If a skill instructs restraint/minimalism but never carves out validation, security, or accessibility, flag it. Restraint without that carve-out can reward skipping non-negotiables, not just avoiding gold-plating. "Lazy, not negligent" is the line.

**Detection**: A restraint/anti-overbuild directive is present (YAGNI, "keep it minimal", "don't over-build / over-engineer", "simplest thing that works", "resist the urge to add", "prefer the stdlib"), AND no line pairs a keep/never-cut cue ("never cut", "always keep", "still required", "non-negotiable") with a safety noun (validation, security, accessibility / a11y). An incidental mention of "security" or "validation" *without* a keep cue does NOT count as a carve-out.

**Does NOT fire when**: no restraint directive is present; or an explicit carve-out clause exists.

**Severity**: Warning

---

## 4. Quality Patterns (Strengths)

Recognize positive patterns in skills. These are reported as "strengths" rather than issues. Checks 8.1–8.9 detect: example sections, error handling, trigger phrases, output format, structured instructions, prerequisites, negative triggers, and gotchas sections. Detection patterns and worked examples for each are in [references/examples.md](references/examples.md).

---

## 5. Invisible Unicode (Cat 30)

Invisible characters hide instructions from human reviewers while every AI agent reads them. Run these three Grep searches over the SKILL.md and every `references/*.md` file. Do not rely on reading the file to spot them — they render as nothing; only a pattern search finds them reliably.

### ASCII Smuggling

**Check 30.1-ascii-smuggling** (Critical): Unicode tag characters carry an entire hidden ASCII message.

**Detection**: Grep pattern `[\x{E0000}-\x{E007F}]`.

**Exemption**: a well-formed flag emoji is the one legitimate use of this block: U+1F3F4 followed by 2–6 tag letters/digits and the cancel tag U+E007F (the Scotland/Wales flags). If the match sits immediately after U+1F3F4 and ends with U+E007F, it is an emoji — do not flag it. Anything else in this block is smuggling.

**Report**: decode the payload (each character in U+E0020–U+E007E is its codepoint minus 0xE0000, read as ASCII) and quote the decoded text in the finding, so the author sees exactly what was hidden.

### Trojan-Source BiDi Overrides

**Check 30.2-bidi-override** (Critical): Bidirectional control characters make displayed text differ from actual text (CVE-2021-42574) — a filename that reads as an image can really be an executable.

**Detection**: Grep pattern `[\x{061C}\x{200E}\x{200F}\x{202A}-\x{202E}\x{2066}-\x{2069}]`.

**Does NOT fire when**: the skill is legitimately bilingual with right-to-left scripts (Arabic, Hebrew) AND the marks appear inside that prose. A BiDi mark in an English-only skill, a code block, a filename, or a command is always a finding.

### Zero-Width Characters

**Checks 30.3-invisible-run / 30.4-invisible-char**: zero-width characters split words invisibly or encode hidden data.

**Detection**: Grep pattern `[\x{034F}\x{180E}\x{200B}\x{200C}\x{2060}\x{FEFF}\x{2061}-\x{2064}\x{206A}-\x{206F}]`.

**Severity**: 10+ consecutive matches on one line is a Critical (30.3, hidden-data channel; 40+ is unambiguous). 3+ grouped is a Warning, an isolated one is a Suggestion (30.4).

**Exemptions**: a U+FEFF as the very first character of the file is a byte-order mark left by tooling — report nothing. Zero-width joiners and variation selectors are deliberately absent from the pattern: they are structural in emoji sequences (family emoji, ❤️) and flagging them teaches authors to ignore the category.