Author(s): Chew Loong Nian – AI ENGINEER

Originally published on Towards AI.

Write Once, Run on 20+ Agents: I Tested SKILL.md on 4 of Them, and Cursor Collapsed

I took a single 40-line SKILL.md file, copied it into four different AI coding agents without changing a character, and asked each one to do the same job. Three of them — Claude Code, OpenAI Codex, and Gemini CLI — read it, understood it, and ran it cleanly. The fourth, Cursor, turned "write once, run anywhere" into "write once, debug forever."

The article explains what SKILL.md is (a folder containing a SKILL.md file with small YAML frontmatter plus markdown instructions, with optional scripts and reference assets, and a “progressive disclosure” model where agents only load the full skill when needed), then documents an experiment using five real skills across four agents over 20 runs. It finds that Claude Code cleanly enforces full spec behavior including advanced safety via allowed-tools, while Codex matches the workflow but does not enforce that guardrail, Gemini generally works but struggles when skills rely on shell/script execution details, and Cursor is where portability breaks down most severely—often treating skills as body-only text, skipping scripts or arguments, failing invocation, and ignoring constraints. It also highlights practical directory fragmentation (each tool wants skills in different local paths), making teams copy skills and let them drift, and suggests symlink-based “single source of truth” approaches that don’t help with cloud-only agents. Finally, it emphasizes security: skills are executable bundles, audited data suggests a meaningful fraction contain critical issues, and because safety fields may be Claude-only, relying on guardrails that aren’t uniformly enforced is dangerous—so it recommends sticking to the portable subset (name/description/body/$ARGUMENTS), using relative script paths, and assuming Cursor and advanced constraints may require manual verification.

Read the full blog for free on Medium.

Join thousands of data leaders on the AI newsletter. Join over 80,000 subscribers and keep up to date with the latest developments in AI. From research to projects and ideas. If you are building an AI startup, an AI-related product, or a service, we invite you to consider becoming a sponsor.

Published via Towards AI