SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsrock-plugin-release

rock-plugin-release

Agents & models

View repository

Updated 10-16 09:50

About this skill

rock-plugin-release — plugin repository maintenance and release

This skill is used to maintain rock-marketplace this plugin repository. This repository is asingle plugin (rock) + multi-skill structure, and the key constraint is:any change that alters plugin behavior or the externally exposed surface must be synchronized to six locations and version-bumped according to semver. Missing any one of them will cause the version installed users get to be inconsistent with what the marketplace declares, or cause some installation path (npx skills add / /plugin install / /plugin marketplace add) to behave inconsistently—this kind of inconsistency is hard to detect, yet it will genuinely trip up users.

Once you understand this "why," all the rules below become entirely natural.

Six locations that must stay in sync

After each change, check whether these six locations are consistent:

# Location What to change When to change
1 plugins/rock/skills/<skill>/ Actual skill content (SKILL.md + scripts/ + references/) When adding/deleting/updating a skill
2 skills/<skill> Top-level symlink → ../plugins/rock/skills/<skill> Create only when adding a skill; remove when deleting a skill
3 plugins/rock/plugin.json version + description Every change that affects behavior
4 marketplace/registry.json version + description + skills[] + updated_at Every change that affects behavior
5 .claude-plugin/marketplace.json The inner plugin's description(plus the outer marketplace description if involved) When the description changes
6 README.md Structure diagram + "Included skills" table When skills are added/removed or the description changes

The three installation paths each rely on different manifests, so all of them must stay consistent:

  • npx skills add only recognizes the top-level skills/ symlink (location 2)
  • /plugin install goes through plugins/ + registry.json(locations 3 and 4)
  • /plugin marketplace add reads .claude-plugin/marketplace.json(location 5)

Location 5 is especially easy to miss—it is independent of registry.json and contains both the outer marketplace and inner plugin two descriptions. Historically, when adding a skill, only the registry was changed and this was missed, causing the description shown in the marketplace list to lag behind reality. The validation script checks whether it has kept up based on keywords.

Consistency validation (mandatory)

This skill has a built-in validation script;it must be run before and after any change：

python3 .claude/skills/rock-plugin-release/scripts/check_consistency.py

It checks: whether the version number is consistent between plugin.json/registry.json, whether the registry's skills list matches the actual directories, whether each SKILL.md has valid frontmatter, whether the top-level symlinks are complete and point correctly, whether the README mentions all skills, and the updated_at format. Exit code 0 = all consistent, 1 = problems.

The script is read-only and does not modify anything, so you can safely run it repeatedly.After the changes are complete, you must see "consistency check passed" before finishing—this step is the fallback to prevent missed changes.

Version number (semver) determination

The version bump is determined by you (the agent executing the skill) based on the type of changeand suggested, butthe final version number must be confirmed by the user—do not bump it on your own. Determination rules:

This repository's simplified rules (overriding standard semver): only when the skill list has additions or removals(adding a skill or deleting/renaming a skill) do you bump minor; all other changes—updates to skill internal content (including new capabilities, fixes), documentation/README/metadata/hooks adjustments—are always bumped as patch. Unless the user instructs otherwise, do not bump major。

Change type Bump Example
Add skill minor Add rock-eval
Delete / rename skill minor Any change to the skill list bumps minor
Update skill content(enhancements/fixes/new capabilities, without adding or removing skills) patch Add a runbook within a skill, fix a bug, add agent team orchestration
Only change docs/README/metadata patch Adjust description wording, align marketplace.json
Modify hooks behavior patch Unless the user requests higher

When judging, hold to one principle:has the skill list (registry.json in skills[] and the top-level symlinks) changed? If changed, bump minor; if not, bump patch. If unclear, treat it as patch and ask the user to confirm.

When bumping the versionplugin.json and registry.json must be kept in sync—the version in both places must be exactly consistent. This repository has previously had plugin.json=1.0.0 while registry.json=1.1.0 was inconsistent (the validation script was created precisely to catch this kind of problem).

Typical operation flow

Add a skill (e.g. rock-xxx）

  1. Create plugins/rock/skills/rock-xxx/SKILL.md(with valid frontmatter:name matches the directory name,description clearly states the trigger scenarios).
  2. Create the top-level symlink:ln -s ../plugins/rock/skills/rock-xxx skills/rock-xxx(run in the repository root).
  3. plugin.json：description Update if the new skill needs to be reflected; bump version (per the table above, usually minor).
  4. registry.json：skills Add "rock-xxx"to the array; sync version and description; update updated_at(use today's date, format YYYY-MM-DD）。
  5. .claude-plugin/marketplace.json: if the description changed, the inner rock plugin's description (and if necessary the outer marketplace description) must also be kept in sync.
  6. README.md: add one line for the symlink + directory in the structure diagram, and one row in the skills table.
  7. Run the validation script and confirm it passes.

Delete a skill

  1. Delete the plugins/rock/skills/<skill>/ directory.
  2. Delete the top-level symlink skills/<skill>。
  3. registry.json remove that item from the skills array; sync version (a change to the skill list, bump minor); update updated_at。
  4. plugin.json sync version, change description if necessary.
  5. .claude-plugin/marketplace.json: if the description changed, sync the inner (and if necessary outer) description.
  6. README.md Remove the corresponding lines from the structure diagram and table.
  7. Run the validation script.

Update skill content (fix/enhance, without adding or removing)

  1. Change files under plugins/rock/skills/<skill>/ (symlinks follow automatically, no need to touch the top-level skills/）。
  2. Bump patch (skill list unchanged), sync the version of plugin.json and registry.json ; update registry.json in updated_at。
  3. If the description changes substantively, sync the description in all four places:plugin.json / registry.json / .claude-plugin/marketplace.json Inner / README table.
  4. Run the validation script.

Metadata / documentation only

Just run the validation script; version usually gets a patch bump (or stays the same, depending on the user's preference).

updated_at date

registry.json of updated_at inany change that affects version must be refreshed to today. For "today" in the current session, confirm with the user or use a known date; do not fabricate a future date (the validation script will flag future dates as warnings).

Final checklist

Before committing each change, confirm against the following:

  • The validation script outputs "consistency check passed"
  • plugin.json is exactly consistent with the version of registry.json is completely identical to the version of
  • If version changed,registry.json 's updated_at has been refreshed
  • Newly added/removed skills are consistent in the registry skills[], top-level symlinks, and README
  • If description changed,.claude-plugin/marketplace.json has been synced (very easy to miss)
  • The suggested version number and rationale have been explained to the user and confirmed

Per project convention, the commit message format is <type>(<scope>): <description>, e.g. feat(rock): add rock-xxx skill。