SkillCheck: Skill Folder Preflight
Find what gets a skill rejected, before the reviewer does.
SkillCheck is a preflight for agent skills. Point it at a skill folder or a .zip and an offline script checks it against 17 rules, then your agent explains each finding and offers a fix.
What it looks for
- SKILL.md frontmatter: missing or never closed, an unquoted
:in the description that breaks YAML, bad or reserved names, no version - Description: too long, too short, vague words ("various", "and more"), no "Use when…" trigger
- Missing files: links and paths in SKILL.md and docs that point to files that are not there, including letter-case mismatches that fail on Linux
- Leftover text: pasted listing headings such as "Capafy listing content", TODO lines, lorem ipsum, form-field text
- Secrets: API keys, tokens, private keys, passwords in URLs, and files such as
.envorid_rsa(masked in the report) - Size and junk: oversized files,
__pycache__,.DS_Store,.git, nested zips, executables, symlinks, files nothing refers to - Tests: scripts with no tests, no examples, examples with no expected output
- Scripts: syntax errors, network imports in a script the docs call offline,
eval,os.system - Consistency: version numbers that disagree, hosted wording in a download package (or the reverse), different model names
What you get
A report in JSON and Markdown: every issue ranked high, medium or low with file, line and a plain-words fix, a verdict, and a list of what was not measured. Exit code 2 when a high issue exists, so you can run it before every release.
Included: a clean example skill, a deliberately flawed one, and the expected reports.
Where it runs and what you need
SkillCheck is a download package. You unzip it and use it in your own environment. It does not run through Capafy's cloud, and no AI model is included in the price.
You provide:
- An AI agent or assistant that can read a SKILL.md file, read and write files in a working folder, and run shell commands. The instructions are written for a Claude-style agent; other agents have not been tested. You can also run the script yourself without an agent.
- Python 3 (standard library only, nothing to install; developed on Python 3.13, other 3.x versions not tested).
- Your own model or provider account, if you use an agent. Any model usage fees are charged by your provider, not by this package.
Data sharing
Nothing is sent to Capafy or to the author by this package. The script runs on your computer, makes no network calls and imports no network libraries. A zip is read in memory, never extracted, and the checked folder is never modified. If you use an agent, the report and the parts of your skill it reads go to that agent and its provider under their terms.
Honest limits
- It checks structure, wording and files against its own rules. It does not show that the skill works, that its instructions are good, or that a marketplace will accept it.
- It does not test whether a model would pick your skill; the description is checked for length, wording and a stated trigger only.
- Secret detection uses a fixed list of patterns. It will miss other formats, secrets in binary files, and secrets split across lines.
- Only Python scripts get a syntax check. Size limits are adjustable defaults and may differ from any marketplace's real limits. Links are not followed.
- Tested with 228 tests; deliberate code breaks (140 tried) were caught except 14, mostly wording or equivalent changes.
- Not legal, security or professional advice. For adults (18+).
