lean-contribute

name	lean-contribute
description	Walk a contributor through proposing a change to the LeanCode AI plugins marketplace — tweaking an existing plugin, adding a new one, and opening a PR against `leancodepl/ai-plugins`. Use when the user invokes `/lean-contribute`, asks how to contribute, asks how to add a plugin, or wants to propose an improvement. Manual-only entry point — does not auto-fire.
disable-model-invocation	true

Contribute to LeanCode AI plugins

The canonical contributor reference for leancodepl/ai-plugins. The repo's CONTRIBUTING.md is a thin pointer at this file. Read top-to-bottom for the full picture, or jump to the relevant path.

How to respond

1. Ask what kind of change the user wants:
   • Tweak an existing plugin (improve a skill or reference, fix a typo, sharpen wording).
   • Add a new plugin (a new focused capability).
   • Add a skill or reference to an existing plugin.
2. Walk through the matching path below. Print exact commands. Do not run git, gh, or any state-changing command on the contributor's behalf unless they explicitly ask.
3. After the PR is pushed, point the user at gh pr checks <pr-number> to follow CI verdicts. CI is the source of truth.

Reading the current state

Before answering questions about what plugins or clients exist, read the source of truth:

• Plugins: .claude-plugin/marketplace.json at the repo root.
• Supported clients: the "Supported clients" section of the root README.md.

Do not enumerate plugins or clients from memory.

Where to work

All contribution work happens inside a local clone of leancodepl/ai-plugins, not in a consumer project. If the contributor does not have the clone yet:

gh repo clone leancodepl/ai-plugins
cd ai-plugins

If gh is not installed, point them at https://cli.github.com/ or, for a fully GUI flow, https://desktop.github.com/.

Plugin shape

This repo ships Claude Code plugins. Every plugin lives under plugins/<plugin-name>/:

plugins/<plugin-name>/
  skills/
    <plugin-name>-usage/
      SKILL.md              # routing entry point, always present
      references/           # optional reference material the skill loads on demand
        <topic>.md
    <other-skill>/
      SKILL.md
  .claude-plugin/plugin.json
  README.md
  CHANGELOG.md
  .mcp.json                 # only if the plugin drives an MCP server

Notes:

• .claude-plugin/plugin.json is the manifest. It carries name, displayName, description, version, and points skills at ./skills/. It has no rules key — Claude Code does not recognize one.
• Every plugin ships skills/<plugin-name>-usage/SKILL.md as its routing entry point. The skill name: in frontmatter must exactly match the folder name.
• Skill names are unique across the whole marketplace. If your slug could collide, prefix it with the plugin name.
• Everything ships as a skill. Use a workflow skill for a step-by-step action, and references/*.md alongside a SKILL.md for convention-style guidance the model should apply. Mark skills that should never auto-fire on inferred intent with disable-model-invocation: true.
• Reference files are edited directly — SKILL.md lists them under a "Reach for these references" section so Claude knows when to load each. They load only when referenced, so detailed material costs nothing until needed.
• Setup and configuration docs have one canonical home: the plugin README.md. Anything a user has to do to make the plugin work (env vars, dependencies, post-install steps, sample directories, MCP servers, etc.) lives there in full. Other surfaces — <plugin>-usage/SKILL.md, other skills, top-level README bullets — reference the plugin README rather than restating the setup. The single exception is a skill that needs to print setup inline at runtime (because the user is not on GitHub at that moment); when you keep an inline copy for that reason, say so in the skill so the next contributor does not assume the duplication is accidental. This rule prevents drift between README.md, the usage SKILL, and any workhorse SKILL that all happen to mention the same env var.

Skill conventions

• Each skill is a folder skills/<slug>/ containing a single SKILL.md.
• Frontmatter name: must equal the folder name.
• description should include "Use when …" with concrete trigger terms.
• Add argument-hint: "<args>" when the skill takes arguments.
• Add disable-model-invocation: true when the skill should never auto-fire on inferred intent.
• Skill names must be unique across the whole marketplace.

Reference-material conventions

• Convention-style guidance lives in skills/<plugin-name>-usage/references/*.md as plain markdown (no frontmatter).
• List each reference file in the owning SKILL.md under a "Reach for these references" section, with a one-line note on what it covers, so Claude knows when to load it.
• A workhorse skill in the same plugin can cite a usage skill's reference with a relative path (e.g. ../<plugin-name>-usage/references/<topic>.md).

Path 1 — tweak an existing plugin

1. Open plugins/<plugin-name>/ and find the file to change.
2. Edit it. Keep the change focused — one PR per concern.
3. Bump the plugin's version in .claude-plugin/plugin.json. PATCH for wording / docs, MINOR for new behavior, MAJOR for renames or removals. See "Versioning" below for what Claude Code does with the bump.
4. Add a bullet to plugins/<plugin-name>/CHANGELOG.md under a new top entry matching the new version.
5. Update plugins/<plugin-name>/README.md if the change affects what the plugin lists.
6. Branch, commit, push, open a PR — see "Open the PR" below.

Path 2 — add a skill or reference to an existing plugin

Same as Path 1, plus:

• New skill → plugins/<plugin-name>/skills/<skill-slug>/SKILL.md with frontmatter name: <skill-slug> and a description that includes "Use when …" with concrete trigger terms. Add disable-model-invocation: true if it should not auto-fire. Also append the skill's plugin-relative path (e.g. "./skills/<skill-slug>") to the plugin's skills array in .claude-plugin/marketplace.json.
• New reference → plugins/<plugin-name>/skills/<plugin-name>-usage/references/<topic>.md (plain markdown), and list it under "Reach for these references" in that SKILL.md.
• Mention the new asset in plugins/<plugin-name>/README.md.

Path 3 — add a new plugin

1. Pick a kebab-case name with a prefix that reflects scope:

   • flutter-<scope> for a Flutter capability (the bulk of this marketplace).
   • lean-<scope> for a meta or repo-wide plugin with no natural domain (matches lean-core).

   Do not ship a bare slug. The prefix is what makes the marketplace listing predictable — users remember prefixes plus autocomplete, not full slugs.

2. Create plugins/<plugin-name>/ with at minimum:

   • skills/<plugin-name>-usage/SKILL.md
   • .claude-plugin/plugin.json
   • README.md
   • CHANGELOG.md with a 0.1.0 entry

3. Copy manifest shape from a sibling plugin. Set version: "0.1.0".

4. Register the plugin in .claude-plugin/marketplace.json — append to plugins[] with name, source, description, and a skills array listing every skill's plugin-relative path (e.g. "./skills/<plugin-name>-usage").

5. Add the plugin to the human-readable overview in the root README.md under the matching group.

6. Branch, commit, push, open a PR.

Versioning

Per-plugin semver in .claude-plugin/plugin.json.

• PATCH — wording, doc only.
• MINOR — new skill, new reference, new behavior; expanded scope; additive change.
• MAJOR — rename, removal, or reversal of existing guidance.

Keep plugin.json to fields in the official Claude Code plugin manifest schema — CI runs claude plugin validate . --strict, which fails on unrecognized fields.

What Claude Code does with the version

plugin.json.version is the cache key for /plugin update. Bumping it is load-bearing. If you ship changes without bumping, users running /plugin update see "already at the latest version" and never get your change. Bump it on every release. (See https://code.claude.com/docs/en/plugins-reference.md, "Version management".)

marketplace.json.metadata.version is decorative — no documented refresh or update behavior. Bump by convention when plugins are added/removed/renamed if you want, but nothing depends on it.

Users get updates by running /plugin update (or auto-update if enabled) — no reinstall needed on a normal version bump.

Open the PR

git checkout -b <short-slug>
git add -A
git commit -m "<plugin-name>: <what changed>"
git push -u origin HEAD
gh pr create --repo leancodepl/ai-plugins \
  --title "<plugin-name>: <what changed>" \
  --body "<one paragraph: what and why; mention any breaking changes>"

If gh is not installed, push the branch and open the PR via the GitHub web UI. The PR description should answer: what changed, why, and which plugins it touches.

CI is the safety net

Every PR runs on GitHub Actions:

• Structure — manifest fields, marketplace registration, file shape (go run ./cmd/validate-plugins).
• Lint — Go formatters/linters for repo tooling.

Contributors do not need to install Go locally — CI runs it. Watch the verdicts with:

gh pr checks <pr-number>

A green PR means the shape is correct. Review focuses on guidance quality, not boilerplate.

What NOT to do

• Do not bundle changes across multiple plugins in a single PR. One plugin per PR keeps review tight.
• Do not ship a Claude Code-visible change without bumping plugin.json.version — see "Versioning" above.
• Do not invent guidance that is not grounded in real usage. If you cannot point at a concrete reason for a skill or reference claim, leave it out.
• Do not enumerate plugins or clients from memory — read the source of truth.