Your skill works. The agent just doesn't know when to use it.
A skill is a set of instructions that teaches an AI agent one job. SkillCheck reads it the way an agent does and tells you, in seconds, what will stop it from being used.
I write skills
Check one now, free. Every finding comes with the fix.
I use or approve skills
See what a grade means before you install someone else's skill.
- Runs on your machine
- Free version is open source (MIT)
- v3.35.0
It says what the skill is like, never what it does or when to use it. An agent has nothing to match a request against.
Now the agent knows what the skill does, when to reach for it, and when not to. The instructions underneath did not change.
- WarningDescription lacks triggering conditions
- WarningDescription missing WHAT clause
- WarningDescription missing WHEN clause
- WarningName contains vague term 'tools'
- PassedDescription includes activation triggers
- PassedDescription includes negative triggers
- WarningName contains vague term 'tools'
Real run · Free checks · v3.34.0 · 25-10-2026
What SkillCheck looks for
A skill can fail even when its instructions are right. SkillCheck asks four questions about every one.
Will the agent pick it?
The description has to say what the skill does and when to use it. If it doesn't, the agent never chooses it.
Naming · Semantics · Quality patterns · Trigger collision
Does it follow the standard?
Required fields, valid names and a well-formed settings block, so it loads in Claude Code, Cursor, VS Code and other agents.
Structure · Body · Plugin manifests (Cat 24) · MCP tool servers (Cat 23)
Is it clear and free of filler?
Vague words, contradictions and stock AI phrases make an agent guess what you meant.
Semantics · Anti-slop · Knowledge density · Token budget
Is it safe to run?
Could it ask for tools it doesn't need, leak a key, or hide instructions in invisible characters?
Security · OWASP Agentic (Cat 26) · Invisible Unicode (Cat 30)
None of these checks is invented. Each one traces to a published spec, a research paper or documented practitioner experience, and we document what informed it and why it matters. See the sources
We checked 28,579 public skill files
On every release we run SkillCheck Pro on the skills published in public repositories. This round covered 172 of them.
Scores across the scan
Share of skill files in each score range. Scores of 0 to 59 are the Poor grade: 29.7% of the scan.
28,579 skill files from 172 public repositories · percentages of the 18,682 unique files, rounded · SkillCheck Pro v3.34.0 · scanned 11-10-2026
Before you install someone else's skill
Open its report. Three things tell you whether it is safe to depend on.
The grade
Excellent or Good means the skill does what it says. Needs Work or Poor means problems an agent or a user will notice.
Critical findings
There should be none. Any Critical finding caps the grade at Needs Work, so a report never says Good next to a must-fix problem.
The fixes
Every finding names the line and the change to make. You can pass them straight to the author.
Three skills that scored Excellent
Free, Pro and Team
The free version checks that a skill is built correctly. Pro also checks whether it is built well: security, writing quality, accessibility and agent readiness.
Checks the structure, the required fields and the wording. It runs as a skill in Claude Code, with nothing to install.
- StructureMissing fields, invalid names, broken YAML, XML injection
- Body and namingContent requirements, formatting, conventions, reserved words
- SemanticsContradictions, vague wording, empty statements, steps crammed into the description
- Quality patternsExamples, error handling, triggers, output format, gotchas
- Agent security basics (Cat 26)8 checks from the OWASP list of top risks for AI agents: tools it doesn't need, identity override, unpinned dependencies
- Invisible characters (Cat 30)Instructions hidden in invisible characters, decoded and shown; text that displays differently from how it runs
Everything in Free, plus deeper checks for skills, plugins and MCP servers (small programs that give an agent new tools). Checks added in later releases are included at no extra cost. License terms.
- SecurityLeaked keys and personal data, unsafe file paths, risky shell commands
- Writing quality (anti-slop)Stock AI phrases such as "Let's dive in", hedge words, inflated wording
- Accessibility (WCAG)Color contrast and accessibility for skills that produce UI
- Agent readinessCan an agent run it on its own: 28 checks, rated from L0 (manual) to L3 (ready to run unattended)
- Token budgetHow much of the agent's memory the skill uses; can fail a build when it grows too large
- Enterprise and workflowHardcoded paths, audit support, steps with no clear end, deploying without a check
- Overlap and test casesFinds skills that compete for the same request; writes test cases for
claude plugin eval - Plugins, MCP servers and upkeepPlugin manifests (Cat 24), MCP servers (Cat 23), and whether a skill was ever revised after it was written (Cat 27)
Pro for a team of up to 10 people.
- Everything in Pro
- Custom rulesets
- Team dashboard
- CI/CD integration
Not on sale yet
Pro includes a GitHub Action, uses: olgasafonova/skillcheck@v3, that blocks low-quality skills in pull requests.
Every check category, Free and Pro
| Category | Tier | What it catches |
|---|---|---|
| Structure | Free | Missing fields, invalid names, broken YAML, XML injection, effort, maxTurns, disallowedTools |
| Body | Free | Content requirements, length, formatting, anti-pattern format lint, MCP tool qualification |
| Naming | Free | Conventions, specificity, reserved words, gerund naming |
| Semantics | Free | Contradictions, ambiguity, platitudes, workflow in the description, railroading |
| Quality patterns | Free | Examples, error handling, triggers, output format, prerequisites, gotchas |
| Anti-slop | Pro | "Let's dive in", hedge words, filler phrases |
| Visual and WCAG | Pro | Color contrast, accessibility, visual design checks for skills that produce UI |
| Security | Pro | Personal data, credential safety, path traversal, Bash guardrail validation |
| Token budget | Pro | Context efficiency, budget analysis, frontmatter overhead |
| Enterprise | Pro | Hardcoded paths, environment config, audit support, metadata, data-storage path safety |
| Workflow | Pro | Exit criteria, unbounded iteration, deploy without verify, feedback loops |
| Agent readiness | Pro | 28 checks across 6 pillars; maturity L0 (manual) to L3 (autonomous-ready) |
| Design pattern | Free + Pro | Classifies Reviewer, Generator, Inversion, Pipeline, Tool Wrapper; Pro validates per pattern |
| Trigger collision | Pro | Overlap between skills and gaps in artifact pipelines |
| Eval Kit | Pro | Writes claude plugin eval cases from trigger phrases; plan preview in Free |
| Knowledge density | Free + Pro | Flags hollow sections (Free); rewards thresholds, consequences, debugging logic (Pro) |
| Skill discovery | Free + Pro | Finds skill candidates in CLAUDE.md, .cursorrules and AGENTS.md; Pro writes the SKILL.md |
| Plugin manifests · Cat 24 | Free + Pro | Schema (Free) plus marketplace governance: maintainers, evals, deprecation (Pro) |
| MCP tool servers · Cat 23 | Free + Pro | Tool count and CRUD smell (Free) plus identity override, annotations, CLI literacy (Pro) |
| OWASP Agentic · Cat 26 | Free + Pro | 8 deterministic checks (Free) plus intent graders your own AI evaluates (Pro) |
| Repo maturity · Cat 27 | Pro | Git history: commit count, recency, skills written once and never revised |
| Restraint · Cat 28 | Free + Pro | Warns when "keep it simple" drops validation, security or accessibility (Free); rewards simple but safe (Pro) |
| Skill distribution · Cat 29 | Free + Pro | Will the skills load when a repository is mounted into a Managed Agents session |
| Invisible Unicode · Cat 30 | Free | Hidden instructions in invisible characters, trojan-source direction tricks, zero-width runs |
What informed each category: methodology
How to run it
Every check runs on your own machine. Nothing is uploaded.
Paste and check
Paste a SKILL.md, a plugin manifest or an MCP tool list into the validator. It runs inside the page with WebAssembly.
Open the validatorAsk for a check
- Copy
skill-checkinto~/.claude/skills/ - Say "skillcheck my skill"
- Read the findings inline
Check skills, plugins and servers
skillcheck check ./my-skill
skillcheck check-plugin \
--pro plugin.json
skillcheck check-mcp \
--pro tools-list.json$ skillcheck check pdf-tools ## pdf-tools Check Results [FREE] ### Warnings (4) - 3.1-name-vague (line 2): Name contains vague term 'tools' - 4.5-desc-no-triggers (line 2): Description lacks triggering conditions - 1.2-desc-what (line 3): Description missing WHAT clause (action verb) - 1.2-desc-when (line 3): Description missing WHEN clause ### Suggestions (3) - 3.4-gerund-naming (line 2): Skill name could use gerund form for clarity - 4.2-ambiguous-term (line 8): Ambiguous term 'several' found - 4.3-output-no-example (line 1): Output section lacks concrete format examples ### Passed Checks: 102 / 109 applicable Status: Needs Attention
Real output from the Free checks on the "before" version of pdf-tools above · score 77 / 100
Recent releases
The three latest versions. Every release since December 2025 is in the changelog.
Fewer false alarms, and scan matches check
scan and check now give a skill the same score. Placeholders and quoted examples are no longer reported as problems.
Fewer false alarms, and a check for forgotten files
Pattern text is no longer mistaken for a Windows path, and Unicode codes such as U+200D no longer for phone numbers. A new Pro check lists files in references/ that SKILL.md never mentions, so the agent never opens them.
Checks that match Claude Code
Free frontmatter checks for fields Claude Code ignores or claude.ai rejects. Eval Kit now writes real claude plugin eval suites, and token budgets can fail a pull request.
Questions
If yours isn't here, open an issue on GitHub.
What is a skill?
A folder of instructions, a SKILL.md file and sometimes scripts, that teaches an AI agent how to do one job. The short description at the top tells the agent when to use it.
Is this official Anthropic tooling?
No. SkillCheck is an independent project. Free validates against the Agent Skills open standard created by Anthropic; Pro adds checks for writing quality, accessibility and security.
Which agents does it work with?
It is built and tested for Claude Code. Because it follows the open standard and the MCP protocol, it also works with Cursor, VS Code, Windsurf and other compatible tools.
Does my skill leave my machine?
No. Every check runs locally: in the command line, in CI, or in the browser build. Nothing is uploaded, which matters when your skills hold confidential product knowledge.
What does $79 get me?
A lifetime Pro license: the binary, the MCP server and every Pro check for skills, plugins and MCP servers. Checks we add in later releases are included at no extra cost. No subscription. One license covers one person, on any number of machines and in CI (continuous integration). Read the license. To try Pro on one project first, the 30-day Pro Pass is $15 at the same checkout, with the same binary and checks.
What happens when my Pro Pass expires?
The binary drops back to the Free checks. Nothing breaks, nothing renews and nothing is charged. Buy a new pass or the lifetime license whenever you need Pro again.
Can I use it in CI?
Yes. Pro ships a GitHub Actions integration. Add uses: olgasafonova/skillcheck@v3 to block pull requests that introduce low-quality skills.
What if I disagree with a check?
SkillCheck reports; you decide what to fix. Suggestions are advice, not requirements, and together they can cost at most 15 points.
Check your skill before someone else depends on it.
The free check runs in your browser, with no signup.