plugin-updating

name	plugin-updating
description	Use this skill when the user asks to bump, update, or release a new version of a plugin in the Shopware AI Coding Tools marketplace — phrases like "bump test-writing to 3.8.0", "release a patch for dev-tooling", "update the plugin version". Handles synchronized version bumps across `plugin.json` and every `SKILL.md` frontmatter inside the plugin, plus CHANGELOG entries and template-synced setup-skill version syncing where applicable.
allowed-tools	Read, Edit, Write, Bash, Glob, Grep

Plugin Updating

Handles plugin version management for the Shopware AI Coding Tools marketplace.

Template synchronization for templates/plugin-setup/ and shared shell scripts is covered by .claude/rules/template-sync.md, which activates automatically when a template or consumer file is touched.

Plugin Inventory

Current plugin names and versions:

for f in plugins/*/.claude-plugin/plugin.json; do
  name=$(basename "$(dirname "$(dirname "$f")")")
  ver=$(jq -r .version "$f" 2>/dev/null)
  printf '%s: %s\n' "$name" "$ver"
done

Version Bump

When updating a plugin's version:

Step 1: Identify the plugin

Match the plugin name from the user's request against the names listed above. If the name does not appear there, stop and ask the user which plugin they mean.

Step 2: Determine version bump level

If the user specifies a target version, use it. Otherwise, reason about the changes to determine MAJOR, MINOR, or PATCH.

Core question: "Can users do something they could not do before?"

MAJOR — Consumer behavior must change to keep working
  Plugin renamed or extracted
  Skill invocation model changed
  MCP tool surface rewritten
  Agent names/roles replaced
  Config files require migration

MINOR — New user-facing capability added
  New skill, MCP tool, hook type, agent, command, or environment
  Significant new parameters on existing tools
  New independently-queryable test rule

PATCH — Everything else
  Bug fixes, refinements, internal refactoring
  Description/docs improvements
  Validation/guard additions to existing features
  Removing deprecated internals

Watch for these traps:

• "Added" does not always mean MINOR — adding validation to an existing feature is PATCH (same capability, better quality)
• "Breaking" in a description does not always mean MAJOR — if the orchestrator absorbs the change transparently, consumers are unaffected
• Batch additions that individually seem incremental can collectively warrant MINOR when they form a cohesive new capability

For detailed triggers, public API definitions, and edge cases see references/version-bump-reasoning.md.

Step 3: Bump plugin.json and all SKILL.md versions

Run the bundled helper script:

bash "${CLAUDE_SKILL_DIR}/scripts/bump-plugin-version.sh" <plugin> <new-version>

It updates plugins/<plugin>/.claude-plugin/plugin.json (surgical text replacement that preserves formatting) and rewrites the version: field in every plugins/<plugin>/skills/*/SKILL.md frontmatter. Do not edit these files by hand.

Step 4: Update CHANGELOG.md

Read the existing plugins/<plugin>/CHANGELOG.md. Add a new version section at the top following the existing format.

Step 5: Stage changes

git add plugins/<plugin>

Do not commit. The user will commit when ready.

Step 6: Sync the setup skill version (if applicable)

If the plugin has a SETUP.md, the version field in plugins/<plugin>/skills/setting-up/SKILL.md must match the new plugin version. Update it in place — leave the rest of the frontmatter and body alone. See .claude/rules/template-sync.md for the body-sync workflow.

SETUP.md Format Reference

Plugins that participate in the setup skill pattern have a SETUP.md at their root with these required sections:

Heading	Level	Purpose
# {Plugin Name} Setup	H1	Plugin name
## Prerequisites	H2	External tools to check
### {tool name}	H3	One per tool: Check, Install, Required by
## Configuration Files	H2	Config files to create
### {filename}	H3	One per file: Required, Location
#### Setup Questions	H4	Numbered questions with options
#### Minimal Config	H4	Simplest valid config (code block)
## Validation	H2	Steps to verify setup
## Post-Setup	H2	Restart requirements, next steps