Skill Portability Check

Our own public skills repository on 2026-10-04: it had grown to 15 skills, and a new one was skipped by npx skills add proskillpacks/skills --list with a YAML error. The same rule, run over our whole tree of 57 skills, found 7 descriptions with an unquoted colon (now fixed), and the checker's other warnings led us to add fallback sentences and remove a vendor tool name.

After (skill output, excerpt):
$ python3 scripts/skill_check.py proskillpacks-skills/skills --quiet
skill errors warnings lines scripts
accessibility-quick-audit 0 0 39 -
changelog-from-commits 0 0 39 -
readme-first-run-check 0 0 39 -
agent-ready-quick-check 0 0 64 Python
late-payment-chaser-uk 0 0 109 Python
...
15 skill(s): 0 error(s), 0 warning(s)

$ python3 scripts/skill_check.py examples/bad-yaml-colon/SKILL.md
ERROR frontmatter: line 3: description: unquoted ': ' inside the value (strict YAML reads it as a nested mapping). Quote the value or reword

A free checker for Agent Skills. Point it at a skill folder or a whole repository of skills and it reports, per SKILL.md, the things that make a skill fail to load or stop it working outside one assistant: frontmatter that strict YAML parsers reject, keys other than name and description, vendor tool names and paths, missing fallbacks, long bodies and broken links. One Python file, standard library only, with a non-zero exit code for CI.

Run over our own 57 skills and its four fixtures (5 checks pass). It found 7 descriptions our tools had accepted but strict YAML parsers reject, now fixed. The assistant wrapper was not model-tested.

Tested on a real example before release. The example is shown in the Before and after section above.

How we test, what we do not do, and which assistants we ran it on.

• It reads files; it cannot tell whether a skill's instructions work or whether it triggers.
• Warnings are portability risks, not proof of breakage.
• The vendor pattern lists are not exhaustive.

Works with any assistant that reads SKILL.md skills (Claude, Codex, Gemini CLI, Cursor and others), plus a paste-in prompt version for ChatGPT or any chatbot. Python 3 (standard library only). Without a shell, the skill checks a pasted SKILL.md by reading.

1. Run npx skills add proskillpacks/skills in your project and pick this skill. Or copy the skill-portability-check folder from GitHub (https://github.com/proskillpacks/skills/tree/main/skills/developers/skill-portability-check).
2. Put the skill-portability-check folder where your assistant looks for skills. The generic path is .agents/skills/ (or npx skills add from a folder). Tool-specific paths:
   • Claude Code: ~/.claude/skills/ (or .claude/skills/ inside one project)
   • OpenAI Codex, Gemini CLI, Cursor and others: .agents/skills/ or the skills folder their docs name
   • claude.ai: zip the skill folder yourself, then Customize, Skills, the plus button, Create skill, Upload a skill (code execution must be on in Settings, Capabilities)
   • ChatGPT or any chatbot: open the skill's prompt.md, paste it into the chat, then paste your own text or link
   • Steps for each tool, with links to its official docs: how to install Agent Skills
3. Ask for the job in plain words, for example: "Check my skills repo for portability problems.". The skill loads by itself.