Architecture decision

Agent Skills vs Plugins

Should a capability be one portable workflow or an installable extension bundle?

Get the short answerReview evidence

The short answer

Start with a Skill. Move to a plugin when installation, versioning, namespacing, multiple components, or organization-wide distribution become product requirements.

Choose

Agent Skills

Discoverable, reusable packages of instructions and resources that teach an agent a specialized workflow without loading the whole procedure into every session.

  • One workflow or domain reference solves the problem.
  • The project owns the capability and does not need a release channel.
  • The procedure should remain easy to inspect and copy.
Open the Agent Skills guide

Choose

Plugins

Installable bundles that distribute one or more agent extensions—such as Skills, subagents, hooks, MCP servers, or application connectors—as a coherent product.

  • Several related Skills, agents, hooks, or servers should install together.
  • The extension needs versioned releases, ownership, and update behavior.
  • A marketplace or administrator will distribute it to multiple teams.
Open the Plugins guide
Use both

How the layers combine

  1. 01

    Build and evaluate each Skill independently before packaging.

  2. 02

    Use the plugin manifest to declare the installable boundary and component ownership.

  3. 03

    Keep executable hooks and network destinations explicit during every plugin review.

Decision review

Questions to answer before implementation

  • Can users explain what the install adds and removes?
  • Are component names and triggers collision-resistant?
  • Can the package be pinned and upgraded predictably?
  • Are scripts, hooks, permissions, and servers auditable?
  • Does each bundled Skill still work as a coherent capability?

Evidence ledger

Primary documentation for both sides

Reviewed July 26, 2026. Use the provider documentation for current configuration and security behavior.

Agent Skills specification

Agent Skills

The open SKILL.md package format and progressive-disclosure model.

Build skills for ChatGPT and Codex

OpenAI

Current OpenAI Skill structure, discovery, and authoring guidance.

Extend Claude with skills

Anthropic

Claude Code Skill discovery, configuration, supporting files, and invocation behavior.

Plugins in ChatGPT and Codex

OpenAI

OpenAI plugin packaging, components, and distribution model.

Claude Code plugins

Anthropic

Claude Code plugin manifests, marketplaces, and packaged extension types.