doctor-universal-plugin
Diagnoses a plugin and repairs nothing: it reports what is declared, unbuilt, stale, drifting, or shadowing, then names the skill that owns each repair.
Output
Section titled “Output”The checks run as a script rather than a prose checklist, because they are deterministic. It emits one JSON object:
{ "manifest": { "name": "my-plugin", "version": "1.0.0" }, "vendors": [{ "vendor": "claude-code", "path": ".claude-plugin/plugin.json", "status": "built", "exists": true, "stale": false }], "findings": [{ "code": "unbuilt", "severity": "high", "detail": "…", "repair": "…" }], "ok": false}Exit status is 0 whether or not findings exist. A finding is a result, not a failure, so the
script is safe to run from a session-start hook.
What it can’t check inline
Section titled “What it can’t check inline”One check stays out of the script. Comparing a derived manifest against what the build would write today requires rebuilding on a clean tree, and that writes. The skill reports it as a repair for you to run.
One check reads git rather than the filesystem. A runtime keys its plugin cache on the version, so
content committed after the commit that set the current version never reaches anyone who already
installed the plugin. The skill reports that as unreleased-content. It stays quiet where the release
moves the number: a plugin that declares packagePath, or one that changesets, release-please,
semantic-release, or release-it versions. It also stays quiet on a tree with no history.
Skills that run the plugin’s own CLI through a package runner
Section titled “Skills that run the plugin’s own CLI through a package runner”A skill runs its plugin’s own CLI through a forwarder: plugin build writes
skills/<skill>/scripts/<bin>.mjs from a { "forward": "<bin>" } entry, and the skill calls it with
node <this skill's folder>/scripts/<bin>.mjs <args>. See
Running your CLI from skills.
The skill reads each skill and agent Markdown file for a line that runs the plugin’s own package
through npx, upx or pnpm exec <bin>, and reports two findings, both severity low:
own-package-runner: the skill has no forwarder for that CLI. The repair names theforwardentry to declare, with the path filled in, and thenodecall that replaces the line. The add a CLI forwarder route ofinit-universal-plugindoes the setup.runner-beside-forwarder: the same skill already has a forwarder for the CLI. Call the forwarder instead of the runner line.
A package named with no command after it, and a line inside a yaml, json or toml
fence (config the user copies), are not read.
Changesets release config
Section titled “Changesets release config”A plugin installed from git or a marketplace catalog, rather than npm, can still be released with changesets. It needs three things, and the skill reports each one that is missing:
changesets-no-package: apackage.jsonat the plugin root. Changesets releases only a package.init-universal-pluginwrites a minimal private one.changesets-private-untagged:"privatePackages": { "version": true, "tag": true }in.changeset/config.json. Withouttag,changeset publishcreates no tag for a private package.changesets-no-publish-script: apublish-scripton thechangesets/actionstep. Without it, the action does nothing after the Version Packages PR merges, so no tag or GitHub release is made.
A plugin whose root package.json is published to npm is not checked here.
release-please release config
Section titled “release-please release config”release-please can release a plugin with no package.json by bumping plugin.json through
extra-files. It runs no command before its release commit, so the rest of the places that carry
the version stay behind unless a workflow restamps the release PR. The skill reports
release-please-no-restamp when release-please-config.json lists the plugin’s plugin.json in
extra-files and no workflow under .github/workflows runs plugin version. The
version skill has the workflow step. A plugin that declares packagePath is not
checked here.
A push made with the default GITHUB_TOKEN starts no workflow run, so a restamp pushed with it
leaves the release PR’s head commit with no checks, and a required check blocks the merge. The skill
reports release-please-restamp-no-ci when a workflow runs --from-manifest and git push with no
other credential in sight: no actions/create-github-app-token step, no deploy key, and no token:
input other than the default token. It reads the workflow as text, so any of those clears the file.
A workflow_dispatch re-run does not clear it, because checks from that event do not count toward a
required check.
release-it config
Section titled “release-it config”release-it commits and tags whatever the tree holds once its hooks have run. A release-it config
(.release-it.json and its siblings, or the release-it key of package.json) with no hook running
plugin version tags a release whose plugin.json and vendor manifests still carry the previous
version. The skill reports it as release-it-no-stamp. The fix is an after:bump hook:
"hooks": { "after:bump": "universal-plugin plugin version ${version}" }.
semantic-release config
Section titled “semantic-release config”semantic-release decides the version inside its own run, so only an @semantic-release/exec
prepareCmd running plugin version carries it into plugin.json and the derived files before
@semantic-release/git commits them. The skill reads the config semantic-release would load (the
release key of package.json, then the first .releaserc*, .config/releaserc* or
release.config.* file) and reports:
semantic-release-no-stampwhen noprepareCmdrunsplugin version. A stamp inpublishCmdruns after the commit, so it does not count.semantic-release-npm-unshippedwhen the plugin ships to no npm package and the config lists@semantic-release/npm, or names nopluginsand so gets the default list, which includes it. With nopackage.jsonthe release fails withENOPKG.semantic-release-no-commitwhen aprepareCmdstamps but the config runs no@semantic-release/git. semantic-release tags the commit thepreparestep leaves, so without a commit the tag holds the files from before the stamp. AprepareCmdthat runsgit commititself counts. The finding ismediumfor a plugin that ships to npm, whose package still carries the number, andhighotherwise.semantic-release-git-before-execwhen@semantic-release/gitcomes before the@semantic-release/execthat stamps. Plugins runprepareinpluginslist order, so git commits the files before exec stamps them. The order is checked only in a JSON or YAML config with no top-levelpreparekey, where the text order is the list order.
The init-universal-plugin skill writes the wiring. A config that
extends a shareable config is not checked, because the wiring may live in the shared one.
Version drift in CI
Section titled “Version drift in CI”The skill reports each file whose version disagrees with the release’s number as version-drift:
the canonical manifest, a vendor manifest, a catalog entry, or a skill pin. The same comparison is a
CLI command that exits 1 on drift, so a repository can fail the release PR instead of publishing the
old number:
universal-plugin publish check-version --root <plugin-root>When the skill finds drift and the repository does not run this yet, it offers to add it to the
verify script or the CI workflow.
See also
Section titled “See also”init-universal-plugin— owns the repairs this skill namesplugin build— the CLI command behind--dry-run, for scripting and CI