Portable by Design, Measured by Degrees

addyosmani/agent-skills makes a portability claim with two parts: the workflow content is shared, while the way a host discovers and invokes that content is adapted to its own conventions. This chapter examines that boundary and then asks how the repository measures its own catalog. The goal is to distinguish a portable Markdown core from behavioral equivalence across tools, and to read structural, routing, and behavioral evals as different kinds of evidence rather than as one score.

Portability matters because a workflow that works only inside one assistant’s private configuration cannot easily become a team standard. But broad installation support can also hide variation. A command may be discoverable on one host and require a different entry point on another. Shared references may be present in a whole-repository install but absent from a per-skill copy. A successful installation can show that files arrived; it cannot by itself show that the agent will follow them in the same way.

The core is shared; the edges are native

The repository keeps the portable workflow core under skills/. Each skill is a Markdown process that can be loaded by an agent capable of reading instruction files. Around that core sit host-native adapters: command directories, plugin manifests, hooks, setup guidance, and discovery paths. The repository describes integrations for a wide range of agent tools, but it does not flatten their differences into one universal runtime.

This is a sensible division of responsibility. The core expresses the engineering judgment that should survive a host change: clarify assumptions, test behavior, review the change, or stage a risky release. The adapter expresses how a particular host finds that workflow, what syntax starts it, which context is loaded automatically, and whether an MCP server or native command mechanism is available. A host can change its command format without requiring every skill to be rewritten, while the core can evolve without pretending that every host exposes the same capabilities.

The npx skills installation path makes the core easy to distribute, and native integrations make it easier to fit a host’s conventions. The trade-off appears when someone installs only one skill. A per-skill copy includes the selected skills/<name>/ directory but not necessarily the repository-level references/ directory that some workflows expect. The skill may still run, but supplementary checklists can become unavailable. The repository documents this as a portability gap and recommends whole-repository integration, cloning, or copying the needed reference into the installed context.

That gap is not a minor packaging detail. It shows that a workflow’s behavior depends on more than its main Markdown file. A portable core may have sibling assets, command parity requirements, hooks, and host assumptions. Removing those relationships can preserve the file while weakening the process it was designed to invoke.

The repository’s own project structure therefore treats native paths as contracts. Claude Code, Gemini CLI, and Antigravity have parallel command locations; plugin manifests point hosts toward shared skills; hooks can inject discovery context; and contributor checks compare command parity. These paths are not branding aliases that can be casually merged.