# Lean Contribute > 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. - Skill: `leancodepl/lean-contribute` (Agent Skill) - Install (CLI): `npx skillmds@latest add leancodepl/lean-contribute` - Raw SKILL.md: https://api.skillmd.com/api/skills/leancodepl/lean-contribute/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: leancodepl (https://skillmd.com/u/leancodepl) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/leancodepl/lean-contribute --- # 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 ` 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//`: ``` plugins// skills/ -usage/ SKILL.md # routing entry point, always present references/ # optional reference material the skill loads on demand .md / 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/-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 — `-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//` 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. ## Reference-material conventions - Convention-style guidance lives in `skills/-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. `../-usage/references/.md`). ## 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. 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//CHANGELOG.md` under a new top entry matching the new version. 5. Update `plugins//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//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`. - New reference → `plugins//skills/-usage/references/.md` (plain markdown), and list it under "Reach for these references" in that `SKILL.md`. - 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: - `flutter-` for a Flutter capability (the bulk of this marketplace). - `lean-` 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//` with at minimum: - `skills/-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/-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 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 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 ``` 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.