Packaging and distributing skills, agents, and CLAUDE.md

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Once a skill, agent, or CLAUDE.md convention is useful in more than one repository, it needs a distribution strategy. There are two, and they suit different situations rather than one strictly superseding the other.

Option 1 — copy the files directly

Drop the relevant .claude/skills/<name>/, .claude/agents/<name>.md, or CLAUDE.md content straight into the target repository, the way this catalog’s own README already describes adopting one of its skills (AI Catalog: "copy the ones you need into another repository’s .claude/skills/ directory").

Best fit when:

  • The skill/agent is being adopted by a handful of repositories, not fleet-wide.

  • Each adopting repository is expected to tweak it for local conventions rather than stay byte-identical to the source.

  • There’s no appetite yet for standing up and maintaining a marketplace.

Tradeoff: there is no update mechanism. A fix or improvement made in one copy doesn’t reach the others unless someone notices and re-copies it — this scales fine to a few repositories and poorly to dozens.

Option 2 — package as a plugin, distribute via a marketplace

Bundle the skill(s)/agent(s) into a plugin (Plugins) and publish it to a marketplace — either a private one hosted in an internal git repository, or a public one.

Best fit when:

  • The same skill/agent needs to behave identically across many repositories (a compliance check, a house release process) and drift between copies is itself the problem.

  • You want version history and a real update path: bump the plugin’s version, and every installing repository can pick up the change deliberately (/plugin install again, or however the marketplace tooling surfaces updates) rather than via a manual diff-and-copy.

  • The skill is genuinely reusable beyond one organization, in which case a public marketplace submission reaches adopters you don’t otherwise know about.

Tradeoff: real packaging overhead — a manifest to maintain, a marketplace to stand up (for a private one) or a submission process to go through (for a public one), and namespacing to be mindful of (/plugin-name:skill-name instead of a bare /skill-name).

This catalog ships both ways

The catalog documents copying (Option 1) and also publishes itself as a plugin marketplace (Option 2), so either path works for its skills:

claude plugin marketplace add albertoirurueta/ai-catalog
/plugin install iru-core@ai-catalog
/plugin install iru-java@ai-catalog

installs the stack-independent iru-core plugin and the Java plugin; the other stacks are separate plugins (see Plugins). Differences to expect compared with copying: skills are also reachable under their namespace (/iru-java:iru-java-test as well as the bare /iru-java-test), agents must be dispatched as iru-core:iru-gate-runner (and likewise for the other two), claude -p needs --allowedTools=Skill to run skills that declare allowed-tools, and each installed plugin caches a full copy of the repository. Copying a skill directory into a repository’s .claude/skills/ still works exactly as before, because every skill keeps its templates and references under its own directory.

Choosing

Signal Favors copying files Favors a plugin + marketplace

Number of adopting repositories

A handful

Many, or unknown in advance

Expected local drift

Repositories will customize it

Should stay identical everywhere

Update cadence

Rare, low-stakes changes

Needs a real versioned update path

Audience

This org, this repository only

Multiple teams, or the public

CLAUDE.md content that’s genuinely universal across an organization (not project-specific) is better served by the enterprise-managed policy file (The CLAUDE.md file's locations table) than by either option here — that mechanism exists specifically so an org can set instructions no single repository or person needs to copy or install at all.

See also