Is SKILL.md a real cross-tool standard now?

Yes. Anthropic introduced the concept and agentskills.io now documents it as an open format for portable agent capabilities. The file format is converging faster than the install paths.

Which tools have verified native support?

Claude Code has native support in official docs. Codex has native support in official docs. Goose also has official docs for Agent Skills and recommends .agents/skills as the standard path. For other tools, check their own docs before assuming native discovery.

Why do people still use symlinks if the format is portable?

Because portability of file format is not the same as portability of discovery path. Claude Code looks in .claude/skills. Codex and Goose prefer .agents/skills. A symlink or installer keeps one skill source while satisfying multiple clients.

What is the minimum portable SKILL.md frontmatter?

At minimum, name and description. Anything beyond that may be useful, but the more tool-specific metadata you add, the less portable the skill becomes.

Can the same scripts folder work across tools?

Yes, if the scripts use tools that exist in every target environment and the instructions explain when to run them. Cross-tool problems usually come from runtime assumptions, not from the SKILL.md file itself.

Should I author in .claude/skills or .agents/skills?

If portability is the goal, .agents/skills is the cleaner neutral home because Codex and Goose document it directly. Claude Code then becomes the tool that usually needs the mirror or symlink.

SKILL.md across tools: what is real, what is portable, what still needs glue

SKILL.md is now a real portable format, but "portable" still means "same folder structure, different discovery paths."

That distinction matters. Anthropic's skills work established the shape: a folder with SKILL.md, optional scripts, references, and assets, loaded progressively so the agent sees only the short description first and the full body only when the task matches (Anthropic engineering post). The open standard documentation at agentskills.io now describes the same folder-based format in neutral terms. OpenAI's Codex docs and Anthropic's Claude Code docs both document SKILL.md as a first-class feature (OpenAI Codex skills docs, Claude Code skills docs).

So yes, the standard is real. What is not standardized yet is where each tool looks for those folders, what extra metadata each tool cares about, and how much tool-specific behavior you can sneak into one supposedly portable skill before it stops being portable.

What the shared format actually is

The common denominator is smaller than people think:

one directory per skill
one required SKILL.md
minimal frontmatter with at least name and description
optional supporting files such as scripts, references, and templates

Anthropic's public explanation is straightforward: skills are a way to package expertise and workflows into folders that an agent can discover, then load on demand (Anthropic engineering post). The standard site says the same thing in more neutral language and explicitly frames it as cross-product reuse (Agent Skills overview). OpenAI's Codex docs are also aligned: Codex can invoke a skill implicitly when the description matches or explicitly when the user names it, and a skill is authored as a folder with SKILL.md plus optional extras (OpenAI Codex skills docs).

That is the important part. The emerging standard is not "a vendor-specific plugin manifest." It is "a folder with plain text instructions and optional local resources."

Verified native support: Claude Code

Claude Code is the easiest one to verify because Anthropic documents it directly. Skills can live in:

~/.claude/skills//SKILL.md for personal use
.claude/skills//SKILL.md for project use
plugin-provided skill locations when a plugin is enabled

Anthropic also documents live change detection and nested discovery, which matters in monorepos (Claude Code skills docs). The agent loads only enough metadata to know when the skill is relevant, then reads the rest when it fires. Anthropic's engineering post explains the context-window reason for this design: the short description rides in the system prompt, while the detailed instructions load only after activation (Anthropic engineering post).

That combination makes Claude Code the original and still most fully documented SKILL.md runtime.

Verified native support: Codex

Codex also documents skills directly, but its path conventions differ. Codex reads skills from repository, user, admin, and system locations. At the repo level, it scans .agents/skills from the current working directory up to the repo root. At the user level, it reads $HOME/.agents/skills. It also explicitly supports symlinked skill folders (OpenAI Codex skills docs).

That detail changes how you should author portable skills. If you were assuming the Claude path layout was universal, it is not. Codex prefers a neutral .agents/skills directory instead of .claude/skills.

Codex also confirms the same discovery pattern at the behavior level: explicit invocation by name or implicit invocation when the description matches (OpenAI Codex skills docs). In other words, the description field is not documentation fluff. It is part of the runtime surface.

Verified bridge support: Goose

Goose is important because its docs describe the portability story in a way the other vendors mostly imply. Goose recommends:

~/.agents/skills/ for global skills
.agents/skills/ for project-level skills

and then states that it also discovers .claude/skills/, ~/.claude/skills/, and some older locations for backward compatibility (Goose Using Skills docs).

That makes Goose the clearest public bridge client today. It is not just consuming the format; it is documenting both the neutral standard path and the backward-compatible vendor paths. If you want one sentence that describes where the ecosystem is heading, it is this one from the Goose docs: use .agents/skills as the standard, but expect legacy paths to remain around for a while.

So which tools need a symlink?

This is where people overcomplicate the story.

The SKILL.md file itself does not need a symlink. The directory layout often does.

If your canonical project path is .agents/skills, Claude Code is the tool that usually needs help, because its documented project path is .claude/skills (Claude Code skills docs). If your canonical path is .claude/skills, Codex is the tool that usually needs help, because its documented path is .agents/skills (OpenAI Codex skills docs).

That leaves you with three sane strategies:

Keep the canonical source in a neutral directory outside both runtimes and install into each runtime path.
Keep the canonical source in .agents/skills and mirror or symlink into .claude/skills.
Keep the canonical source in .claude/skills and mirror or symlink into .agents/skills.

For a genuinely multi-tool repo, option 2 is the cleanest today because both Codex and Goose already document .agents/skills as the preferred standard path (OpenAI Codex skills docs, Goose Using Skills docs).

How to write skills that stay portable

Portability dies from extras, not from the core format. The trap is loading your skill with features that only one client understands.

The rules that travel well are simple.

Keep frontmatter minimal

If name and description are enough, stop there. Codex adds optional metadata like agents/openai.yaml for UI and policy hints (OpenAI Codex skills docs). Those are useful inside Codex. They are not part of the universal core. Treat them as optional overlays, not the skill itself.

Write the description like a trigger surface

Both Claude-style and Codex-style skill systems rely on the description for implicit activation. Anthropic explains that only short skill metadata is present until the skill is activated (Anthropic engineering post). Codex explicitly says implicit matching depends on the description and recommends clear scope and trigger words (OpenAI Codex skills docs).

If your description is vague, the skill is portable only in theory.

Make scripts optional, not foundational

If a skill only works when a very specific shell tool exists, or when a local binary is installed at one path on one operating system, you no longer have a portable skill. You have a portable instruction file wrapped around a non-portable runtime.

The better pattern is:

keep the core logic in instructions
keep scripts small
document prerequisites plainly
offer fallbacks when possible

Avoid hidden repo assumptions

A portable skill should say where it expects to run, what directories it assumes exist, and what it will change. Claude Code, Codex, and Goose all support file-based skills, but they do not all share the same repo layout conventions. If your skill assumes src/ and tests/ exist, say so.

Test in at least two clients

A skill is not portable because it validates in one harness. It is portable when its description activates correctly, its instructions make sense, and any bundled scripts survive in more than one target client. Codex and Claude can both discover skills implicitly; Goose can bridge the same layout (OpenAI Codex skills docs, Claude Code skills docs, Goose Using Skills docs).

Until you run that test, "cross-tool" is still a theory.

Where this fails

The standard is ahead of the ecosystem. The file format is converging faster than discovery rules, installers, marketplaces, and tooling conventions.

Tool-specific metadata is the second fault line. The moment you depend on one client's extra fields, UI metadata, or permission model, your "portable" skill becomes partially portable.

The third failure mode is security. Skills can bundle scripts and instructions that tell an agent to execute those scripts. Anthropic's own write-up warns that malicious skills can introduce vulnerabilities or exfiltration paths if you install them casually (Anthropic engineering post).

Sources

Anthropic. Equipping agents for the real world with Agent Skills
Anthropic. Extend Claude with skills
OpenAI. Agent Skills for Codex
Agent Skills. Agent Skills overview
Goose. Using Skills
Goose. Skills Extension