- Home
- Skills
- Prompt & Skill Engineering
- Skillset Lint: Fix Skills That Don't Trigger
Works with the AI Agents you already use
Skillset Lint: Fix Skills That Don't Trigger
It sees **all of them**, and picks one by its description.
Free
Skillset Lint: Fix Skills That Don't Trigger
Example session with this skill installed
Lint the skills in this repo before I publish them, and check them against the skills I already have installed.
- Read your context and instructions
- Compiled the skillset lint
Summary
I linted the 20 skills in this repository (the real result for anthropics/skills). 2 will not load on strict clients, 3 will load but rarely trigger. Nothing risky was found in the scripts.
Will not load
| Skill | Rule | Problem | Fix |
|---|---|---|---|
| claude-api | SL005 | description is 1,068 characters; the spec limit is 1,024 | Trim to ~600 characters; move the model list into the body |
| template | SL004 | name: template-skill does not match its folder template | Rename the folder or the name |
Will load but trigger badly
| Skill | Rule | Problem |
|---|---|---|
| theme-factory | SL006 | says what it is, never when to use it |
| webapp-testing | SL006 | same |
| template | SL006 | same |
Suggested description for webapp-testing:
Tests local web applications with Playwright: verifies frontend behavior, debugs UI issues, captures screenshots and reads browser logs. Use when the user asks to test, check or debug a web app running locally.
Cost and hygiene
- claude-api: SKILL.md body is ~26,000 tokens, 5× the recommended size. Split reference sections into
shared/*.md. - skill-creator: ~8,200 tokens.
- The skill list adds ~2,600 tokens to every conversation; the longest descriptions are claude-api, academy-guide and discernment-nudge.
Next steps
Shall I (1) shorten the claude-api description, (2) rename the template folder, and (3) rewrite the three descriptions above? Then I will re-run the linter and show the before/after counts.
Connects securely to your tools. The creator never sees your data.
About this skill
Why your skill doesn't trigger
Your agent never sees one skill. It sees all of them, and picks one by its description. So the bugs that hurt in practice live between skills:
- Two skills read alike, and the agent loads the wrong one, or neither.
- Two skills share a name in different folders, and which one wins depends on load order.
- Every description is paid for in every conversation. 30 installed skills can cost 4,000+ tokens before you type a word.
Skillset Lint checks each skill against the Agent Skills spec and best practices, then checks the set.
What it checks
Each skill (24 rules)
- Frontmatter: valid YAML (with the exact line),
namerules and folder match,description1-1024 characters,compatibility,metadata,allowed-tools - Descriptions that say what but not when to use it, first-person descriptions,
<>that some clients reject, reserved words - File references that do not exist, backslash paths, reference chains deeper than one level, scripts nothing mentions
- SKILL.md over 500 lines or ~5,000 tokens, placeholder text
- Security:
curl | bash, hard-coded secrets (masked), hidden Unicode, credential files sent over the network, unguardedrm -rf
The set (4 rules)
- Duplicate names
- Overlapping descriptions, with the shared words that cause it
- How many tokens the skill list costs per conversation, and the longest descriptions
How the agent uses it
- Runs the bundled zero-dependency Node script on a folder, a repo, or everything installed (
--installed: Claude Code, plugins, Codex, OpenCode, project skill folders). - Groups the results: will not load, will load but trigger badly, risky, cost and hygiene.
- Fixes what you approve: renames, rewritten descriptions (both sides of an overlap), fixed paths, split-out reference files. Then re-runs to show the before/after.
Found in real repositories
On anthropics/skills it found a description of 1,068 characters (over the 1,024 limit), a name that does not match its folder, and descriptions that never say when to use them. On obra/superpowers it flagged two skills whose descriptions overlap.
Never executes the scripts it checks. JSON and SARIF output, plus a GitHub Action for CI.
Open source (MIT): https://github.com/MBotirjonDev/skillset-lint
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Prompt & Skill Engineering.
Static analysis only; does not execute scripts. Requires Node.js to run the linting utility. Focuses on SKILL.md and metadata, not full logic debugging.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free to use
No account required to browse
Trust & safety
Security scan
Security scan passed 9 days ago
- Free with an Agensi account