jaktestowac/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.

| Shape | Justified when | | --- | --- | | One skill | It stands alone, and nothing else is needed to use it | | A skill plus its quick variant | The pair covers routine and deep use of the same capability, like writing-unit-tests | | Several cooperating skills | A user reaching for one reliably reaches for the others in the same session |

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.

| Command | Does | | --- | --- | | npm run plugin:generate -- <name> | add the entry for one plugin or root skill | | npm run plugin:generate -- <name> --description='...' | add it with a written description instead of the skill's | | npm run plugin:generate | backfill entries for every plugin folder missing one | | npm run plugin:generate:all | register every root skill, refreshing existing entries from their SKILL.md | | npm run plugin:generate -- --dry-run | print what would change, write nothing | | npm run plugin:generate -- --no-overwrite | report drift instead of rewriting an entry | | npm run plugin:generate -- --verbose | list every item instead of a count | | node scripts/generate-plugins.js --check | fail if a plugin folder has no entry (CI, part of npm run lint) |

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/...

Phase 3: Complete the manifest

The scaffolder writes a plugin.json; fill in what it cannot know.

{
  "name": "planning-exploratory-testing",
  "description": "...",
  "version": "1.0.0",
  "author": { "name": "jaktestowac.pl" },
  "repository": "https://github.com/jaktestowac/awesome-copilot-for-testers.git",
  "license": "MIT",
  "keywords": [
    "exploratory testing", "session-based testing", "charters",
    "test heuristics", "SFDIPOT", "tours", "manual testing", "QA"
  ],
  "skills": ["./skills/planning-exploratory-testing/"]
}

• skills paths are relative to the plugin root and resolve to skills/<name>/ at the repository root during materialize
• keywords are how a user finds the plugin; include the terms they would search, including the ones the skill's own description does not need
• keywords and skills are the two fields a re-materialize leaves alone - edit them here
• description and version come from the marketplace entry and are rewritten on every materialize; change them there, not here

Phase 4: Write the plugin README

The body is yours to write and survives every re-materialize; the frontmatter description is taken from the marketplace entry, so change it there. Then:

• what problem the plugin solves, in one paragraph
• what is inside: each skill, plus its bundled resources listed individually. This is the part a user reads to judge depth.
• installation commands
• related plugins, and when to reach for those instead
• the source-of-truth note

The resource list matters more than it looks. It is the difference between "a skill about exploratory testing" and "the charter format, the SFDIPOT heuristics, the note template, and the PROOF debrief", and it is what tells a user whether the plugin is worth installing.

Use ./resources/plugin-readme.template.md.

Phase 5: Verify

npm run plugin:materialize   # regenerate the copies
npm run generate             # regenerate the repository README tables
npm run check                # verify the README is in sync
npm run lint                 # frontmatter, orchestration, plugin sync

check-plugin-sync.js performs two checks:

1. every skill declared in a plugin.json has a materialized copy with a SKILL.md
2. for each plugin skill copy whose source exists at the repository root, the file lists and file contents match exactly

A drift error means a plugin copy was edited directly, or a root skill changed without a re-materialize. Both are fixed by editing the root skill and running npm run plugin:materialize.

Phase 6: Keep it in sync

The recurring rule for anyone changing a skill that a plugin vendors:

Edit skills/<name>/. Then run npm run plugin:materialize && npm run generate.

Add it to the pull request habit. The lint catches it, but catching it in CI costs a round trip that a one-line habit avoids.

Common Failure Modes

• editing a file under plugins/*/skills/, which fails the sync check and is lost on the next materialize
• changing a root skill and pushing without re-materializing
• a plugin.json declaring a skill that does not exist at the repository root
• bundling by topic, so one plugin ships a dozen competing descriptions
• a marketplace description that describes the topic and never says when to install it
• a README listing the skill but not its resources, so the depth is invisible
• editing description or version in plugin.json, which the next materialize overwrites from the marketplace entry
• rewording a marketplace description by hand and then running plugin:generate:all, which takes the skill's frontmatter back
• a plugin created for a skill still being iterated on, so every skill edit becomes a plugin release

Resource Map

• ./resources/plugin-manifest.template.md - plugin.json and marketplace entry, annotated field by field, with a worked example
• ./resources/plugin-readme.template.md - README structure, the resource-listing pattern, and a worked example
• ./resources/plugin-packaging-checklist.md - pre-ship checks and the drift-error troubleshooting table

Related Skills

• creating-skills - for the skill that the plugin ships; the skill has to be good before packaging matters
• creating-orchestration-packs - when the thing being packaged is a pack of agents rather than skills
• creating-custom-agents - when the capability belongs in an agent
• documenting-test-suites - for the same instinct applied to a test suite: say what is inside and how to start

Definition of Done

This skill is complete when:

• the bundle is one skill, or a group a user reaches for together, and grouping by topic was rejected
• the marketplace entry exists with a name, source, description, and version
• the description says what is inside and when to install it
• plugin.json carries author, repository, license, searchable keywords, and correct relative skill paths
• the README lists every bundled skill and its resources, plus installation and the source-of-truth note
• no file under plugins/*/skills/ was hand-edited
• npm run plugin:materialize, npm run generate, npm run check, and npm run lint all pass
• versions match between plugin.json and the marketplace entry