--- 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 rule, fix a typo, sharpen wording). - **Add a new plugin** (a new vertical or a new focused capability). - **Add a skill or rule** 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 ` to follow CI verdicts. Do not run validators or linters locally — 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 Every plugin lives under `plugins//`: ``` plugins// skills/ -usage/ SKILL.md # routing entry point, always present / SKILL.md .cursor-plugin/plugin.json .claude-plugin/plugin.json README.md CHANGELOG.md .mcp.json # only if the plugin drives an MCP server rules/ # optional cursor-rules/ # generated from rules/, never hand-edited claude-rules/ # generated from rules/, never hand-edited ``` Notes: - **Both manifests must agree on `name`, `displayName`, `description`, `version`.** Cursor reads `.cursor-plugin/plugin.json` (`rules: "./cursor-rules/"`), Claude Code reads `.claude-plugin/plugin.json` (`rules: "./claude-rules/"`). If your plugin has no `rules/`, omit the `rules` key from both manifests. - **Every plugin ships `skills/-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. - **Skills and rules are both first-class.** Use the one that fits — skills for routing and workflows, rules for guidance the model should apply automatically (path-scoped via `globs`, or agent-requested via a precise `description`). Mark skills that should never auto-fire on inferred intent with `disable-model-invocation: true`. - **Don't hand-edit `cursor-rules/` or `claude-rules/`.** They are generated by `python scripts/generate-rules.py` from `rules/*.md`. Commit source and generated files together. - **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 — `-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 the three-way 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//` containing a single `SKILL.md`. - Frontmatter `name:` must equal the folder name. - `description` should include "Use when …" with concrete trigger terms. - Add `argument-hint: ""` 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. Skills are also distributed through `vercel-labs/skills` as a cross-client install path (`npx skills add leancodepl/ai-plugins --skill -a `, supports Cursor, Claude Code, and 50+ other agents). When authoring: keep `name:` globally unique (the CLI uses a flat namespace, no plugin scoping), make `description:` self-contained, and don't assume the plugin's `rules/` are present at runtime — a `-usage` skill should be useful standalone. ## Rule conventions - Author in `rules/`. A non-empty `description` is mandatory; `globs` is optional. - Scope each rule with `globs` (path-scoped) or with a precise `description` alone (agent-requested); never `alwaysApply: true`. See AGENTS.md "Rule authoring" for which to pick. - Run `python scripts/generate-rules.py` after any change. Commit source and generated files together. - Do not hand-edit anything under `cursor-rules/` or `claude-rules/`. ## Path 1 — tweak an existing plugin 1. Open `plugins//` and find the file to change. 2. Edit it. Keep the change focused — one PR per concern. 3. If you edited any `rules/*.md`, regenerate locally with `python scripts/generate-rules.py`. (Python is the only tool a contributor should need locally; CI handles the rest.) 4. Bump the plugin's `version` in **both** `.cursor-plugin/plugin.json` and `.claude-plugin/plugin.json`. PATCH for wording / docs, MINOR for new behavior, MAJOR for renames or removals. See "Versioning" below for the full rules and what each client does with the bump. 5. Add a bullet to `plugins//CHANGELOG.md` under a new top entry matching the new version. 6. Update `plugins//README.md` if the change affects what the plugin lists. 7. Branch, commit, push, open a PR — see "Open the PR" below. ## Path 2 — add a skill or rule to an existing plugin Same as Path 1, plus: - New skill → `plugins//skills//SKILL.md` with frontmatter `name: ` 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/"`) to the plugin's `skills` array in `.claude-plugin/marketplace.json` — that's the manifest `vercel-labs/skills` reads for cross-client distribution. - New rule → `plugins//rules/.md` with `description` and concrete `globs`. Never set `alwaysApply: true`. After saving, run `python scripts/generate-rules.py`. - Mention the new asset in `plugins//README.md`. ## Path 3 — add a new plugin 1. Pick a kebab-case name with a prefix that reflects scope: - `-` when the plugin is tied to a specific vertical: `backend-…`, `flutter-…`, `pmo-…`. - `lean-` when the plugin is cross-vertical or has no natural vertical (matches `lean-core`, `lean-anti-ai-slop`). 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//` with at minimum: - `skills/-usage/SKILL.md` - `.cursor-plugin/plugin.json` - `.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"` and `stability: "experimental"`. 4. Register the plugin in **both** marketplace files: - `.cursor-plugin/marketplace.json` — append to `plugins[]`. - `.claude-plugin/marketplace.json` — append to `plugins[]` and include a `skills` array on the entry listing every skill's plugin-relative path (e.g. `"./skills/-usage"`). `vercel-labs/skills` reads this for cross-client distribution; without it the CLI falls back to a recursive search. - Bumping `metadata.version` on either file is convention-only — see "Versioning" below. 5. Add the plugin to the human-readable overview in the root `README.md` under the matching vertical group. 6. Branch, commit, push, open a PR. ## Versioning Per-plugin semver. Both `plugin.json` files must carry the same `version`. - **PATCH** — wording, doc, regenerated output only. - **MINOR** — new skill, new rule, new behavior; expanded scope; additive change. - **MAJOR** — rename, removal, or reversal of existing guidance. Optional `stability` field on each plugin: `experimental`, `beta`, or `stable`. ### What clients actually do with these versions This trips contributors up — be explicit when walking the user through. - **Claude Code**: per-plugin `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".) - **Cursor**: per-plugin `plugin.json.version` is **decorative**. Cursor pins installs to the git commit SHA internally, so any new commit on the tracked branch is a new version regardless of the string. (See https://cursor.com/docs/reference/plugins.) - **`marketplace.json.metadata.version`** in either client: **decorative** — no documented refresh, cache, or update behavior. Bump by convention when plugins are added/removed/renamed if you want, but nothing depends on it. ### How users get updates (no reinstall needed) - **Claude Code**: user runs `/plugin update` (or auto-update fires if they enabled it). Pulls the latest version using the cache key above. - **Cursor**: a GitHub-push webhook re-indexes the marketplace on Cursor's side; clients pull on next refresh (window focus or periodic). If a specific user is stuck, the working fallback is Settings → Plugins → manual **Refresh**, and as a last resort clearing `~/.cursor/plugins/cache///` and reinstalling. Forum reports show Cursor's auto-refresh can be flaky in practice. No client requires a full reinstall on a normal version bump. ## Open the PR ``` git checkout -b git add -A git commit -m ": " git push -u origin HEAD gh pr create --repo leancodepl/ai-plugins \ --title ": " \ --body "" ``` 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 three checks, all on GitHub Actions: - **Structure** — manifest fields, marketplace registration, file shape. - **Generated rules in sync** — fails if you changed a rule but forgot to regenerate. - **Lint** — Go and Python formatters/linters for repo tooling. Contributors do not need to install Go locally. Watch the verdicts with: ``` gh pr checks ``` A green PR means the shape is correct. Review focuses on guidance quality, not boilerplate. ## What NOT to do - Do not hand-edit `cursor-rules/` or `claude-rules/`. They are generated. - 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 rule or skill claim, leave it out. - Do not enumerate plugins or clients from memory — read the source of truth.