How do I check that my SKILL.md file will load in other tools?

You write a skill, test it in one tool, and it works. Then someone installs it in another tool and it does not load, or loads but never triggers, or tells the assistant to use a tool that does not exist there.

Most of these problems are in the first twenty lines of the file. A description with an unquoted colon can be rejected by a strict YAML parser. A name with a capital letter breaks the naming rule. Instructions that name one vendor's tool fail everywhere else. You can catch these by reading.

What you need

• Your skill's SKILL.md, the whole file including the frontmatter between the two --- lines.
• One skill at a time.

The prompt

Paste this into a new chat, then paste the file under it.

You check an Agent Skill's main file for portability and common mistakes, by reading only. Quote the line behind each finding. Never claim the skill is valid or portable, and do not invent findings.

Check:
1. Errors: frontmatter missing or not closed; frontmatter a strict YAML parser would reject (an unquoted ": " or " #" inside the description, an unclosed quote, a stray indented line); missing name or description; a name that is not lowercase letters, digits and single hyphens or is over 64 characters (and if you can tell, does not match the folder name); a description over 1024 characters; markdown links to files that probably do not exist.
2. Warnings: frontmatter keys other than name and description (license, compatibility and metadata are spec keys: note them; allowed-tools and others are tool-specific); a description that does not say when to use the skill ("Use when the user says ..."); vendor tool names (WebFetch, Skill tool, Bash(...), mcp__) and vendor paths (.claude/, .cursor/); a body that relies on the web, a shell or a script but never says what to do when it is missing; text like $ARGUMENTS or $0 that some tools substitute; a body that looks over 500 lines.
3. For every finding give the line, why it matters in one sentence, and the exact replacement text.
4. End with what you could not check by reading (whether the instructions work, whether the skill triggers, files outside what I pasted).
Do not edit anything.

Here is my skill file:

[paste the SKILL.md here]

How to check the result

Start with the errors. For the rules about the frontmatter, the Agent Skills specification at agentskills.io says the name field is required and limited to 64 characters of lowercase letters, numbers and hyphens, and that it must not start or end with a hyphen. The description is required, up to 1024 characters, and should say what the skill does and when to use it. Check your file against those lines yourself: https://agentskills.io/specification

Then read each warning. A warning about a vendor tool name is a prompt to write the action neutrally: "fetch the page with whatever web tool you have, and if you have none, ask the user to paste it". A warning about a missing fallback means the skill assumes a tool that may not be there.

Apply the replacement text it gives you and run the check again. When it comes back with nothing to report, remember what that means: the file reads cleanly. It does not mean the instructions work.

A script that does the same job

Reading by a chatbot misses some things, such as whether linked files exist. We publish a free script that checks a whole folder of skills, parses the frontmatter like a strict parser and exits with an error code you can use in CI. It lives in our free skills repository, under skills/developers/skill-portability-check: https://github.com/proskillpacks/skills/tree/main/skills/developers/skill-portability-check . A separate repository, https://github.com/proskillpacks/skill-check , packages the same checks for use in your own pipeline.

Limits

• It checks the file by reading. It cannot run the skill or tell you whether it triggers.
• It cannot see files outside what you paste, so it cannot confirm that linked files exist.
• Tools differ, and specs change. Check the current rules for the tools you target.
• It never says a skill is valid. It lists what it found.

Browse all skills in the catalog

Want this as a ready-made skill? Skill Portability Check (Free) does it in your own assistant.