Scripts

Utility scripts for maintaining the Bitwarden AI Plugins Marketplace.

bump-plugin-version.sh - Automate version bumping
validate-plugin-structure.sh - Validate plugin structure
validate-marketplace.sh - Validate marketplace.json
validate-version-bump.sh - Validate version bumps for changed plugins
GitHub Actions Integration
Local Development Workflow

bump-plugin-version.sh

Automates version bumping across all required plugin files.

Usage

./scripts/bump-plugin-version.sh <plugin-name> <new-version>

Examples

# Bump patch version for a bug fix
./scripts/bump-plugin-version.sh bitwarden-code-review 1.3.4

# Bump minor version for new features
./scripts/bump-plugin-version.sh claude-retrospective 1.1.0

# Bump major version for breaking changes
./scripts/bump-plugin-version.sh claude-config-validator 2.0.0

What It Does

The script automatically updates version numbers in:

.claude-plugin/marketplace.json - Marketplace registration
plugins/<plugin-name>/.claude-plugin/plugin.json - Plugin manifest
README.md - Plugin catalog table
plugins/<plugin-name>/agents/*/AGENT.md - All agent YAML frontmatter (if agents exist)

Features

Input validation: Ensures plugin name and version format are valid
Existence checks: Verifies plugin and files exist before making changes
Confirmation prompt: Asks for confirmation before applying changes
Colored output: Clear visual feedback with success/error indicators
Agent detection: Automatically finds and updates all agent files
Helpful reminders: Reminds you to update changelog after version bump

After Running

After a successful version bump, you must:

Update plugins/<plugin-name>/CHANGELOG.md with an entry for the new version
Follow Keep a Changelog format
Commit all changes together in the same PR

Requirements

jq - JSON processor (install with brew install jq on macOS)
sed - Stream editor (usually pre-installed)
bash 4.0 or higher

Error Handling

The script validates:

Plugin name format (alphanumeric, hyphens, underscores only)
Semantic version format (must be X.Y.Z)
Plugin directory existence
Required file existence
JSON syntax after updates

If any validation fails, the script exits with an error message and no changes are made.

validate-plugin-structure.sh

Validates the structure and content of individual plugins.

Usage

bash scripts/validate-plugin-structure.sh
# or
./scripts/validate-plugin-structure.sh

Checks Performed

Plugin directory structure - Verifies required directories exist
Required files - Checks for:
- .claude-plugin/plugin.json - Plugin manifest
- README.md - Plugin documentation
- CHANGELOG.md - Version history
Optional directories - Validates commands/, agents/, skills/, hooks/
Agent definitions - Ensures each agent has AGENT.md with valid YAML frontmatter
Skill definitions - Ensures each skill has SKILL.md with valid YAML frontmatter
Command definitions - Checks for .md files in command directories
README content - Warns if missing key sections (description, usage, installation)
CHANGELOG format - Warns if not following Keep a Changelog format

Output

The script provides colored output:

🔍 Blue headers for sections
✅ Green for successful validations
❌ Red for errors (will fail the check)
⚠️ Yellow for warnings (won't fail the check)

Exit Codes

0 - All validations passed
1 - One or more validations failed

Example Output

🔍 Validating plugin structure...

📦 Validating bitwarden-code-review...
  ✅ Structure is valid

📦 Validating claude-config-validator...
  ❌ Missing required file: CHANGELOG.md
  ⚠️ CHANGELOG.md does not exist

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Validation Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total plugins checked: 2
Total errors: 1
Total warnings: 1

❌ Plugin validation failed

validate-marketplace.sh

Validates the marketplace.json file and checks consistency with actual plugins.

Usage

bash scripts/validate-marketplace.sh
# or
./scripts/validate-marketplace.sh

Checks Performed

Marketplace structure - Validates required fields:
- name - Marketplace identifier
- owner - Owner information (must have name field)
- plugins - Array of plugin entries
Plugin entries - Checks each plugin has:
- name - Plugin identifier
- source - Path to plugin directory
- description - Plugin description
- version - Semantic version (X.Y.Z)
Plugin existence - Verifies plugin directories actually exist
Version consistency - Ensures versions match between:
- marketplace.json
- plugin.json files
Name consistency - Ensures names match in marketplace and plugin manifests
README catalog - Verifies each plugin appears in the README.md plugin catalog table with the correct version
Completeness - Warns if plugins exist but aren't listed in marketplace

Output

The script provides colored output:

🔍 Blue headers for sections
✅ Green for successful validations
❌ Red for errors

Exit Codes

0 - All validations passed
1 - One or more validations failed

Example Output

🔍 Validating marketplace.json...

📋 Checking marketplace structure...
  ✅ Structure is valid

📦 Checking plugin entries...
  ✅ claude-retrospective
  ✅ claude-config-validator
  ✅ bitwarden-code-review

🔄 Checking consistency with plugin files...
  ✅ All plugins are consistent

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Validation Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total plugins in marketplace: 3
Total errors found: 0

✅ marketplace.json is valid

validate-version-bump.sh

Validates that changed plugins include a version bump and changelog update.

Usage

# Compare against a base branch
./scripts/validate-version-bump.sh origin/main plugin-name

# Check multiple plugins
./scripts/validate-version-bump.sh origin/main bitwarden-code-review bitwarden-software-engineer

# Accept plugins/ path prefix
./scripts/validate-version-bump.sh origin/main plugins/bitwarden-code-review

Checks Performed

Version bump - Compares the version in plugin.json between the base ref and HEAD. The new version must be strictly greater than the base version (any of major, minor, or patch).
Changelog update - Verifies that CHANGELOG.md was modified in the diff between the base ref and HEAD.

Exit Codes

0 - All plugins have proper version bumps
1 - One or more plugins are missing a version bump or changelog update

Example Output

🔍 Validating version bumps for changed plugins...

📦 Checking bitwarden-software-engineer...
  ❌ bitwarden-software-engineer: Version not bumped (still 0.3.0). Plugin component files were changed — run ./scripts/bump-plugin-version.sh bitwarden-software-engineer <new-version>
  ❌ bitwarden-software-engineer: CHANGELOG.md not updated. Add an entry describing what changed.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Version Bump Validation Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Plugins checked: 1
Total errors: 2

❌ Version bump validation failed with 2 error(s)

Plugin Requirements Reference

Required Files

Every plugin must include:

.claude-plugin/plugin.json - Plugin manifest with:

{
  "name": "plugin-name",
  "version": "X.Y.Z",
  "description": "Plugin description",
  "author": {
    "name": "Author Name"
  }
}

README.md - Documentation including:
- Description/overview
- Usage examples
- Installation instructions
CHANGELOG.md - Version history following Keep a Changelog format

Version Format

All versions must follow semantic versioning:

Format: MAJOR.MINOR.PATCH (e.g., 1.0.0, 2.3.4)
Numbers only (no 'v' prefix)
Must be consistent across all files

See Semantic Versioning for guidelines:

MAJOR - Breaking changes
MINOR - New features, backward-compatible
PATCH - Bug fixes, documentation updates

Agent Requirements

If your plugin includes agents, each AGENT.md must have valid YAML frontmatter:

---
name: agent-name
description: Agent description
version: X.Y.Z
tools:
  - tool1
  - tool2
---

Skill Requirements

If your plugin includes skills, each SKILL.md must have valid YAML frontmatter:

---
name: skill-name
description: Skill description
---

Security Requirements

❌ No hardcoded credentials or API keys
❌ No committed .env files
✅ Proper input validation in scripts
✅ Use environment variables for sensitive data

Troubleshooting

Common Issues

"Missing required file: plugin.json"

Ensure .claude-plugin/plugin.json exists in your plugin directory
Check the file path matches the expected structure

"Invalid version format"

Use semantic versioning: 1.0.0 not v1.0 or 1.0
No prefixes or suffixes allowed

"Version mismatch"

Ensure versions match in:
- plugin.json
- marketplace.json
- AGENT.md files (if agents exist)
Use the version bump script: ./scripts/bump-plugin-version.sh plugin-name X.Y.Z

"Version not bumped" / "CHANGELOG.md not updated"

Plugin component files (agents, skills, hooks) were changed without a version bump
Run ./scripts/bump-plugin-version.sh <plugin-name> <new-version> to bump all version files
Add a changelog entry under the appropriate category (Added, Changed, Fixed, etc.)
Commit the version bump alongside your code changes

"Missing YAML frontmatter"

Ensure files start with --- and end with ---
Include all required fields
Validate YAML syntax at YAML Lint

"Invalid JSON"

Validate JSON syntax using jq:
```
jq empty your-file.json
```
Or use an online validator like JSONLint

"Plugin is not listed in the README.md plugin catalog table"

Add a row to the plugin catalog table in README.md
Format: | [plugin-name](plugins/plugin-name/) | X.Y.Z | Description |
Use the version bump script to keep all files in sync: ./scripts/bump-plugin-version.sh

"README catalog version mismatch"

Run the version bump script to update all files at once: ./scripts/bump-plugin-version.sh plugin-name X.Y.Z
Or manually update the version in the README.md plugin catalog table

"Plugin exists but not in marketplace"

Add an entry to .claude-plugin/marketplace.json
Ensure the source path is correct

Resources

Official Documentation

Claude Code Plugins Reference - Official plugin API reference
Plugin Marketplaces - Marketplace structure
Plugin Structure - Plugin organization

Standards & Best Practices

Keep a Changelog - Changelog format
Semantic Versioning - Version numbering
Bitwarden Contributing Guidelines - Contribution standards

Best Practices from Research

Based on research into Claude Code plugin validation and best practices:

Automated validation - Run lints and tests that gate every change; CI runs should be non-destructive first (Claude Code Plugin Best Practices)
Hooks for quality checks - Automate type checks, security validation, and code formatting using hooks (Claude Code: Part 8 - Hooks)
Security scanning - Scan generated code for vulnerabilities and validate against security policies (Claude Desktop Developer Best Practices)
Progressive constraints - Start in read-only mode; allow writes only after tests pass (Claude Code 2.0 Best Practices)
Schema validation - Validate against official marketplace schema at https://anthropic.com/claude-code/marketplace.schema.json (Plugin marketplaces)

Contributing

When modifying validation scripts:

Test locally before committing
Document any new validation checks in this README
Update workflow file if adding new checks
Follow existing patterns for consistency
Consider backwards compatibility

For questions or issues, refer to the main repository README or contact the maintainers.

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Scripts

Table of Contents

bump-plugin-version.sh

Usage

Examples

What It Does

Features

After Running

Requirements

Error Handling

validate-plugin-structure.sh

Usage

Checks Performed

Output

Exit Codes

Example Output

validate-marketplace.sh

Usage

Checks Performed

Output

Exit Codes

Example Output

validate-version-bump.sh

Usage

Checks Performed

Exit Codes

Example Output

Plugin Requirements Reference

Required Files

Version Format

Agent Requirements

Skill Requirements

Security Requirements

Troubleshooting

Common Issues

Resources

Official Documentation

Standards & Best Practices

Best Practices from Research

Contributing