Cross-Agent Skills — Cursor, Codex, Cline, Antigravity, Gemini CLI, Mastra, Vercel: Portability in 2026

TL;DR — the portability matrix

Eight agents, one format, three categories. Native readers — Claude Code, Cursor (since 2.4), OpenAI Codex CLI, Cline (experimental flag), Google Antigravity, and Gemini CLI all parse SKILL.md directly and obey progressive disclosure. Installer- mediated — the long tail (OpenCode, Continue, Roo Code, Kiro CLI, Windsurf, Devin, Crush, Mistral Vibe, Qwen Code, Tabnine CLI, dozens more) gets skills via npx skills add, which symlinks the same SKILL.md into whatever path that agent expects. Holdouts — a handful of older agents (and Vercel’s own AI SDK, by argument rather than design) prefer AGENTS.md in the repo root and treat Skills as a discovery overhead they’d rather skip.

The corner cases that bite: case sensitivity on SKILL.md (Gemini CLI is strict), three different conventions for where the folder lives, and the experimental allowed-tools field that only two of the eight agents actually parse.

The SKILL.md spec status

Anthropic launched Skills on October 16 2025. From claude.com/blog/skills, verbatim: “Skills are folders that include instructions, scripts, and resources that Claude can load when needed… Skills use the same format everywhere. Build once, use across Claude apps, Claude Code, and API.” The same launch announced the open spec at github.com/agentskills/agentskills: “Agent Skills are a simple, open format for giving agents new capabilities and expertise… an open format maintained by Anthropic and open to contributions from the community.” Apache-2.0 for code, CC-BY-4.0 for docs, roughly 17.8K stars at the time of writing.

The current specification — published at agentskills.io/specification — defines the structure and frontmatter exactly:

• A skill is a directory containing SKILL.md (required) plus optional sibling directories scripts/, references/, and assets/.
• Frontmatter required fields: name (max 64 chars, lowercase letters, numbers, hyphens; no leading, trailing, or consecutive hyphens; must match the parent directory) and description (max 1024 chars, non-empty).
• Frontmatter optional fields: license, compatibility (max 500 chars), metadata (arbitrary key-value), and allowed-tools — explicitly marked Experimental in the spec, with the note “Support for this field may vary between agent implementations.”
• Progressive disclosure is canonical, not optional. Per the spec: “Metadata (~100 tokens): The name and description fields are loaded at startup for all skills. Instructions (<5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated. Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required.”

What that means for portability: any agent that parses YAML frontmatter and reads Markdown can support SKILL.md. The interesting differences are everywhere except the format — discovery paths, the activation gesture, sandboxing, and which optional fields are honored.

The example above is Anthropic’s own skill-creator, the canonical reference for what a real SKILL.md looks like. Every cross-agent runtime in the rest of this post can load that exact file unchanged.

Claude Code (canonical implementation)

Claude Code is the reference implementation and the only runtime guaranteed to honor every field in the spec. Per the official Agent Skills overview, verbatim: “Skills exist as directories on a virtual machine, and Claude interacts with them using the same bash commands you’d use to navigate files on your computer.”

• Project path: .claude/skills/
• Global path: ~/.claude/skills/
• Frontmatter: full spec compliance — all required fields, all optional fields, including allowed-tools.
• Sandbox: the docs note “Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities.”
• Gotcha: Anthropic’s own docs warn that “Custom Skills do not sync across surfaces” — a Skill uploaded to claude.ai is not automatically available via the API or in Claude Code. Each surface maintains its own store.

If you’re writing a new skill from scratch, start in Claude Code, validate against the canonical implementation, then move on to the other agents.

Cursor — the late but full adopter

Cursor shipped Skills support in version 2.4, released January 22 2026. From the Cursor 2.4 changelog, verbatim: “Cursor now supports Agent Skills in the editor and CLI. Agents can discover and apply skills when domain-specific knowledge and workflows are relevant.”

• Project paths: .cursor/skills/<name>/SKILL.md or .agents/skills/; nested under monorepo packages, e.g. apps/web/.cursor/skills/.
• Global paths: ~/.cursor/skills/ and ~/.agents/skills/.
• Legacy compatibility paths: .claude/skills/ and .codex/skills/ are also scanned, so a project initialized for Claude Code works in Cursor without a move.
• Activation: two gestures — type /skill-name in chat to invoke directly, or @ the skill from the context menu to attach it for the next turn. The agent can also pick a skill on its own from the description.
• Cursor-specific frontmatter: Cursor adds an optional paths field with glob patterns (e.g. "**/*.tsx") to scope a skill to specific file types. Every other agent will ignore this field harmlessly.
• Skills vs Rules: Cursor explicitly positions Skills alongside .cursor/rules/*.mdc — Rules are always loaded, Skills are loaded on demand. The Cursor docs phrase it as “Skills are loaded dynamically when the agent decides they’re relevant, which keeps your context window clean.”

Cursor users who came up on the .mdc rules system have an adjustment to make: the format is YAML frontmatter rather than the .mdc properties block, and you should not put a name field in a rule but you must in a skill. The two systems coexist; you can run both.

How to Create & Use SKILLS.md in Cursor (2026)

The Code City · click to play

OpenAI Codex CLI

OpenAI’s Codex CLI added first-class Skills support in late 2025. The feature page at developers.openai.com/codex/skills lists four discovery tiers, in order of precedence:

1. System / bundled: skills shipped inside the Codex binary by OpenAI.
2. Admin: /etc/codex/skills — intended for fleet-managed installations.
3. User: $HOME/.agents/skills.
4. Repo: .agents/skills in the current working directory or any parent up to the repo root.

• Frontmatter: the standard name + description are required; Codex implements the experimental allowed-tools field, like Claude Code.
• Codex-specific extension: an optional agents/openai.yaml file inside the skill folder lets you pin tool dependencies and UI configuration. Other agents do not read this file.
• Activation: two gestures — explicit /skills command or $-mention syntax in the CLI, plus implicit invocation when the task matches the skill description.
• Note on AGENTS.md: Codex CLI also reads AGENTS.md at the repo root. The two coexist — AGENTS.md is always loaded, skills are loaded on demand. Codex’s own repo ships an AGENTS.md that documents Rust conventions for the codex-rs subtree.

Codex CLI’s adoption of .agents/skills as the project path — rather than a vendor-specific path — is the clearest signal yet that the cross-agent convention is stabilizing on .agents/. Cursor, Gemini CLI, and Codex all accept it; Claude Code and Cline accept their own paths but tolerate .agents/ via Vercel’s installer.

Cline — experimental flag, full spec

Cline’s docs introduce Skills as “modular instruction sets that extend Cline’s capabilities for specific tasks… they load on-demand rather than consuming context constantly, unlike rules which remain always active.” The feature is gated behind a Settings toggle marked experimental.

• Project paths (three of them): .cline/skills/, .clinerules/skills/, and .claude/skills/. The triple lookup is a deliberate compatibility move — drop a Claude Code skill folder into a Cline project and it works without modification.
• Global paths: ~/.cline/skills/ on macOS/Linux, the equivalent under %USERPROFILE% on Windows.
• Frontmatter: name (must match the directory name in kebab-case) and description (max 1024 chars). Cline does not implement allowed-tools.
• Precedence: per the docs, “when a global skill and project skill have the same name, the global skill takes precedence.” This is unusual — Claude Code and Codex put the project ahead — so factor it in when you have name collisions.
• Loading levels: Cline implements the three-level progressive disclosure exactly: “Metadata (always loaded, ~100 tokens), Instructions (triggered on-demand, under 5k tokens), and Resources (loaded as needed).”

Google Antigravity

Google’s Antigravity Agent Skills page treats a skill as “a directory-based package containing a definition file (SKILL.md) and optional supporting assets (scripts, references, templates). While SKILL.md is the only required file, you can include additional resources like helper scripts, reference implementations, and templates.”

• Workspace path: <workspace>/.agent/skills/<name>/ — note the singular .agent, distinct from the plural .agents that Codex/Cursor/Gemini use.
• Global path: ~/.gemini/antigravity/global_skills/<name>/ per Google’s “getting started” codelab.
• Frontmatter: name and description; the docs note “a vague description like ‘Database tools’ is insufficient” and emphasize the description must be “descriptive enough for the LLM to recognize semantic relevance.”
• Activation flow: “When a conversation starts, the agent sees a list of available skills with their names and descriptions; if a skill looks relevant to the task, the agent reads the full SKILL.md content; the agent follows the skill’s instructions while working on the task, and doesn’t need explicit direction to use a skill.”
• Compatibility caveat: the singular .agent path means a skill written for Cursor (which uses .agents, plural) needs a symlink or the Vercel installer to land in the right place. Vercel’s CLI knows about both.

Gemini CLI

Gemini CLI shipped Skills first as an experimental feature and made them stable in v0.26.0. The official docs at geminicli.com/docs/cli/skills list four discovery tiers in order of precedence: built-in, extension-bundled, user, workspace.

• User paths: ~/.gemini/skills/ or ~/.agents/skills/ (alias).
• Workspace paths: .gemini/skills/ or .agents/skills/. Within a tier, .agents/skills/ takes precedence over .gemini/skills/.
• Activation flow: verbatim from the docs — “Discovery — Skill names and descriptions are injected into the system prompt at session start. Activation — The model calls activate_skill when identifying matching tasks. Consent — A confirmation prompt shows skill name, purpose, and directory access. Injection — Upon approval, the SKILL.md and bundled resources become available. Execution — The model proceeds with specialized expertise.”
• The case-sensitivity warning: Gemini CLI’s docs are explicit — “The filename must be exactly SKILL.md. Capitalization matters on case-sensitive filesystems (Linux, and macOS when configured as such): skill.md or Skill.md will be ignored.”
• Companion repo: google-gemini/gemini-skills ships gemini-api-dev, gemini-live-api-dev, and gemini-interactions-api — Apache-2.0, around 3.4K stars at the time of writing.

mkdir -p .claude/skills/vercel-react-native-skills && curl -L -o skill.zip "https://mcp.directory/api/skills/download/812" && unzip -o skill.zip -d .claude/skills/vercel-react-native-skills && rm skill.zip

The install card above is for vercel-labs/vercel-react-native-skills — one of the first skills shipped by Vercel that crosses Cursor, Codex, Claude Code, and Gemini CLI without modification.

Mastra — single skill, multi-agent

Mastra publishes one official skill at github.com/mastra-ai/skills (Apache-2.0). The README opens: “Official Mastra skills for agents working with the Mastra framework, a framework for building AI-powered applications and agents with a modern TypeScript stack.”

• Install: npx skills add mastra-ai/skills via the Vercel installer, or npx skills add https://mastra.ai/ via the RFC 8615 .well-known URI mechanism.
• Spec compliance: a single skill named mastra, written to the open spec, with no Mastra-specific frontmatter additions.
• Progressive disclosure: the skill bundles separate reference files for setup, embedded docs lookup, remote docs lookup, troubleshooting, and migration — exactly the pattern the spec recommends.
• Stars: small (around 51 at last check), but Mastra’s Mastra Docs MCP server is the more-trafficked surface.

Vercel — the installer and the dissent

Vercel publishes two contradictory artifacts in the same quarter. vercel-labs/skills is the de facto cross-agent installer (16.9K stars, MIT, 90.5% TypeScript). The CLI, invoked as npx skills add <source>, supports six source formats: GitHub shorthand (owner/repo), full GitHub URL, direct path to a skill in a repo, GitLab URL, raw git URL, and local path. The README lists 50+ supported agent targets including OpenCode, Claude Code, Codex, Cursor, OpenHands, Cline, Continue, GitHub Copilot, Antigravity, Roo Code, Kiro CLI, Windsurf, Devin, Crush, Gemini CLI, Mistral Vibe, Qwen Code, and Tabnine CLI.

The installer’s contract is clean: each agent has a designated project path and a global path. The CLI symlinks rather than copies, so a single source-of-truth update propagates to every installed agent the next time it discovers skills. The only Vercel-specific frontmatter addition the CLI looks for is metadata.internal: true, which hides a skill from normal discovery unless INSTALL_INTERNAL_SKILLS=1 is set in the environment.

Then the same Vercel labs publishes the dissent. From Agents.md outperforms skills in our agent evals by Jude Gao: “With AGENTS.md, there’s no moment where the agent must decide ‘should I look this up?’ The information is already present. Skills load asynchronously and only when invoked. AGENTS.md content is in the system prompt for every turn.” Their Next.js 16 eval reported a 100% pass rate with an 8KB AGENTS.md doc index versus 79% for Skills with explicit instructions and 53% for Skills with default invocation.

Both can be true. We unpack the debate later in this post.

OpenCode and the long tail

OpenCode is the open-source coding agent that has been the fastest cross-vendor adopter of Skills outside the original Anthropic ecosystem. The Vercel installer’s opencode target points to an .opencode/skills/ project path; the rest of the contract is identical to Cursor and Codex.

Beyond OpenCode, the long tail handled by npx skills add covers GitHub Copilot CLI, Continue, Roo Code, Kiro CLI, Windsurf, Devin, Crush, Mistral Vibe, Qwen Code, and Tabnine CLI. None of these runtimes parse SKILL.md as a first-class primitive in the same way as Claude Code or Cursor — instead, they treat the skill folder as either a system-prompt fragment (loaded every turn, like AGENTS.md) or as a command they invoke explicitly. The Vercel installer normalizes the differences so the skill author doesn’t care; the runtime semantics still vary.

If you’re shipping a public skill, our advice is to target Claude Code, Cursor, Codex, Gemini CLI, and Cline explicitly (the six-agent core) and rely on the Vercel installer to cover the long tail. The marginal effort to test on Crush or Tabnine is rarely worth it for a skill that does its job in the canonical six.

The portability matrix

Every cell pulled from the agent’s own docs, with citations in the per-agent sections above. “Native read” means the agent parses SKILL.md directly without an installer. “Progressive disclosure” means the agent loads only the metadata until the skill activates. “Allowed-tools” is the experimental field in the spec; only Claude Code and Codex implement it as of May 2026.

Three observations from the matrix. Native support is the norm — six of the eight rows here read SKILL.md directly, which was not true six months ago. The path is the only real fragmentation — every agent has a different project path, and the only honest portability story is to rely on the Vercel installer or symlink. The experimental fields don’t actually portable — allowed-tools is parsed by two runtimes; Cursor’s paths by one. Don’t put security-relevant logic in fields that may be silently stripped.

What breaks across agents

Skill-author guidance: write once, run anywhere

Five practical rules we follow when shipping a skill that needs to work across the canonical six (Claude Code, Cursor, Codex, Cline, Antigravity, Gemini CLI):

1. Stick to name and description in the frontmatter. Optional fields are nice but vary in support; portability comes from minimalism. Add license and metadata for documentation, never for enforcement.
2. Lowercase, hyphenated name, matching the parent directory exactly. The spec validates this; Cline enforces it; the others assume it.
3. Description in the form “Verb noun. Use when X.” — a behavior verb plus a triggering condition. Antigravity, Codex, and Gemini CLI all warn that vague descriptions cause the agent to skip the skill at activation time. The Anthropic spec gives a good example: “Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.”
4. Keep the SKILL.md body under 500 lines. Move details to references/REFERENCE.md or references/FORMS.md. Progressive disclosure works only if the skill author cooperates with it.
5. Test on Linux for case sensitivity. On macOS the bug is invisible; on the Linux runners that ship the binaries to most users, a file named skill.md is a no-op. Add a CI step that does find skills -type f -name "[Ss][Kk][Ii][Ll][Ll].[Mm][Dd]" ! -name "SKILL.md" and fails the build on a hit.

Two patterns to actively avoid. Don’t use the allowed-tools field for security. Two of eight agents parse it; the others run the skill with whatever tools they grant by default. If you need enforcement, write the boundary in the runtime config, not in the skill. Don’t put per-agent logic inside the skill. Conditionals like “if Cursor, do X; if Claude, do Y” are an anti-pattern; the format is portable only because skill authors cooperate. If you genuinely need per-agent behavior, ship two skills and let each runtime install the right one.

Full Claude Skills Tutorial for Beginners in 2026

AI Foundations · click to play

The five cross-agent skill collections

Five repos cover most of the cross-agent skill universe. Each has a slightly different shape; star counts pulled at write time.

agentskills/agentskills — the spec (~17.8K stars, Apache-2.0). The reference. README opens: “Agent Skills are a simple, open format for giving agents new capabilities and expertise… an open format maintained by Anthropic and open to contributions from the community.” Houses the published spec and the skills-ref validator at skills-ref validate ./my-skill.

vercel-labs/skills — the installer (16.9K stars, MIT). README: “a CLI for installing skills across multiple agents” — supports “OpenCode, Claude Code, Codex, Cursor and 50+ other agents.” npx skills add <source> is the canonical cross-agent install gesture in 2026.

google/skills — Google Cloud (~6.5K stars, Apache-2.0). The first-party Google Cloud skill set. README lists “Gemini API in Agent Platform, AlloyDB Basics, BigQuery Basics, Cloud Run Basics, Cloud SQL Basics, Firebase Basics, Kubernetes Engine (GKE) Basics” plus Well-Architected Framework recipes. Install: npx skills add google/skills.

addyosmani/agent-skills — production engineering (~27.7K stars, MIT). Addy Osmani’s collection of 20 skills across six lifecycle phases — Define, Plan, Build, Verify, Review, Ship. The README’s pitch: “Process, not prose” — every skill is a step-by-step workflow with anti-rationalization tables and verification requirements. Documented setup for Claude Code, Cursor, Gemini CLI, Windsurf, OpenCode, GitHub Copilot, and Kiro IDE.

VoltAgent/awesome-agent-skills — the curated awesome list (~20.2K stars, MIT). README, verbatim: “Unlike many bulk-generated skill repositories, this collection focuses on real-world Agent Skills created and used by actual engineering teams, not mass AI-generated stuff.” 1100+ entries, organized by publishing org — Anthropic, Google, Stripe, Vercel, Cloudflare, Netlify, Trail of Bits, plus community.

Honourable mention: obra/superpowers (around 178K stars, MIT) ships “a complete software development methodology for your coding agents, built on top of a set of composable skills.” It’s the largest single skill set in the wild and has been part of the Anthropic Claude Code marketplace since January 2026.

The Vercel debate, with the counter-take

Vercel’s claim is direct and well-evidenced. From the same agent eval post: “Skills create sequencing decisions (read docs first vs. explore project first). Passive context avoids this entirely… In 56% of eval cases, the skill was never invoked. The agent had access to the documentation but didn’t use it.”

The honest counter-take. Vercel’s eval was on Next.js 16 — one framework, one model, one task type. Their conclusion is correct at that scale: when you have a single, well-bounded set of guidance to inject every turn, AGENTS.md dominates Skills. But the same approach doesn’t scale to dozens of skills. Anthropic shipped progressive disclosure precisely because AGENTS.md with 47 skills inlined would consume more context than the model has. Cloudflare’s Code Mode work and Anthropic’s Tool Search Tool exist for the same scaling reason — see our MCP Context Bloat Fix deep dive for the math.

Both can be right. Use AGENTS.md for the half- dozen pieces of guidance that apply to every turn in a given repo. Use Skills when you have a procedural library that grows past the point where every turn loading every procedure is affordable. Most production setups end up with both — a small AGENTS.md at the repo root and a .agents/skills/ folder for the long tail. Simon Willison’s framing on launch day still holds: Skills are not a replacement for anything else; they’re a new layer in the stack.

Frequently asked questions

Sources

The spec

• agentskills.io/specification — the canonical Agent Skills spec
• github.com/agentskills/agentskills — open spec repo, governance language, validator
• github.com/anthropics/skills — Anthropic-maintained reference set
• platform.claude.com/docs — Agent Skills overview
• anthropic.com/engineering — Agent Skills (Oct 16 2025)
• claude.com/blog/skills — Skills launch post

Per-agent docs

• cursor.com/changelog/2-4 — Cursor 2.4 Skills launch (Jan 22 2026)
• cursor.com/help/customization/skills — Cursor Skills paths and frontmatter
• developers.openai.com/codex/skills — Codex CLI Skills docs
• github.com/openai/codex — Codex CLI repo
• docs.cline.bot/features/skills — Cline Skills feature docs
• github.com/cline/cline — Cline repo
• antigravity.google/docs/skills — Antigravity Skills docs
• geminicli.com/docs/cli/skills — Gemini CLI Skills docs
• github.com/google-gemini/gemini-cli — Gemini CLI repo
• github.com/google-gemini/gemini-skills — Google’s Gemini API skills

Cross-agent collections

• vercel-labs/skills — the installer
• mastra-ai/skills — Mastra’s official skill
• google/skills — Google Cloud skill set
• addyosmani/agent-skills — Addy Osmani’s 20-skill production set
• VoltAgent/awesome-agent-skills — the awesome list
• obra/superpowers — methodology + skill set

The debate

• vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals
• simonwillison.net — Claude Skills (Oct 16 2025)
• Cross-Platform Agent Skills Guide — zazencodes

Internal links

• /blog/claude-skills-vs-mcp-vs-subagents-vs-cli-2026-decision-matrix
• /blog/mcp-context-bloat-fix-2026-tool-search-code-mode-progressive-disclosure
• /blog/what-are-claude-code-skills
• /blog/what-is-mcp
• /blog/context7-vs-deepwiki-vs-ref-vs-docfork-2026
• /blog/claude-codex-cli-skill-guide
• /skills/skill-creator
• /skills/vercel-react-native-skills
• /skills/claude-md-improver
• /skills/codex-cli
• /servers/codex-cli
• /servers/gemini-cli
• /servers/cursor-mcp-installer
• /servers/mastra-docs
• /skills — browse the directory