skill-check

Files (4)

• SKILL.md
• passed.svg
• examples.md · references/
• marketplace-checks.md · references/

SKILL.md (first lines)

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

From olgasafonova/SkillCheck-Free, MIT.