Cross-Agent Skill Development: Why Agent Skills Are the New npm

The npm Analogy Is Not a Metaphor Anymore

In December 2025, Anthropic released the Agent Skills specification as an open standard. By January 2026, OpenAI adopted it for Codex CLI. Google shipped native support in Gemini CLI. GitHub wired it into Copilot. By March 2026, the ecosystem crossed 351,000 published skills across three marketplaces, with tools like skillpm and skills-npm bridging agent skills directly into the npm registry.

The "skills are the new npm" line started as a convenient analogy. A SKILL.md file gives an AI agent reusable knowledge the way an npm package gives an application reusable code. But the analogy has become literal infrastructure. Anthony Fu's skills-npm discovers agent skills shipped inside npm packages and symlinks them for your coding agent. skillpm goes further — it maps Agent Skills onto npm's package.json, node_modules, registry, and semver resolution. Skills are npm packages now. You publish them, install them, version them, and declare dependencies between them.

This article covers the cross-agent compatibility story: how one SKILL.md works across every major coding agent, where each tool expects to find skills, what breaks when you move between agents, and where the ecosystem still falls short of real npm. If you are new to agent skills entirely, start with the Agent Skills Complete Guide. If you want to build your first skill, the step-by-step tutorial is faster.

One Format, Six Agents

The SKILL.md format is deliberately simple: YAML frontmatter with name and description, followed by a Markdown body containing instructions. This simplicity is the reason it works across agents. There is no agent-specific API, no compiled binary, no runtime dependency. A skill is a directory with a text file in it. Any agent that can read Markdown can consume it.

As of March 2026, six major coding agents support the SKILL.md format natively:

The compatibility matrix below summarizes which agents read which directory conventions and which frontmatter fields they support.

Key takeaway from this table: Every agent reads .agents/skills/ as a fallback. That directory is the universal bus. If you author skills for cross-agent use, put them there.

Claude Code has the richest feature set — allowed-tools for sandboxing, disable-model-invocation for manual-only triggers, and multi-level skill loading (personal, project, marketplace). Codex CLI supports allowed-tools partially. The rest read name, description, and the Markdown body. For cross-agent skills, the lowest common denominator is all you need.

Directory Conventions: The Fragmentation Problem

Every agent created its own dotfile directory. This is the one area where the "open standard" story breaks down.

.claude/skills/       # Claude Code
.agents/skills/       # Codex CLI, universal fallback
.github/skills/       # GitHub Copilot
.gemini/skills/       # Gemini CLI
.codex/skills/        # Codex CLI (alternative)
.opencode/skills/     # OpenCode
.cursor/skills/       # Cursor

Seven directories for one format. If you want a skill to be discoverable by every tool your team uses, you have three options:

Option 1: Symlinks (Simple, Works Now)

Put your skills in a canonical location and symlink to each agent's expected path:

# Canonical location
mkdir -p .skills/code-review

# Symlinks for each agent
ln -s ../.skills .claude/skills
ln -s ../.skills .agents/skills
ln -s ../.skills .github/skills
ln -s ../.skills .gemini/skills

This is the approach recommended in the Agent Skills Guide. It works, it is simple, and it costs you four lines in your project setup script. The downside: symlinks are fragile on Windows (requires developer mode or admin privileges), and some CI environments do not follow them.

Option 2: Target .agents/skills/ Only

If you accept that not every agent will find your skills through its primary path, .agents/skills/ is the strongest single choice. Every agent on the compatibility matrix above reads it as a fallback. Codex CLI reads it as its primary path. Claude Code and Gemini CLI both discover it. This is one directory, no symlinks, works on every OS.

The trade-off: Claude Code users who run claude skill list will not see skills in .agents/skills/ in the default output. They exist and they load, but the discovery UX is worse than using .claude/skills/ directly.

Option 3: The agent-skill-creator Approach

FrancyJGLisboa's agent-skill-creator tool generates a single SKILL.md and distributes it to 14+ agent directories automatically. It reads your skill definition once and writes the files wherever each tool expects them. This is the "write once, deploy everywhere" approach. The downside: it introduces a build step, and now your skill has a dependency on a distribution tool.

My recommendation: use .agents/skills/ as your primary directory. Add a symlink from .claude/skills/ if your team is Claude Code-heavy. Skip the rest unless a team member specifically needs Gemini CLI or Copilot discovery through the primary path.

Writing Truly Cross-Agent Skills

A skill that works on one agent and breaks on another is not a cross-agent skill. Here are the rules for writing skills that work everywhere.

Rule 1: Stick to Core Frontmatter

The cross-agent safe frontmatter fields are:

---
name: deploy-staging
description: >
  Deploy the current branch to the staging environment.
  Use when the user asks to deploy, push to staging, or
  test changes in a staging environment.
---

name and description are universal. Every agent reads them. Stop there for cross-agent skills. Do not use allowed-tools (Claude Code / OpenCode only), disable-model-invocation (Claude Code only), or any other agent-specific extension. If you need access control, document it in the Markdown body as a convention rather than enforcing it through frontmatter.

Rule 2: No Agent-Specific Tool Names

Claude Code tools are named Bash, Read, Edit, Write. Codex CLI uses different internal tool names. Gemini CLI has its own set. If your skill body says "use the Edit tool to modify the file," that instruction makes sense to Claude Code but is meaningless to Gemini CLI.

Write instructions in terms of outcomes, not tools:

## Bad (agent-specific)
Use the `Bash` tool to run the test suite.
Use the `Edit` tool to update the config file.

## Good (agent-agnostic)
Run the test suite: `pnpm test`
Update the config file at `src/config.ts` with the new values.

The agent knows how to run shell commands and edit files. It does not need you to name the internal tool. Describe what you want done, not which API to call.

Rule 3: Use Relative Paths from Project Root

Skills that reference ~/.claude/skills/my-skill/references/guide.md break on Codex CLI because the skill lives in .agents/skills/ there. Reference files relative to the skill directory:

Read the deployment checklist in `./references/deploy-checklist.md`.

Or relative to the project root:

Read the API schema at `src/schemas/api.yaml`.

Never use absolute paths. Never reference the agent's config directory structure.

Rule 4: Test on Two Agents Minimum

The fastest way to catch cross-agent issues is to test on Claude Code and one other agent. Claude Code has the most features — if something works there, it usually works everywhere. But features like allowed-tools silently degrade on other agents, and you will not notice until a Codex CLI user reports that the skill executed a shell command it should not have.

A two-agent test takes five minutes: invoke the skill via slash command on both agents, verify the same behavior, done.

The Marketplace Ecosystem

Three marketplaces serve the skills ecosystem. They differ in philosophy, not format.

The marketplace comparison below shows the scale and focus of each platform.

SkillsMP is the volume leader. It crawls GitHub repositories for SKILL.md files and indexes them with AI-powered semantic search. The catalog spans 89K tools skills, 70K development skills, and 60K business skills. The number is impressive; the signal-to-noise ratio is not. There is no security scanning. There is no install mechanism. It is a discovery platform — find the skill, read the SKILL.md on GitHub, copy it manually.

Skills.sh is Vercel's answer. Launched January 20, 2026, it reached 20,000 installs within six hours. Stripe, Prisma, Supabase, Coinbase, and Remotion all shipped official skills before Q1 ended. Skills.sh differentiates through a CLI-native install experience, integrated Snyk security scanning, and actual install count tracking. When top skills like vercel-react-best-practices show 100K+ installs, that number means something.

ClawHub is the cautionary tale turned redemption story. It suffered the ClawHavoc malware campaign — 341 malicious skills distributing Atomic macOS Stealer — but responded with mandatory scanning and became the most curated marketplace. At ~3,200 skills with proper versioning and rollback support, it is the smallest but highest signal.

The fragmentation across three marketplaces is the clearest sign that the ecosystem has not reached npm's maturity. npm is one registry. Skills have three, and none of them provide the full npm install experience on their own.

Versioning and Distribution: Where It Gets Real

npm solved versioning in 2012 with semver, package-lock.json, and a centralized registry. The skills ecosystem is re-solving these problems from scratch, fourteen years later.

The Current State

Skills have no built-in versioning. A SKILL.md file is a text file in a directory. It has no version field in the core spec. When SkillsMP crawls your GitHub repo, it gets whatever is on the default branch. When Skills.sh installs a skill, it copies the current version. There is no lock file. There is no way to pin a version. There is no way to roll back.

Community solutions are emerging:

skill-semver adds automatic version control to Claude Code skills — MAJOR.MINOR.PATCH format, auto-backup on every edit, changelog tracking. It is a skill that manages other skills. Clever, but it solves the problem at the wrong layer. Versioning should be in the registry, not in userspace.

skillpm is the most promising approach. It maps Agent Skills onto npm's package.json and node_modules. Skills become npm packages with semver, dependency resolution, lockfiles, and audit — all handled by npm itself. skillpm only adds what npm cannot do on its own: scanning node_modules for packages containing skills/*/SKILL.md and wiring them into agent directories.

skills-npm by Anthony Fu takes a lighter approach. It discovers agent skills shipped inside npm packages and creates symlinks for coding agents. Add it as a prepare script in package.json and skills symlink automatically when you run npm install. No new package manager, no new registry — just a discovery layer on top of npm.

The Dependency Problem

npm packages can depend on each other. Skills cannot — not natively. A "deploy to AWS" skill that needs a "run tests" skill and an "update changelog" skill has to inline the instructions from all three. This is the prompt bloat problem that skillpm solves: because skills become npm packages, they can declare dependencies, and the agent loads only what it needs.

Without dependency resolution, the skills ecosystem encourages monolithic skills. A single SKILL.md that tries to handle deployment, testing, and changelog generation because there is no way to compose smaller skills. This is exactly the pre-npm era of JavaScript: copy the library source code into your project because there is no dependency manager.

What Is Missing vs Real npm

The "skills are the new npm" narrative is compelling but incomplete. Here is an honest comparison of what the skills ecosystem has and what it still lacks.

The gap analysis below compares the skills ecosystem maturity against npm's feature set.

The critical gaps are registry fragmentation and security. npm has one registry. Skills have three, and a skill on SkillsMP may not exist on Skills.sh or ClawHub. npm has npm audit backed by multiple vulnerability databases. Skills had 13.4% critical-issue rate in the Snyk ToxicSkills study — and that was on the 3,984 skills they managed to scan out of 351K.

The moderate gaps — namespaces, publish workflows, deprecation — are solvable and being actively worked on. The critical gaps will define whether "skills are the new npm" becomes reality or remains marketing copy.

The Cross-Agent Skill Authoring Checklist

If you are publishing a skill intended for multi-agent use, run through this list before publishing:

1. Use .agents/skills/ as the primary directory. Symlink to .claude/skills/ if needed.
2. Frontmatter: name and description only. No agent-specific fields unless you document the degradation behavior on other agents.
3. Write instructions as outcomes, not tool calls. "Run pnpm test" not "Use the Bash tool to run tests."
4. Relative paths only. Reference files relative to the skill directory or the project root.
5. Test on Claude Code + one other agent. Codex CLI is the easiest second target.
6. Keep SKILL.md under 500 lines. Use references/ for long content.
7. Include a scripts/ directory for deterministic tasks. Every agent can execute bash scripts.
8. Document which agents you tested on. A simple "Tested on: Claude Code, Codex CLI, Gemini CLI" in the SKILL.md body sets expectations.
9. Avoid conditional logic based on agent detection. If you find yourself writing "if Claude Code, do X; if Codex, do Y," you are fighting the abstraction. Write one instruction that works everywhere.
10. Pin your marketplace versions. If publishing to Skills.sh, use the built-in versioning. If distributing via npm with skillpm, use semver.

For the design principles behind writing effective skills — description optimization, progressive disclosure, eval loops — the skill design principles guide covers the craft side. This checklist covers the distribution side.

Where This Is Heading

The skills ecosystem is roughly where npm was in 2011. The format is standardized. Multiple registries compete. Distribution tooling is fragmented but functional. The community is producing volume but not yet quality. Security is the open wound.

Three predictions:

Registry consolidation. One marketplace will win. Skills.sh has the best position — Vercel backing, Snyk security integration, actual install metrics. SkillsMP has volume but no install mechanism. ClawHub has curation but trust damage. Within 12 months, expect one dominant registry with the others as mirrors or niche alternatives.

npm convergence. skillpm and skills-npm are pointing the way. Skills will become npm packages with agent-specific metadata. The separate skill registries will either integrate with npm or lose to packages that publish to npm directly. The JavaScript ecosystem already solved package distribution. Re-solving it for a text format that sits in the same repos as JavaScript code is a waste of everyone's time.

Agent-side standardization. The directory fragmentation is unsustainable. Agents will converge on .agents/skills/ as the primary path, not just a fallback. The OpenAI and Google adoption of this convention as a primary path — not just fallback — makes this likely. Claude Code already reads it. The only question is when it becomes the documented default rather than a footnote.

The developers building cross-agent skills today are the equivalent of npm package authors in 2012. The ecosystem is messy, the tooling is incomplete, and the conventions are still forming. That is exactly when it pays to show up and shape the standard rather than wait for it to stabilize.

Understanding the differences between SKILL.md, CLAUDE.md, and AGENTS.md is the foundation for getting the layering right. Once you have that, building cross-agent skills is straightforward — the format is the same everywhere, and the directory problem has workable solutions today.