Creating Plugins

Creating Plugins

Use this skill when a skill or a small group of skills should be installable as a unit rather than copied by hand.

The rule that governs everything here: skills/ at the repository root is the source of truth, and everything under plugins/*/skills/ is generated output that happens to be committed. The generator is npm run plugin:materialize; the guard is scripts/check-plugin-sync.js, which CI runs as part of npm run lint. Editing a plugin copy directly produces a drift error and loses the edit on the next materialize.

When to Use

• a skill is mature enough to install rather than copy
• several related skills should ship together
• a new plugin needs registering in the marketplace
• npm run lint reports a plugin copy that does not match its source skill
• a plugin's description or keywords need updating

Operating Principles

• The root skill is the source of truth. Every change starts in skills/<name>/ and flows outward.
• Plugin skill copies are generated. Never hand-edited, always regenerated.
• A plugin is self-contained. The plugin format resolves skill paths relative to the plugin root, so a plugin cannot reference skills/ at the repository root. That is why the copies exist.
• The marketplace entry comes first. The scaffolder builds the plugin directory from it, and rewrites the generated fields from it on every run - edits flow downstream, never back up.
• A bundle is justified by use together. Two skills in one plugin because a user reaching for one reaches for the other, not because they share a topic.
• The description is the install decision. It is what a user reads in a marketplace listing, and it is the only thing they read.

Workflow

Phase 0: Decide the bundle

A plugin ships one skill, or a small group used together.

Not justified: grouping by topic. "All the testing skills" is a directory listing, not a plugin. The user installs it, gets fifteen descriptions competing for the same triggers, and picks worse than they would have with three.

Before bundling, confirm the skills are distinct enough to coexist. Two skills whose descriptions overlap will collide harder inside one plugin than they do in a repository, because the user installed both deliberately.

Phase 1: Register in the marketplace

npm run plugin:generate -- planning-exploratory-testing

scripts/generate-plugins.js writes the entry into .github/plugin/marketplace.json, taking the description from plugins/<name>/.github/plugin/plugin.json if the plugin folder already exists, otherwise from the frontmatter of skills/<name>/SKILL.md. Entry order is preserved and new entries are appended, so the file stays readable in diffs.

Which file wins. The pipeline flows one way, and each step overwrites what is downstream of it:

skills/<name>/SKILL.md  →  marketplace.json  →  plugins/<name>/  →  README.md
   (frontmatter)            (the registry)      (plugin.json,        (the tables)
                                                 README description)

plugin:generate:all therefore rewrites an existing entry's description from the skill's frontmatter - a marketplace description edited by hand does not survive it. Write the listing description in the skill's frontmatter, or use --description= per plugin, or pass --no-overwrite to keep what is there and have the drift reported instead. A version somebody bumped is never reset by a refresh; only --version= changes it.

plugin:generate:all packages the repository in bulk. It skips a skill another plugin already ships, and it skips <name>-quick when skills/<name>/ exists, printing the plugin.json line that bundles the quick variant with its parent instead. Pair it with --dry-run first, and read Phase 0 before accepting the result: one plugin per skill is a defensible default, but a pair used together belongs in one plugin. --check never demands a plugin for a root skill - an unpackaged skill is a normal state - so bulk mode stays opt-in and CI stays quiet about it.

A description derived from the skill frontmatter is a starting point, not the finished entry - the generator says so when it uses one. Rewrite it as a marketplace listing, then continue.

The resulting entry, hand-written or generated:

{
  "name": "planning-exploratory-testing",
  "source": "plugins/planning-exploratory-testing",
  "description": "Runs session-based exploratory testing: charters, timeboxed sessions, coverage heuristics, evidence-carrying notes, and debriefs that route every finding somewhere. Bundles the charter format with worked examples per context, the SFDIPOT and tour heuristics, a session note template with a coverage summary, and the PROOF debrief. Use when a feature needs testing before requirements settle, or when scripted cases keep passing while users hit problems.",
  "version": "1.0.0"
}

The name matches the plugin directory under source. The description is what a user reads before installing, so it says what is inside and when to reach for it, in more detail than the skill's own description needs to.

Phase 2: Scaffold and materialize

npm run plugin:materialize

This does two things, per scripts/materialize-plugins.js:

1. Scaffold - creates the plugin directory, a .github/plugin/plugin.json, and a README.md for every marketplace entry with a local source, then rewrites the generated fields on every run so the plugin always matches its marketplace entry:

   File	Overwritten	Preserved
   plugin.json	name, description, version, author, repository, license	keywords and skills - curated by hand, and not derivable from the entry
   README.md	the frontmatter description	the whole body, which is hand-written prose

   --force-readme rewrites plugin READMEs wholesale from the template, discarding that prose. Use it to reset a README the scaffolder generated, not one somebody wrote.

2. Materialize - copies each skill declared in each plugin.json from skills/ into the plugin, and prunes copies no longer declared. A copy that already matches its source is left alone, so the output names only what changed.

The generated tree:

plugins/<plugin-name>/
  .github/plugin/plugin.json
  README.md
  skills/<skill-name>/
    SKILL.md
    resources/...