From skill to plugin: build your own tooling

What to understand

• Think of a capability ladder: Prompt -> Template -> Skill -> Plugin -> MCP server -> Internal app. Each rung adds reach and durability but also adds cost to build and maintain, and the value gained per extra unit of effort drops as you climb. Climb only as far as the problem actually demands, the most common mistake on this topic is climbing for its own sake.
• A prompt is a one-off. A template is a saved prompt you reuse. A skill (Lesson 14) packages a workflow reliably for you, the single user. The first three rungs cover the large majority of personal knowledge-work needs and should be your default; you only leave them when sharing or programmatic integration becomes the real requirement.
• A plugin is the sharing rung, it is what turns 'my skill' into 'our tool'. Codex describes plugins as bundling skills, app connectors, and MCP servers into reusable, installable workflows; Claude Code describes a plugin as a self-contained directory of components (skills, agents, hooks, MCP servers, LSP servers, monitors) that others install in one step and get a ready-to-go setup with no manual configuration.
• An MCP server is the integration rung: a service that exposes tools and live data from an external system to the agent. You reach for it only when a skill needs structured, programmatic access to a system rather than just instructions, and a plugin can then bundle that server. An internal app is the top rung, for when the workflow needs its own UI, persistence, and users beyond the agent.
• In Claude Code a plugin is a folder whose only required file is .claude-plugin/plugin.json (and even that is optional, components auto-discover, and the name can come from the directory). Components live at the plugin ROOT, never inside .claude-plugin/: skills/, commands/, agents/, hooks/hooks.json (scripts that fire automatically on agent events).mcp.json connectors.lsp.json (language-server integrations), plus optional bin/, monitors/ (background watchers that react to agent activity), themes/, and output-styles/. The single field that is required when you do write a manifest is name.
• Codex uses a parallel layout: a .codex-plugin/plugin.json manifest (JSON) at the plugin root, with name, version, and description as the core fields, declaring skills/, an .mcp.json for MCP servers, and an .app.json for app connectors. The two ecosystems deliberately mirror each other, the same mental model (manifest + component folders) ports across both tools.
• Plugins are distributed through marketplaces, which are just catalogues. In Claude Code a marketplace is a .claude-plugin/marketplace.json listing plugins and their sources; you add one with `claude plugin marketplace add <owner>/<repo>` (or a local path) and install with `claude plugin install <plugin>@<marketplace>`. Anthropic ships curated marketplaces (Knowledge Work, Financial Services, Legal, Life Sciences). In Codex you `codex plugin marketplace add` from GitHub shorthand, a git/SSH URL, or a local folder, browse the Plugins directory / `/plugins`, and choose 'Add to Codex'.
• Versioning decides who gets your changes and when, it is not a formality. In Claude Code, if you set `version` in plugin.json you must bump it on every release or users keep the cached copy; if you OMIT version, the git commit SHA becomes the version so every push is an update. That gives two deliberate strategies: explicit semver for published, stable plugins; commit-SHA for internal, fast-moving ones. Pick one consciously per plugin.
• Trust is the load-bearing constraint when you climb to plugins and MCP. Claude's own guidance is blunt: only install plugins from sources you trust, because a plugin may bundle local MCP servers that run with program-level permissions on the installer's machine. The same caution binds you as a publisher: every connector you bundle widens the trust surface you are asking others to accept, so bundle exactly what the workflow uses and document it.
• Governance scales the discipline to a team. Claude Code supports install scopes (user, project, project-local, managed) so a plugin can be personal, checked into a repo for collaborators, or pushed read-only by an admin via managed settings; project-scope plugins load only after the workspace trust gate, and admins can restrict which marketplaces are allowed. Codex respects existing approval settings on install and lets a plugin be disabled with `enabled = false` in config. Shipping for an org means thinking in these controls, not just in 'does it work for me'.

Deeper dive

Plugin packaging & distribution compared (Claude Code vs Codex, June 2026)

How each tool packages, distributes, versions, and governs plugins. These are the mechanics you'll use in the hands-on. Both tools ship fast and the plugin systems are young. Codex's self-serve publishing was still 'coming soon' as of mid-2026, so verify file names, fields, and CLI commands at the official docs linked below before relying on specifics.

Sources (as of June 2026): Claude Code. Plugins reference (manifest schema, layout, versioning) · Claude Code. Plugin marketplaces (marketplace.json, add/install) · Codex. Plugins (bundles skills/apps/MCP, install, governance) · Codex. Build plugins (manifest, publishing 'coming soon')

Step by step

1

Locate your skill on the ladder

Take the skill you built in Lesson 14 and ask one honest question: who needs it? If it's just you, stop at the Skill rung, you're done, and that is the right answer. Only consider climbing if you have concrete evidence of shared need: a teammate keeps asking you to run it for them, or you find yourself copying the folder around to other machines. Write your placement and the one piece of evidence (or its absence) in a sentence. The lesson's funnel visualisation above is the ladder, find your skill's rung on it before writing your sentence.

HintThe honest answer is usually 'it's fine as a skill'. Reach drops in value per extra unit of effort as you climb, resist promoting for its own sake.

2

Decide: plugin or MCP server

12

If your need is SHARING a workflow made of instructions plus existing connectors, that's a plugin. If your need is new PROGRAMMATIC access to a system the agent can't reach today, live queries, writes to an internal database, that's an MCP server, which a plugin can then bundle. Most teams need a plugin, not a new server. Name which one your case is, and if it's a server, name the specific data the agent genuinely cannot reach with an existing connector. Done when you've written one line naming plugin or server, and, if server, the specific data no existing connector reaches.

HintBuild a new MCP server only when no existing connector reaches the data. The server is the deepest, highest-maintenance rung, don't take it on speculatively.

On this screen

1. 1'A plugin can contain' (page bullets). Skills, apps, and MCP servers. Codex's own menu of what the sharing rung bundles; if your need is instructions plus existing connectors, it is a plugin.
2. 2MCP servers in the same list. The integration rung, only build one when no existing connector reaches the data; a plugin can then bundle it.

3

Lay out the plugin and write the manifest

12

Build the directory: .claude-plugin/plugin.json at the top, and ALL component folders (skills/, commands/, hooks/.mcp.json) at the plugin ROOT, never inside .claude-plugin/. Write the manifest using the production example in this lesson: name (kebab-case, it namespaces your components), description, an explicit version, license/repository/homepage for the trust storefront, defaultEnabled:false if it touches an external system, and userConfig (with sensitive:true on any token). For Codex, mirror the same shape under .codex-plugin/plugin.json with skills/.mcp.json, and .app.json. Keep the connector list to exactly what the workflow uses. Shortcut: claude plugin --help shows an init|new subcommand that scaffolds this exact layout for you, run it, then check the result matches the rule: only plugin.json inside .claude-plugin/, every component folder at the root. Done when your tree shows .claude-plugin/plugin.json plus your component folders at the root.

HintComponents inside .claude-plugin/ is the #1 'plugin loads but skills are missing' bug. Only plugin.json belongs in .claude-plugin/; everything else sits at the root.

On this screen

1. 1init|new. Scaffolds a new plugin with the correct layout, the fastest way to avoid the components-inside-.claude-plugin bug.
2. 2validate. Validates a plugin or marketplace manifest, you'll run it with --strict in step 5 before sharing.

4

Choose a version strategy and write the changelog

Decide the release channel deliberately. For a published, stable plugin set an explicit semver `version` in plugin.json and commit to bumping it every release (MAJOR=breaking, MINOR=feature, PATCH=fix), pushing commits without bumping ships nothing. For an internal, fast-moving plugin, OMIT version so the git commit SHA drives updates and collaborators track HEAD automatically. Start a CHANGELOG.md now; the version number plus the changelog is the entire interface your users use to decide whether to take a change.

HintIf you set `version`, you MUST bump it for users to get changes. Claude Code keeps the cached copy when the string is unchanged. If you're iterating fast, leave it unset on purpose.

5

Distribute via a marketplace and test on a clean profile

12

Create a .claude-plugin/marketplace.json (name, owner, plugins[] with name + source), a GitHub repo is itself a marketplace. Test locally first: `claude plugin marketplace add ./your-marketplace`, then `claude plugin install <plugin>@<marketplace>`, and run `claude plugin validate ./plugins/<plugin> --strict` to catch typo'd fields. Then add it the real way (`claude plugin marketplace add <owner>/<repo>`) and install at the right scope (--scope project for team-shared, local for gitignored personal). Run the bundled command end to end on a clean profile or a colleague's machine. Done when the namespaced command (/your-plugin:your-skill) runs end to end on the clean profile.

Hint'Works on mine' is not 'ready to share'. A clean-room install on a fresh profile catches the missing userConfig prompt, the path-traversal reference, and the connector that only worked because YOUR machine already had it.

On this screen

1. 1@marketplace suffix. install <plugin>@<marketplace> names which catalogue the plugin comes from, the marketplace you added with /plugin marketplace add (use a local path first for the clean-room test).
2. 2Namespaced commands. Plugin skills invoke as /plugin-name:skill-name, so they never clash with the installer's personal skills.

6

Set trust, scope, and governance boundaries

12

Before sharing, write the trust note an installer can act on: name every MCP server and app connector the plugin runs and the access each needs, state the minimum scope it should be installed at, and tell installers to enable integrations only if they trust the source, reminding them that bundled local MCP servers run with program-level permissions. Decide governance: defaultEnabled:false for anything with a cost or permission footprint, project scope (trust-gated) for team sharing, managed scope when an admin should enforce it org-wide. On Enterprise, expect admins to restrict which marketplaces are allowed.

HintTreat publishing a plugin like shipping software: a trusted source, a clear changelog, least-privilege connectors, and a trust note that lets a reviewer, or a security team, say yes quickly.

On this screen

1. 1Trust warning (boxed note). The note on this support page is the exact warning your trust note answers: bundled local MCP servers run with the same permissions as installed software, only install from trusted sources.
2. 2Enterprise restriction (same note). 'Your organization may have restricted which plugins you can install', the admin-side control; state the minimum scope your plugin needs so a reviewer can approve it quickly.

Production prompt examples

// .claude-plugin/plugin.json
// Lives in .claude-plugin/; ALL component folders (skills/, commands/, agents/,
// hooks/.mcp.json) sit at the plugin ROOT, never inside .claude-plugin/.
{
 "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
 "name": "deal-desk-review",
 "displayName": "Deal Desk Review",
 "version": "1.2.0",
 "description": "Reviews inbound sales contracts against our redline playbook and drafts a summary for legal.",
 "author": { "name": "RevOps Tooling", "email": "revops-tools@example.com" },
 "homepage": "https://wiki.example.com/plugins/deal-desk-review",
 "repository": "https://github.com/example/deal-desk-review",
 "license": "Apache-2.0",
 "keywords": ["sales", "contracts", "legal", "review"],

 // Ship installed-but-OFF: this plugin connects to an external system and adds
 // token cost, so require a deliberate opt-in rather than auto-running on install.
 "defaultEnabled": false,

 // Only the connector the workflow actually uses. One server, least privilege.
 "mcpServers": "./.mcp.json",

 // Prompt the installer for their own values at enable time instead of making
 // them hand-edit settings.json. The token is sensitive -> goes to the keychain.
 "userConfig": {
 "clm_base_url": {
 "type": "string",
 "title": "Contract system base URL",
 "description": "Your CLM instance, e.g. https://clm.example.com",
 "required": true
 },
 "clm_api_token": {
 "type": "string",
 "title": "CLM API token (read-only scope)",
 "description": "Use a READ-ONLY token. The plugin never writes to the CLM.",
 "sensitive": true,
 "required": true
 }
 }
}

// .claude-plugin/marketplace.json (at the repo ROOT of your marketplace repo)
// A GitHub repo IS a marketplace, no hosted registry needed to share with a team.
{
 "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
 "name": "revops-tools",
 "owner": { "name": "RevOps Tooling", "email": "revops-tools@example.com" },
 "metadata": { "pluginRoot": "./plugins" },
 "plugins": [
 {
 "name": "deal-desk-review",
 "source": "deal-desk-review", // resolved under metadata.pluginRoot -> ./plugins/deal-desk-review
 "description": "Contract review against our redline playbook.",
 "version": "1.2.0",
 "category": "sales",
 "defaultEnabled": false // marketplace entry wins over plugin.json for this field
 }
 ]
}

// ---- Installer flow (Claude Code CLI) ----
// Add the marketplace by GitHub owner/repo (or a local path for testing first):
// claude plugin marketplace add example/revops-tools
// claude plugin marketplace add ./revops-tools # local, for a clean-room test
//
// Install at the right SCOPE (team-shared = project; gitignored personal = local):
// claude plugin install deal-desk-review@revops-tools --scope project
//
// Validate before publishing; --strict turns warnings (typo'd fields) into errors:
// claude plugin validate ./plugins/deal-desk-review --strict
//
// Release a change the EXPLICIT-version way: bump plugin.json version, commit, push.
// Users pick it up with: claude plugin update deal-desk-review@revops-tools

Common mistakes to avoid

• Climbing to a plugin or MCP server when a personal skill already does the job for one user, packaging reach nobody asked for is pure overhead.
• Building a new MCP server when an existing connector already reaches the data, taking on the highest-maintenance rung speculatively.
• Putting component folders (skills/, commands/, hooks/) INSIDE .claude-plugin/, only plugin.json belongs there; everything else sits at the plugin root, and getting this wrong makes the plugin load with its components silently missing.
• Bundling more connectors than the workflow uses, widening the trust and permission surface installers (and their security teams) must accept for no benefit.
• Setting an explicit `version` and then pushing fixes without bumping it. Claude Code keeps the cached copy, so the change never reaches users while `/plugin update` reports 'already latest'.
• Publishing with no license, repository, or CHANGELOG, the trust storefront an installer reads before running your code, left blank, reads as 'unmaintained and unaccountable'.
• Letting a plugin auto-enable its external integrations on install instead of shipping defaultEnabled:false for anything with a cost or permission footprint.
• Publishing without a trust note, leaving installers unaware that bundled MCP servers run with program-level permissions and at what minimum scope the plugin should be installed.
• Calling 'works on my machine' done, never doing a clean-profile install that would expose the missing userConfig prompt, a path-traversal reference, or a connector that only worked because your machine was already set up.

Source conflicts to review

• FORMAT DRIFT (Codex): Codex's plugin manifest is documented less completely than Claude Code's.codex-plugin/plugin.json (JSON) with skills/.mcp.json/.app.json is the reported shape, but OpenAI stated self-serve publishing to the official Plugin Directory was 'coming soon' as of mid-2026, so the manifest field names and publishing flow are provisional. Re-verify at developers.openai.com/codex/plugins/build before relying on Codex specifics.
• VERSION-GATED FIELDS (Claude Code): several manifest fields are tied to client versions, displayName requires Claude Code v2.1.143+, defaultEnabled v2.1.154+, plugin background monitors v2.1.105+, plugin prune v2.1.121+. A field shown in this lesson may not exist on an older client; confirm against your installed version with `claude plugin validate`.
• SCHEMA EVOLUTION: marketplace 'strict' mode and the version-resolution precedence (plugin.json version > marketplace entry version > git SHA > unknown) have changed across point releases, and third-party blogs lag the official docs. Cite code.claude.com/docs/en/plugins-reference and /plugin-marketplaces over secondary sources, and treat all CLI command names and field names as accurate only as of June 2026.