release-ai-plugins

AI Plugins release process

This is a high-frequency, reproducible release entry point. Release orchestration still uses the scripts/release-ai-plugins.ps1in the same directory; the default is DryRun, and only an explicit -Apply allows writing files. ai-plugins/skill-registry.json The only canonical authority for scripts/generate-skill-registry.mjsis scripts/generate-skill-registry.ps1 . The compatibility entry point -Check/-Apply parameters to Node, and must no longer contain SKILL.md parsing, JSON serialization, indentation, escaping, or line-ending normalization logic. If any script fails, or final acceptance does not pass, release completion must not be claimed.

Fixed inputs

• -Version: plugin major version, must be MAJOR.MINOR.PATCH。
• -Skill: names of skills that were actually modified, may be repeated or comma-separated; when omitted, the script automatically discovers them based on Git changes.
• -ChangeType：added、major、minor or patch, used to upgrade the metadata.version。
• -Summaryof each modified skill: a short description written to the three CHANGELOGs.
• -NewSkill: new skill names; the corresponding plugin root README must already contain those names.
• -Apply: explicitly allow writing files; when unspecified, it is DryRun.

-NewSkill version upgrade behavior

For the skills listed in -NewSkill , the scriptforces a patch upgrade of metadata.version(source semantics if ($isNew) { $type = "patch" }），-ChangeType does not apply to new skills. This means that even if a new skill starts its first release at 1.0.0 , after Apply it will be upgraded to 1.0.1。

• Callers must anticipate this behavior: contract tests written for skills that assert version numbers should use a semantic version regex (such as /version: "1\.0\.\d+"/), and must not pin literal values, otherwise tests will turn red after release.
• If a new skill must remain at 1.0.0 for its first release: do not pass -NewSkill, pass only -Version + -Summary to complete the release; the registry will still fully regenerate and include the new skill during Apply. In this case the script does not perform the new-skill README blocking validation, and the caller must verify on their own that the README already includes the skill name.

Enforced order

1. Verify the inputs, the root each Skill belongs to, and the frontmatter of each SKILL.md .
2. Only upgrade the Skill metadata.versionthat actually changed this time; do not upgrade other Skills along the way.
3. Synchronize the nine plugin.json, the two versioned marketplaces for Claude/Cursor; validate the Codex marketplace and the dedicated fields of the three Codex manifests.
4. Update the three plugin CHANGELOGs; new Skills must first pass the corresponding plugin README blocking validation.
5. During Apply, after all Skill versions and release files are complete, call registry Apply only once, then call Check only once. The release main script may continue to be invoked through the PowerShell compatibility entry point; actual generation and comparison must be completed by Node .mjs .
6. Complete acceptance for the existing JSON, versions, README, CHANGELOG, installation docs, and git diff --check .

Multi-Skill batch releases must not repeatedly generate the registry inside the changed-Skill loop. The Generator always fully scans the current working tree from the three Skill roots; additions, deletions, and renames appear as entries increasing, disappearing, and old ids disappearing/new ids appearing, respectively.

Registry file contract

ai-plugins/skill-registry.json is a generated discovery manifest committed in the same Git commit as the Skill tree, not a manually maintained second source of truth. v1 contains only schemaVersion, fixed roots , and each Skill's id、plugin、name、description、version、entry。

• The Node generator uses only built-in modules and does not depend on pnpm install or third-party serializers.
• Read SKILL.md Then first normalize CRLF/CR to LF; the frontmatter parser only supports the narrow subset actually used by this skill, and does not attempt to implement general-purpose YAML. Unknown or invalid structures fail directly.
• To avoid changing existing discovery text at the same time as the infrastructure migration,description 's > / >- / | / |- block all follow the current registry's folding semantics: ordinary lines are joined with spaces, and empty paragraphs retain one newline marker; this is not a general-purpose YAML literal-block implementation.
• Skill id only allows [a-z0-9-], so fixed ordering uses direct string comparison and does not use locale-sensitive sorting.
• The sole definition of canonical JSON is JSON.stringify(registry, null, 2) + "\n"; no serializer patches are maintained for Windows PowerShell 5.1, PowerShell 7, or HTML-sensitive characters.
• Output must be deterministic: UTF-8 without BOM, LF, two-space indentation, fixed attribute order, fixed id ordering, and one trailing newline.
• Must not write timestamps, the current branch, commit SHA, absolute paths, Cloudflare fields, or body copies.
• Do not enumerate references、templates、examples; these files are read on demand by the cloud MCP after a Skill is selected, using the same exact commit SHA.
• Node --check only compares the generator's canonical text and does not write files; stale, missing, duplicate id, invalid frontmatter, invalid version, or invalid entry must all fail with a non-zero exit, and output the --apply repair command; when stale, print the first differing line to aid localization.
• PowerShell -Check/-Apply is only a compatibility alias and must forward to the Node --check/--apply, and must not form a second set of generation logic.
• Skill registry stale, entry/version inconsistent with SKILL.md , or batch publishing repeatedly invoking the generator are all prohibited completion conditions.

CI Workflow Maintenance Contract

The fixed maintenance entry point is .github/workflows/ai-plugins-skill-registry-check.yml. It maintains the read-only -Check contract, and covers the three Skill roots, the registry,.ps1 compatibility entry point,.mjs generator, and the workflow itself; Apply, commit, or push are not allowed.

• CI runs the same Node generator on Ubuntu and Windows, verifying that canonical output does not depend on the operating system.
• CI pins the repository's engines.node minimum supported version; the generator uses only Node built-in modules and does not install project dependencies.
• When only modifying Skill bodies,metadata.version, references/templates/examples, the workflow does not need to be changed; the path filter will trigger the check, and the registry is generated centrally by release Apply.
• When modifying the generator path, CLI arguments, scanned roots, registry schema, minimum Node version, CI permissions, or trigger scope, the workflow must be updated in the same change.
• The release main script's existing static gate continues to validate the wrapper path, read-only -Check and contents: read and other core contracts; .mjs 's own path is explicitly included in the trigger scope by the workflow, and the wrapper must also fail with a non-zero exit when the generator is missing.

Therefore future maintenance does not rely on "remembering one file": routine Skill updates are automatically covered by path-scoped CI; infrastructure contract changes must put the workflow, wrapper, Node generator, and registry in the same change. This does not expand the release main script's responsibilities to parse Node implementation details.

For independent diagnosis, prefer running the Node generator directly:

node ai-plugins/common-tools/skills/release-ai-plugins/scripts/generate-skill-registry.mjs --check

Compatibility with old callers:

powershell -NoProfile -ExecutionPolicy Bypass -File ai-plugins/common-tools/skills/release-ai-plugins/scripts/generate-skill-registry.ps1 -Check

Usage Boundaries

This skill is responsible for plugin version numbers, CHANGELOG, the three-platform manifests, README/installation documentation synchronization, and the generation and validation from the local working tree to the deterministic registry. PowerShell continues to handle release orchestration; Node only takes over the text parsing and JSON canonical ownership of the Skill Registry. This boundary does not expand to rewriting the entire release script, nor does it migrate other manifest JSON files to the new framework along the way.

It is not responsible for GitHub commit SHA parsing, Cloudflare KV/R2 publishing, Worker deployment, MCP session/cache, or the incremental registry database.

When marketplaces are involved, first establish the mapping of "client → marketplace → plugin manifest → published components → install/update/uninstall documentation → real verification commands → cleanup actions". The schemas, hooks, commands, agents, paths, and installation commands of Claude Code, Cursor, and Codex must be verified separately and must not be copied from one another. Static JSON/schema validation is only a preliminary gate; it can be marked as verified only after obtaining a real client CLI or official installation verification. When evidence cannot be obtained due to account, client, or environment limitations, "unverified" must be explicitly recorded.

Version and file contract

• The plugin major version source is .claude-plugin/marketplace.json in metadata.version, and must be synchronized to the Cursor marketplace and the nine plugin.json; the Codex marketplace must not fabricate a version field.
• The Skill's metadata.version evolves independently and is upgraded only when that Skill actually changes.
• Node .mjs generator is the sole canonical writer of the registry; the PowerShell wrapper is only a compatibility adapter; the main release script only treats the registry as an expected artifact in a strict allowlist.
• For the reference field matrix, CHANGELOG format, Codex smoke test, and exact-commit rules, see references/release-contract.md。

Sole entry point

Execute in the repository root:

powershell -NoProfile -ExecutionPolicy Bypass -File ai-plugins/common-tools/skills/release-ai-plugins/scripts/release-ai-plugins.ps1 `
  -Version 10.1.0 -ChangeType minor -Skill release-ai-plugins `
  -Summary "强化发布流程并生成 Skill Registry" -DryRun

After confirming the DryRun output, append -Apply before writing is allowed. For major behavioral changes to this Skill itself, -ChangeType major upgrade this Skill; the plugin major version is still determined separately according to the release level of the entire plugin system.

README and installation documentation

At release time, at least check:

• ai-plugins/docs/README.md
• ai-plugins/docs/use-vercel-skills-install.md
• .claude-plugin/README.md
• .cursor-plugin/README.md
• .agents/plugins/README.md
• ai-plugins/low-frequency-skill/README.md
• root README.md

Installation commands and source paths must use ai-plugins/..., and must not retain claude-code-marketplace/; newly added Skills must also appear in the corresponding plugin root README.

Prohibited completion conditions

• Missing changes to any manifest, marketplace, CHANGELOG, or newly added Skill README.
• The Skill tree has changed but the registry is stale, the registry is not the canonical output of the Node generator, or the entry/version is inconsistent with the real SKILL.md .
• The PowerShell wrapper once again contains JSON serializer, HTML escape, indentation recalculation, or CRLF canonicalization logic.
• Claiming completion based solely on a successful build, JSON parsing, verbal explanation, or git status .
• Using the registry's own fields to impersonate the source commit, or treating CI auto-fix/Cloudflare synchronization as a release step.

Acceptance checklist

• DryRun outputs the Skill, twelve JSON files, three CHANGELOGs, README, and registry plan with zero writes.
• After Apply, both the Node generator Apply and the final Check pass, and the batch is invoked only once each.
• The PowerShell compatibility entry point only forwards parameters and contains no registry text/JSON processing logic.
• .github/workflows/ai-plugins-skill-registry-check.yml Maintains a read-only core contract and explicitly listens for .mjs generator。
• Ubuntu and Windows both pass the registry Check when using the same Node version.
• The registry is parseable, deterministic regeneration produces no diff, and all entries are valid POSIX repo-relative SKILL.md paths.
• The Codex/Claude/Cursor field matrix, installation documentation, and real smoke test evidence have been verified; evidence that could not be obtained is marked as "unverified".
• git diff --check passed, and the workspace contains only the files expected for this change.

Related Resources

• scripts/release-ai-plugins.ps1: main release entry point.
• scripts/generate-skill-registry.mjs: the registry's sole canonical generator.
• scripts/generate-skill-registry.ps1: compatible with legacy -Check/-Apply CLI thin adapter.
• references/release-contract.md: field matrix, CHANGELOG, and smoke test contract.
• Semantic Versioning
• Keep a Changelog