Plugin authoring

Skill selamy-labs/agent-skills/skills/plugin-authoring

Use when packaging skills, commands, agents, or hooks into a Claude Code plugin and publishing to a marketplace. Get the directory structure, plugin.json and marketplace.json manifests, version bump, and local-test loop right so the plugin installs cleanly and is version-pinnable.From its SKILL.md

Install

npx -y skills add selamy-labs/agent-skills --skill plugin-authoring

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.5 KB, 540 tokens by cl100k_base, as published. Nobody here has run it

Plugin Authoring

A Claude Code plugin bundles skills (and optionally commands, agents, hooks, MCP servers) into one versioned, installable unit distributed through a marketplace. Getting the structure and manifests right is what makes it install cleanly and pin to a known version — the failure modes are all in the layout and the JSON.

Structure

my-plugin/
  .claude-plugin/
    plugin.json          # the plugin manifest
  skills/<name>/SKILL.md
  commands/<name>.md     # optional
  agents/<name>.md       # optional
  hooks/                 # optional

The marketplace is a separate repo (or root) with a marketplace.json listing the plugins it offers.

Manifests

plugin.json — identity + version (the thing consumers pin):

{
  "name": "my-plugin",
  "version": "0.2.0",
  "description": "One line on what it provides",
  "author": { "name": "...", "email": "..." }
}

marketplace.json — the catalog entry pointing at the plugin:

{ "name": "my-marketplace",
  "plugins": [{ "name": "my-plugin", "source": "./my-plugin" }] }

The loop that prevents broken releases

Build the structure; keep one capability per skill.
Validate locally — install the plugin from a local path and confirm the skills/commands actually load before publishing. A manifest that parses but ships a skill that won't load is the classic invisible break.
Version deliberately — bump plugin.json version on every change; consumers pin to it, so an unversioned change silently shifts everyone.
Publish by updating the marketplace entry, then have a consumer install the pinned version and verify it resolves.

Discipline

Version-pin in consumers, never float — reproducibility beats "latest."
One bundled unit, declared per workload — each workload's config names the plugin + version it gets, so what's installed is auditable.
Don't ship exec scripts inside skills — keep skills as instructions; put any tooling in the plugin's scripts/commands, audited separately.

Adapted from the MIT-licensed softaworks/agent-toolkit plugin-packaging skill (guidance only; upstream's generator script intentionally omitted).

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most skill authoring skills give in 540 tokens

Counted across 408 of the 422 authors here whose files we hold, read 2026-09-06

Keep SKILL.md under 500 linesin 118 of 408, across 104 files
Write skill instructions in imperative formin 44 of 408, across 37 files
Move detailed reference material into references filesin 41 of 408, across 34 files
Run init_skill.py to initialize new skillsin 40 of 408, across 33 files
Draft assertions while test runs are in progressin 32 of 408, across 25 files
Keep description under 1024 charactersin 31 of 408, across 18 files
Run package_skill.py once the skill is completein 29 of 408, across 23 files
Spawn with-skill and baseline runs in the same turnin 28 of 408, across 21 files
Test added scripts by actually running themin 27 of 408, across 21 files
Follow the creation steps in orderin 24 of 408, across 17 files
Generate the eval viewer before evaluating outputs yourselfin 24 of 408, across 17 files
Write the description in third personin 24 of 408, across 18 files

Said here and by no other author read

Build the plugin directory structure
Write a plugin.json manifest
Install from a local path before publishing
Confirm skills and commands load before publishing
Bump plugin.json version on every change
Publish by updating the marketplace entry

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.