Tools: Plugin and skill tooling (validate structure, version bump, generators)

[krokoko]

Describe the feature

Note: these tools should take into account different clients as needed (Cursor, Claude Code,...) and their respective schemas differences,...

Enhance the tools/ folder with a coherent set of scripts or CLI tools that support the plugin and skill lifecycle:

1. Validate plugin structure — A tool that checks a plugin directory (and optionally the whole repo) against the expected layout: e.g. plugins/<name>/.claude-plugin/plugin.json, plugins/<name>/.mcp.json if present, skills/<skill-name>/SKILL.md, correct frontmatter and schema compliance, and cross-references (marketplace ↔ plugin, plugin ↔ skills). This can extend or wrap existing validate-cross-refs.cjs and lint/manifest checks.

2. Bump plugin and marketplace version — A tool to bump version numbers in a single plugin (e.g. plugin.json and any other versioned manifests) and/or in the marketplace manifest (.claude-plugin/marketplace.json) for a given plugin entry, following semver (patch/minor/major). Avoids manual edits and reduces mistakes.

3. Generate a new plugin — A generator (e.g. node tools/generate-plugin.cjs my-plugin-name) that scaffolds a new plugin directory: plugins/<name>/.claude-plugin/plugin.json, plugins/<name>/.mcp.json (optional), plugins/<name>/README.md stub, and optionally a first skill or placeholder, so contributors can start from a consistent structure.

4. Generate a new skill — A generator (e.g. node tools/generate-skill.cjs my-skill-name or scoped to a plugin) that scaffolds skills/<name>/SKILL.md with valid frontmatter (name, description) and optional references/ placeholder, matching the repo’s skill-frontmatter schema and design guidelines.

All tools must be exposed as mise tasks (e.g. mise run plugin:validate, mise run plugin:bump, mise run plugin:new, mise run skill:new) so CI and contributors use the same interface.

Use Case

• Consistency: New plugins and skills often miss required files or use wrong structure. A validator and generators reduce variation and help contributors get it right the first time.
• Less manual work: Version bumps across plugin.json and marketplace.json are error-prone; a single command (e.g. mise run plugin:bump patch deploy-on-aws) is safer and faster.
• Onboarding: “Run this to create a new plugin/skill” is easier to document and script than “copy this folder and edit these 5 files.”
• CI and pre-commit: A single “validate plugin structure” command can be run in CI and locally (e.g. pre-commit) so structural regressions are caught early.

Proposed Solution

1. Validate plugin structure

   • Add (or extend) a script, e.g. tools/validate-plugin-structure, that:
     • Takes a path (plugin dir or repo root).
     • Checks directory layout (.claude-plugin/plugin.json, skills/*/SKILL.md, optional .mcp.json).
     • Validates manifests against schemas/plugin.schema.json, schemas/skill-frontmatter.schema.json, schemas/mcp.schema.json.
     • Reuses or reimplements existing validate-cross-refs.cjs for marketplace/plugin/skill cross-refs.
     • Exits with non-zero and clear errors if something is wrong.
   • Add a mise task, e.g. plugin:validate or lint:plugin-structure, that runs this (and optionally lint:manifests + lint:cross-refs).

2. Bump plugin / marketplace version

   • Add tools/bump-version (or similar) with usage like:
     • bump-version patch plugins/deploy-on-aws — bumps plugins/deploy-on-aws/.claude-plugin/plugin.json and the matching entry in .claude-plugin/marketplace.json to the next patch.
     • Optional: bump-version minor marketplace for marketplace metadata version only.
   • Implement by parsing JSON, updating version with semver logic (or a small library), and writing back. Ensure formatting is preserved (e.g. no extra newlines).
   • Expose as mise run plugin:bump (or version:bump) with args passed through.

3. Generate new plugin

   • Add tools/generate-plugin <name> that:
     • Creates plugins/<name>/ with .claude-plugin/plugin.json (minimal valid manifest), optional .mcp.json stub, and README.md with standard sections from DESIGN_GUIDELINES or from a template.
     • Optionally creates skills/<first-skill>/SKILL.md stub.
     • Uses schema defaults or minimal valid values so the result passes validate-plugin-structure and lint:manifests.
   • Document in DEVELOPMENT_GUIDE; add mise task plugin:new that runs the generator.

4. Generate new skill

   • Add tools/generate-skill <name> [--plugin path] that:
     • Creates skills/<name>/SKILL.md with YAML frontmatter (name, description placeholder) that satisfies skill-frontmatter.schema.json and design guidelines (e.g. description length).
     • Optionally creates references/.gitkeep or a short references/defaults.md placeholder.
   • If --plugin is given, create the skill under that plugin path; otherwise assume repo root or prompt.
   • Add mise task skill:new.

5. Documentation

   • Update DEVELOPMENT_GUIDE (and optionally README) to describe the new tools and mise tasks. Add a short “Creating a new plugin” / “Adding a new skill” section that points to these commands.

Other Information

• Existing tools: tools/validate-cross-refs.cjs, tools/markdownlint-frontmatter.cjs, tools/markdownlint-skill-length.cjs. The new validator should compose with these rather than duplicate logic.
• Schemas: schemas/plugin.schema.json, schemas/marketplace.schema.json, schemas/mcp.schema.json, schemas/skill-frontmatter.schema.json. Generators must output schema-valid JSON/YAML.
• DESIGN_GUIDELINES and directory structure (e.g. plugins/<name>/.claude-plugin/plugin.json, skills/<skill>/SKILL.md, references/) should be the single source of truth for what “valid” looks like; the validator and generators should align with that.
• Prefer no new runtime dependencies where possible; use Node built-ins or existing dev deps. If a semver helper is needed, consider a small dependency or a minimal implementation.

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change