Cross-Agent Skills: Why They're 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, 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. New to agent skills entirely? Start with the Agent Skills Complete Guide. 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 of instructions. This simplicity is why it works across agents. No agent-specific API. No compiled binary. No runtime dependency. A skill is a directory with a text file. Any agent that reads Markdown consumes it.

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

Compatibility matrix:

Check the actual loading paths. The table is a March 2026 snapshot; paths and supported fields can change. Do not assume every tool reads .agents/skills/. Check each tool's current documentation and test loading in a fresh session.

In Claude Code, allowed-tools pre-approves listed tools for the invoking turn; it is not a sandbox and does not block unlisted tools. disable-model-invocation controls automatic invocation. Other tools can interpret fields differently, so check each one. Actual access restrictions require permissions and appropriate isolation.

Directory Conventions: The Fragmentation Problem

Every agent created its own dotfile directory. 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. Three options for cross-tool discoverability:

Option 1: Symlinks (Simple, Works Now)

Canonical location plus symlinks:

# 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

Recommended in the Agent Skills Guide. Works, simple, four lines in your setup script. Downside: symlinks are fragile on Windows and some CI environments skip them.

Option 2: Target .agents/skills/ Only

If you accept that not every agent finds skills through its primary path, .agents/skills/ is the strongest single choice. Every agent reads it as fallback. Codex CLI reads it as primary. Claude Code and Gemini CLI discover it. One directory, no symlinks, every OS.

Trade-off: Claude Code's claude skill list will not show skills in .agents/skills/ in default output. They exist and load, but discovery UX is worse than .claude/skills/ directly.

Option 3: The agent-skill-creator Approach

FrancyJGLisboa's agent-skill-creator generates a SKILL.md and distributes to 14+ agent directories automatically. Write once, deploy everywhere. Downside: introduces a build step and a tool dependency.

Recommendation: .agents/skills/ as primary. Symlink from .claude/skills/ if team is Claude Code-heavy. Skip the rest unless someone specifically needs Gemini CLI or Copilot primary path discovery.

Writing Truly Cross-Agent Skills

A skill that works on one agent and breaks on another is not cross-agent. The rules:

Rule 1: Stick to Core Frontmatter

Cross-agent safe fields:

---
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.
---

For cross-tool skills, start with standard fields such as name and description, then verify each tool's supported extensions. The body can describe operating limits but is not enforced access control; use each tool's permissions and a sandbox when needed.

Rule 2: No Agent-Specific Tool Names

Claude Code tools: Bash, Read, Edit, Write. Codex CLI uses different names. Gemini CLI has its own set. "Use the Edit tool to modify the file" makes sense to Claude Code, means nothing to Gemini CLI.

Write instructions as 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 commands and edit files. Describe what, not which API.

Rule 3: Use Relative Paths from Project Root

Skills referencing ~/.claude/skills/my-skill/references/guide.md break on Codex CLI where the skill lives in .agents/skills/. Reference relative to skill directory:

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

Or relative to project root:

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

Never absolute paths. Never agent config directory structure.

Rule 4: Test on Two Agents Minimum

Test loading and output in at least two tools you actually use, with the same positive and negative prompts. Fields can be ignored or interpreted differently; success on one tool does not prove another behaves the same. Test permission behavior in an isolated environment.

Record both tool versions, the actual skill paths, whether each loaded, and the results. Time depends on the task and setup.

The Marketplace Ecosystem

Three marketplaces, different philosophies, same format.

SkillsMP is volume leader. Crawls GitHub for SKILL.md, indexes with semantic search. 89K tools, 70K development, 60K business. Impressive number, unimpressive signal-to-noise. No security scanning. No install mechanism. Discovery platform only.

Skills.sh is Vercel's answer. Launched January 20, 2026. 20,000 installs in six hours. Stripe, Prisma, Supabase, Coinbase, Remotion all shipped official skills before Q1 ended. Differentiates through CLI install, Snyk scanning, actual install tracking. When vercel-react-best-practices shows 100K+ installs, that number means something.

ClawHub is cautionary tale turned redemption. ClawHavoc malware campaign -- 341 malicious skills, Atomic macOS Stealer -- but responded with mandatory scanning. At ~3,200 skills with versioning and rollback, smallest but highest signal.

Three marketplaces: the clearest sign the ecosystem has not reached npm maturity. npm is one registry. Skills have three, none providing the full npm install experience alone.

Versioning and Distribution: Where It Gets Real

npm solved versioning in 2012 with semver, package-lock.json, centralized registry. Skills are re-solving these problems from scratch, fourteen years later.

Current State

No built-in versioning. SKILL.md is a text file in a directory. No version field in core spec. SkillsMP crawls default branch. Skills.sh copies current version. No lock file. No version pinning. No rollback.

Community solutions emerging:

skill-semver adds auto version control -- MAJOR.MINOR.PATCH, backup on edit, changelog tracking. A skill managing other skills. Clever, but wrong layer. Versioning should be in the registry.

skillpm is most promising. Maps Agent Skills onto npm's package.json and node_modules. Skills become npm packages with semver, dependency resolution, lockfiles, audit -- handled by npm. skillpm adds only what npm cannot: scanning node_modules for skills/*/SKILL.md and wiring into agent directories.

skills-npm by Anthony Fu is lighter. Discovers agent skills in npm packages, creates symlinks. Add as prepare script in package.json -- skills symlink on npm install. No new package manager, no new registry. Discovery layer on top of npm.

The Dependency Problem

npm packages depend on each other. Skills cannot -- not natively. A "deploy to AWS" skill needing "run tests" and "update changelog" must inline all three. This is the prompt bloat skillpm solves: skills as npm packages can declare dependencies, agent loads only what is needed.

Without dependency resolution, the ecosystem encourages monolithic skills. One SKILL.md handling deployment, testing, and changelog because there is no way to compose smaller ones. Pre-npm JavaScript: copy library source 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. Honest comparison:

Critical gaps: registry fragmentation and security. npm has one registry. Skills have three -- a skill on SkillsMP may not exist on Skills.sh. npm has npm audit backed by vulnerability databases. Skills had 13.4% critical rate in ToxicSkills -- on only 3,984 of 351K scanned.

Moderate gaps (namespaces, publish workflows, deprecation) are solvable and actively worked on. Critical gaps define whether "skills are the new npm" becomes reality or remains marketing.

Compare the Skill Across Agents in Termdock

Install the same skill in the location supported by each tool, then open two Termdock sessions. Give each one a prompt that should trigger it and one that should not. Record whether it loaded, which instructions were followed, and how the outputs differ. After editing, start fresh sessions and repeat to avoid relying on earlier conversation. Verify each tool's skill path and permissions; Termdock does not install or activate the skill for other tools.

To have one session collect the other's results, follow the agent handoff workflow. Pass the test prompts and results explicitly rather than assuming conversations are shared.

The Cross-Agent Skill Authoring Checklist

Publishing a skill for multi-agent use? Before publishing:

1. Use .agents/skills/ as primary directory. Symlink to .claude/skills/ if needed.
2. Frontmatter: name and description only. No agent-specific fields unless you document degradation.
3. Write instructions as outcomes, not tool calls. "Run pnpm test" not "Use Bash tool."
4. Relative paths only. From skill directory or project root.
5. Test on Claude Code + one other agent. Codex CLI is easiest second target.
6. Keep SKILL.md under 500 lines. Long content in references/.
7. Include scripts/ for deterministic tasks. Every agent runs bash.
8. Document tested agents. "Tested on: Claude Code, Codex CLI, Gemini CLI" sets expectations.
9. Avoid agent-detection conditionals. "If Claude Code do X, if Codex do Y" fights the abstraction. One instruction everywhere.
10. Pin marketplace versions. Skills.sh built-in versioning. npm via skillpm uses semver.

For design principles -- description optimization, progressive disclosure, eval loops -- the skill design principles guide covers craft. This checklist covers distribution.

Where This Is Heading

The skills ecosystem is roughly where npm was in 2011. Format standardized. Multiple registries competing. Distribution fragmented but functional. Community producing volume, 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 integration, real install metrics. SkillsMP has volume but no install mechanism. ClawHub has curation but trust damage. Within 12 months, expect one dominant registry with others as mirrors.

npm convergence. skillpm and skills-npm point the way. Skills will become npm packages with agent metadata. Separate registries will integrate with npm or lose to direct npm publishing. JavaScript already solved package distribution. Re-solving it for a text format in the same repos is wasted time.

Agent-side standardization. Directory fragmentation is unsustainable. Agents will converge on .agents/skills/ as primary, not just fallback. OpenAI and Google adopting it as primary makes this likely. Claude Code already reads it. Question is when it becomes documented default rather than footnote.

Developers building cross-agent skills today are the equivalent of npm package authors in 2012. Ecosystem is messy. Tooling incomplete. Conventions still forming. That is exactly when showing up and shaping the standard beats waiting for it to stabilize.

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