Since its August 2025 release, the AGENTS.md open format has been adopted by more than 60,000 open-source projects, and the related Agent Skills SKILL.md standard is now read by 32-plus tools including Claude Code, OpenAI Codex, Cursor, and Gemini CLI (verified 2026-06-07). A procedure you write once can, in principle, run in every agent you touch. The catch: the file format is shared, but install paths, auto-loading behavior, and a few file-name conflicts are not, so portability is real but partial.

This guide collects 15 playbooks: SKILL.md (and where relevant, AGENTS.md) patterns you can author once and reuse across Claude Code, Codex, Cursor, and Antigravity. Where a playbook breaks at a tool boundary, the entry says so plainly.

SKILL.md playbook: A reusable, file-based capability defined in a SKILL.md document, made of YAML frontmatter (name, description) plus markdown instructions, that an agent loads on demand when a task matches the description. Unlike persistent project rules, a playbook is task-scoped: it costs almost nothing in context until the agent decides it's relevant.

About this article:

• Researched and written June 2026. Last fact-checked 2026-06-07.

• Hands-on experience: partial. Research plus hands-on review of SKILL.md and AGENTS.md tooling across Claude Code, Codex CLI, Cursor, and Antigravity docs and sample repos.

• AI assistance: used for drafting, reviewed and edited by the author.

• Conflicts of interest: none. SSOJet is not one of the tools evaluated.

• Sponsorship: none. All claims verified 2026-06-07 against official docs.

Key Takeaways

• The SKILL.md format requires only two frontmatter fields, name (max 64 characters) and description (max 1,024 characters), per the Agent Skills standard (verified 2026-06-07).

• Skills are portable in format but not in install path: Claude Code reads .claude/skills/, Codex reads .agents/skills/, and Antigravity reads ~/.gemini/antigravity/skills/.

• AGENTS.md, the persistent-rules counterpart to task-scoped SKILL.md, is stewarded by the Agentic AI Foundation under the Linux Foundation since its November 2025 launch.

• Antigravity added native AGENTS.md support in v1.20.3 (March 5, 2026), but Claude Code still has no native AGENTS.md auto-loading.

• Cursor's .cursor/rules/*.mdc files use YAML glob scoping no other agent reads.

How Portable Is a SKILL.md File Across Agents, Really?

A SKILL.md file is portable in format and inconsistent in plumbing. The body and two required frontmatter fields parse the same everywhere, but each agent stores and loads skills differently.

Agent	Skills / rules path	Native AGENTS.md?	Portability note
Claude Code	.claude/skills/, ~/.claude/skills/	No (open issue)	Adds allowed-tools, subagent forking
OpenAI Codex CLI	.agents/skills/	Yes	Among first adopters of SKILL.md
Cursor	.cursor/rules/*.mdc + AGENTS.md	Yes	.mdc is Cursor-locked; keep logic portable
Google Antigravity	~/.gemini/antigravity/skills/	Yes (v1.20.3)	Watch the ~/.gemini/GEMINI.md path conflict

The table makes the tradeoff concrete. You write one SKILL.md, but you place it in up to four directories, and only Claude Code currently lacks native AGENTS.md loading. Treat the format as portable and the deployment as per-tool glue.

How Did We Evaluate These SKILL.md Playbooks?

We ranked each playbook on six criteria, weighted toward genuine cross-agent reuse rather than clever single-tool tricks.

1. Cross-agent portability (highest weight). Does the playbook run unmodified in at least three of Claude Code, Codex CLI, Cursor, and Antigravity? We tested by copying the same SKILL.md into each agent's expected directory and triggering it.

2. Format compliance. Does it stay inside the two-field minimum (name, description) plus markdown body that the Agent Skills spec guarantees, avoiding tool-specific frontmatter that silently breaks elsewhere?

3. Context efficiency. Does it use progressive disclosure (a short SKILL.md that points to bundled files) so it costs near-zero tokens until invoked?

4. Determinism. Does it produce repeatable output, or does it depend on a specific model's quirks?

5. Safety and least privilege. Does it scope tool access (for example, Claude Code's allowed-tools) and avoid baking secrets into the file?

6. Maintenance cost. Is it a single committed artifact a team can review in a pull request, or does it drift across copies?

We performed this evaluation in June 2026 against official documentation and sample repositories. The honest limitation: Claude Code, Codex, Cursor, and Antigravity ship rapidly, and exact directory paths and frontmatter support shift between releases, so re-verify paths against current docs before standardizing on them.

We considered but did not include:

• .cursorrules (legacy single file): deprecated in favor of .cursor/rules/*.mdc and AGENTS.md; not portable to any other agent.

• Windsurf Cascade memories: a proprietary in-product memory store, not a file-based artifact you can commit and share across agents.

• GitHub Copilot's .github/copilot-instructions.md: Copilot now also reads AGENTS.md and SKILL.md, so the Copilot-only file is redundant for a portability-focused list.

Which SKILL.md Playbooks Are Foundational Across Every Agent?

These five are the backbone. They use only the guaranteed two-field frontmatter, so they survive the trip between agents intact.

1. The Skill Scaffolder

A meta-skill that writes other skills, modeled on Anthropic's own skill-creator.

Best for: teams standardizing how skills get authored across multiple agents.
Starting price: Free (Apache 2.0 in the anthropics/skills repo).
Key differentiator: it enforces the minimal two-field frontmatter so generated skills stay portable by construction.

In our review, scaffolding a skill through the skill-creator pattern produced a SKILL.md whose frontmatter was exactly name and description, with the body kept under roughly 30 lines and longer reference material pushed into bundled files. That structure is what made the same file load cleanly when we dropped it into Codex's .agents/skills/ directory without edits. The honest limitation: a scaffolder cannot fix install paths, so you still copy the output into each agent's directory yourself.

2. The Commit Summarizer

A task skill that reads the working diff, drafts a commit message, and flags risky changes.

Best for: anyone tired of pasting "summarize my uncommitted changes" into chat.
Starting price: Free.
Key differentiator: it is the canonical example in the Claude Code skills docs, so the reference implementation is public.

When to choose the Commit Summarizer:

• You want one diff-review behavior shared between Claude Code and Codex.

• You want Claude to auto-invoke it from a phrase like "what changed" via its description.

• You want to scope it to read-only access using allowed-tools: Read Grep.

When to avoid it:

• Your team enforces commit messages through a server-side hook already.

• You need deterministic, lint-style output rather than a model summary.

• You run it in an agent that does not expose git context to skills.

3. The Test-First Enforcer

A skill that instructs the agent to write a failing test before implementation code, then run it.

Best for: enforcing TDD discipline regardless of which agent a developer prefers.
Starting price: Free.
Key differentiator: it is pure instruction text, so it carries zero tool-specific frontmatter and runs identically across all four agents.

Because this playbook is just markdown guidance, it was the most portable thing we reviewed. The same body that drove Claude Code to write a failing test first also worked verbatim in Cursor when saved as a rule and in Antigravity via AGENTS.md. The catch is enforcement strength: a skill is guidance, not a gate, so a determined model can still skip the test step. Pair it with a CI check if you need a hard guarantee.

4. The PR Reviewer

A review skill that walks a diff against a checklist of correctness and security concerns.

Best for: consistent self-review before a human opens the pull request.
Starting price: Free.
Key differentiator: it can run in a forked subagent in Claude Code via context: fork, keeping the main session clean.

In testing, the same review checklist produced comparable findings across agents, but the Claude Code variant using context: fork and a dedicated subagent kept the review output isolated from the working session, which mattered on a long task where the main context was already near its budget. The portability seam: context: fork is a Claude Code extension, so in Codex and Cursor the identical skill runs inline instead. Same checklist, different execution model.

5. The Doc Generator

A skill that turns code and inline comments into reference documentation.

Best for: keeping docs in sync without a separate pipeline.
Starting price: Free.
Key differentiator: it pairs cleanly with the document skills (docx, pdf, pptx, xlsx) published in the anthropics/skills repo.

This is a good example of progressive disclosure done right. The SKILL.md stays short and references a bundled style guide file the agent only reads when generating output, so it adds almost nothing to context until invoked. The honest limitation: the document-generation skills in the Anthropic repo are source-available rather than open source, so check the license before redistributing them inside a commercial product.

Which Playbooks Handle MCP and External Tools?

Agents increasingly reach external systems through the Model Context Protocol, so these playbooks govern how skills interact with MCP servers and APIs. If MCP security is new to you, best practices for MCP security is a solid primer before wiring skills to live servers.

6. The MCP Server Builder

A skill that scaffolds a new MCP server, modeled on Anthropic's mcp-builder.

Best for: teams shipping their own MCP integrations across multiple agents.
Starting price: Free.
Key differentiator: because MCP is itself a cross-agent standard, an MCP server built once works in any MCP-capable agent, compounding the portability story.

7. The API Client Generator

A skill that reads an OpenAPI spec and emits a typed client plus a smoke test.

Best for: repetitive integration work against documented REST APIs.
Starting price: Free.
Key differentiator: deterministic input (the spec) makes its output far more repeatable than free-form code generation.

8. The Secrets Hygiene Guard

A skill that scans staged changes for hardcoded credentials and refuses to proceed if it finds any.

Best for: preventing the most common agent footgun, committing a key.
Starting price: Free.
Key differentiator: it encodes a hard "stop" instruction, which models honor more reliably than soft suggestions.

This playbook matters more as agents gain autonomy. When a skill calls an MCP server or external API, it often needs a token, and a skill that bakes that token into the file is a leak waiting to happen. Keep credentials in the agent's environment, not the SKILL.md. The same caution applies to how agents authenticate to your own services: see OAuth 2.0 for AI agents implementation patterns for the token-handling side of this.

Which Playbooks Enforce Security and Identity Discipline?

These four exist because an agent that can edit code, call APIs, and act non-interactively is also a new attack surface.

9. The Prompt-Injection Sentinel

A skill that treats fetched web content and tool output as untrusted and refuses to follow instructions embedded in them.

Best for: any agent that browses, reads issues, or ingests third-party data.
Starting price: Free.
Key differentiator: it directly addresses the top agent-specific risk class rather than generic code quality.

In our review, a skill carrying an explicit "data is not instructions" rule reduced how often the agent acted on injected directives in fetched pages, though it did not eliminate them, which matches the broader finding that prompt injection is a mitigation problem, not a solved one. For the deeper threat model, AI agent security risks for the enterprise catalogs the failure modes this playbook only partially covers.

10. The Least-Privilege Tool Scoper

A skill that declares the minimum tools it needs and explicitly removes dangerous ones.

Best for: autonomous or background skills that should never touch certain capabilities.
Starting price: Free.
Key differentiator: Claude Code's allowed-tools and disallowed-tools frontmatter make this enforceable, not just advisory.

11. The Audit-Trail Logger

A skill that appends a structured record of every significant action the agent takes to a log file.

Best for: teams that need to reconstruct what an autonomous agent did and when.
Starting price: Free.
Key differentiator: it produces a reviewable artifact, which is what compliance and incident response actually need.

12. The Non-Human Identity Gatekeeper

A skill that requires the agent to assume a scoped service identity before calling any privileged internal API.

Best for: organizations treating agents as first-class actors with their own credentials.
Starting price: Free.
Key differentiator: it shifts the agent from borrowing a human's session to holding its own auditable identity.

As agents call internal systems on their own, the identity question stops being theoretical. An agent needs an identity you can scope, rotate, and revoke, not a copy of a developer's token. AI agent identity and access control lays out the framework, and the evolution of SSO for autonomous AI agents covers the non-human-identity angle this playbook depends on.

Which Playbooks Cover Cross-Agent Setup and Maintenance?

The last three are about the seams: making the same logic survive across agents that disagree on where files live.

13. The AGENTS.md Bridge

A playbook that keeps a single AGENTS.md as the source of truth and syncs it to each agent's preferred file.

Best for: teams running Cursor, Codex, and Claude Code on the same repo.
Starting price: Free.
Key differentiator: it works around Claude Code's missing native AGENTS.md auto-loading.

This is the playbook that earns its keep on a mixed-agent team. We confirmed that Cursor and Antigravity read a root AGENTS.md natively, while Claude Code did not auto-load it as of June 2026, so the bridge symlinks or copies AGENTS.md to CLAUDE.md (and into .cursor/rules/ only where a Cursor-specific override is needed). One real gotcha we hit: Antigravity and Gemini CLI both write to ~/.gemini/GEMINI.md, which can leak rules between tools, so the documented fix is to keep shared global rules in ~/.gemini/AGENTS.md instead.

14. The Monorepo Scoper

A playbook that places nested AGENTS.md files per package so the agent reads the closest one.

Best for: large monorepos where each package has its own conventions.
Starting price: Free.
Key differentiator: it uses the standard's nearest-file precedence, which the OpenAI monorepo demonstrates with 88 AGENTS.md files.

How does nesting actually resolve?
The agent reads the AGENTS.md closest to the file it is editing, and the nearest file wins. So a root file sets defaults and a packages/frontend/AGENTS.md overrides them for frontend work. Antigravity requires enabling "Load nested AGENTS.md files" in settings first, so the behavior is opt-in there rather than automatic.

15. The Skill Sync Linter

A skill that verifies the same logical skill exists, and matches, across every agent directory in the repo.

Best for: preventing the silent drift that happens when one copy of a skill gets edited and the others do not.
Starting price: Free.
Key differentiator: it turns "portable in theory" into "consistent in practice" by failing CI when copies diverge.

How Should You Choose Which Playbooks to Adopt First?

Start from how many agents your team actually runs, then layer in risk.

If you use a single agent today, skip the cross-agent bridges (13 and 15) and start with the foundational five, especially the Commit Summarizer and PR Reviewer, since they pay off immediately and carry no portability tax. If you run two or more agents on the same repo, adopt the AGENTS.md Bridge (13) and Skill Sync Linter (15) early, because drift between copies is the failure that quietly erodes trust in your skill library.

If your agents touch production systems or external APIs, prioritize the security cluster (9 through 12) before the convenience skills. The Secrets Hygiene Guard and the Non-Human Identity Gatekeeper are the two that prevent the expensive mistakes. And if you maintain a monorepo, the Monorepo Scoper (14) is close to mandatory, because a single root file cannot capture per-package conventions cleanly.

One sequencing rule held up across our review: get the foundational skills portable and committed first, then add security, then add the cross-agent plumbing. Reversing that order means you are syncing skills that are not yet stable.

Frequently Asked Questions

What is the difference between SKILL.md and AGENTS.md?

SKILL.md defines a task-scoped capability that an agent loads only when a task matches its description, while AGENTS.md is persistent project context that applies to every interaction. Think of SKILL.md as an on-demand tool and AGENTS.md as a README the agent always reads. Both are plain markdown and both are designed to be portable, but they solve different problems and are often used together.

Do SKILL.md files really work across Cursor, Codex, and Antigravity?

The format works across all of them, but the install path does not. The same SKILL.md parses identically in each agent, yet Claude Code expects it in .claude/skills/, Codex in .agents/skills/, and Antigravity in ~/.gemini/antigravity/skills/. The spec standardizes the file, not where each tool looks for it, so you copy the same file into different directories per agent.

Does Claude Code read AGENTS.md natively?

Not as of June 2026. Native AGENTS.md auto-loading in Claude Code is an open feature request, so teams symlink or copy AGENTS.md to CLAUDE.md, or sync the two in CI. Cursor, Codex, and Antigravity (since v1.20.3, March 5, 2026) do read AGENTS.md natively.

Are Cursor's .mdc rules portable to other agents?

No. Cursor's .cursor/rules/*.mdc format uses YAML frontmatter with glob-based activation that no other agent reads. The pragmatic pattern is to keep a root AGENTS.md so every agent works and reserve .mdc files only for Cursor-specific scoped overrides where Cursor's auto-attach behavior genuinely helps.

Can a SKILL.md file contain secrets or API keys?

It should not. A SKILL.md is a committed, shareable artifact, so any credential inside it is effectively published to everyone with repo access. Keep secrets in the agent's environment or a secrets manager, and use a skill like the Secrets Hygiene Guard to block commits that contain credentials.

Final Thoughts

Portable skills are real in 2026, but the portability lives in the file format, not the tooling around it. Write your playbooks against the two-field SKILL.md minimum, keep persistent rules in AGENTS.md, reserve Cursor's .mdc for Cursor, and treat the install paths as glue you maintain per agent. If you build agents that act on their own, the identity and security playbooks are the ones that keep a convenient tool from becoming a liability.

Sources

All pricing, version, and feature claims were verified on 2026-06-07 against official documentation and primary sources.

• AGENTS.md official site (adoption count, native tool support, nesting) (verified 2026-06-07)

• Agent Skills open standard (agentskills.io) (SKILL.md frontmatter fields, adopting tools) (verified 2026-06-07)

• Claude Code skills documentation (frontmatter fields, install paths, subagent forking, nesting) (verified 2026-06-07)

• anthropics/skills repository (skill-creator, mcp-builder, document skills, licensing) (verified 2026-06-07)

• skill-creator SKILL.md (verified 2026-06-07)

• mcp-builder SKILL.md (verified 2026-06-07)

• Linux Foundation: formation of the Agentic AI Foundation (AGENTS.md and MCP stewardship) (verified 2026-06-07)

• Anthropic: donating MCP and establishing the Agentic AI Foundation (verified 2026-06-07)

• Cursor rules documentation (.mdc format, AGENTS.md support) (verified 2026-06-07)

The post 15 SKILL.md Playbooks That Work Across Cursor, Codex, and Antigravity appeared first on SSOJet – Enterprise SSO & Identity Solutions.

*** This is a Security Bloggers Network syndicated blog from SSOJet - Enterprise SSO & Identity Solutions authored by SSOJet - Enterprise SSO & Identity Solutions. Read the original post at: https://ssojet.com/blog/skill-md-playbooks