olgasafonova/skillcheck-free/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; 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. 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

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:

Claude Code Extensions

Recognized by Claude Code (per the Claude Code skills docs) 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).

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

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