# Marketplace Author > This skill should be used when the user asks to "create a skill in this repo", "add a skill to claude-code-tools", "add a skill to the marketplace", "update an existing skill", "ship this skill", "bump skill version", or otherwise authors/edits skills in the amitkot/claude-code-tools marketplace. Handles directory layout, version bumps across SKILL.md / plugin.json / marketplace.json, CHANGELOG entries, and the create → commit → push → PR → /plugin → /reload-plugins workflow. - Skill: `amitkot/marketplace-author` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add amitkot/marketplace-author` - Raw SKILL.md: https://api.skillmd.com/api/skills/amitkot/marketplace-author/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: amitkot (https://skillmd.com/u/amitkot) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/amitkot/marketplace-author --- # Marketplace Author Authoring skills in the [`amitkot/claude-code-tools`](https://github.com/amitkot/claude-code-tools) marketplace. The repo is a multi-plugin marketplace; each top-level directory (other than the root) is its own plugin with its own version, and skills live under `/skills//`. ## CRITICAL: Repo path Run all commands from the repository root. If the current working directory is unclear, ask once before guessing. ## Workflow The end-to-end flow for any skill change: 1. **Decide where it goes** — new skill in an existing plugin, new skill in a new plugin, or edit an existing skill. See [Decide placement](#decide-placement). 2. **Branch off `main`** — `git checkout main && git pull && git checkout -b feat/`. Never edit on `main` directly. 3. **Make the changes** — write or edit SKILL.md, references, examples, scripts. Follow the [Skill content rules](#skill-content-rules). 4. **Bump every version that changed** — SKILL.md frontmatter, the plugin's `plugin.json`, the marketplace entry, and the marketplace top-level. See [Version bumps](#version-bumps) — getting this wrong is the most common bug. 5. **Update `CHANGELOG.md`** — at the top, with a new section. See [CHANGELOG format](#changelog-format). 6. **Verify JSON validity** — `jq . .claude-plugin/marketplace.json` and `jq . /.claude-plugin/plugin.json` for every file touched. Don't skip this. 7. **Commit + push** — single commit per skill change is fine; multi-step changes can be separate commits on the same branch. 8. **Open or update the PR** — `gh pr create` (or `gh pr edit` if already open). See [PR template](#pr-template). 9. **Hand off to user for plugin reload** — see [After push](#after-push). The agent cannot run `/plugin` or `/reload-plugins`; the user must. ## Decide placement Pick one: - **Add a skill to an existing plugin** — when the new skill clearly belongs to an existing plugin's domain. Bump only that plugin's version + the marketplace entry + the marketplace top-level. - **Create a new plugin** — when the skill doesn't fit any existing plugin's domain. The marketplace top-level gets a **minor** bump because a new plugin is a new feature. Add a new entry in `.claude-plugin/marketplace.json` `.plugins[]`. - **Edit an existing skill** — bump the existing plugin's version + the marketplace entry + marketplace top-level (patch if behavior unchanged, minor if new functionality). **Always discover the current plugin set before deciding** — don't rely on memory. Run: ```bash jq -r '.plugins[] | "\(.name)\t\(.version)"' .claude-plugin/marketplace.json ``` `references/repo-layout.md` has more discovery commands, including a drift-check that spots stale version pins from a previous half-bump. ## Skill content rules Skills in this repo follow Anthropic's Skill conventions plus a few local norms. For the full canonical Skill authoring guidance — frontmatter, progressive disclosure, imperative voice, trigger-phrase quality — invoke the `plugin-dev:skill-development` skill. Local conventions on top of that: - **Frontmatter `version`** must be present and match the plugin version after a bump. Skills without a version field have appeared, but every new/edited skill should set it. - **Frontmatter `description`** is the trigger. Use specific phrases the user actually says. For models, find an existing skill whose triggering shape is close to the new one — `find . -maxdepth 5 -name SKILL.md | head -20` and skim a few `description:` lines. - **`allowed-tools`** in frontmatter is optional but recommended. Use it to scope tool access (e.g., `Bash, Read, Edit` for an editing skill, `Bash(but *)` to limit a Bash skill to specific commands). - **Imperative voice, not second-person.** "Run X" not "You should run X". - **Lean SKILL.md.** Target 1,500–2,000 words. Move detailed patterns to `references/.md`, working examples to `examples/`, scripts to `scripts/`. - **Filename for the SKILL is always `SKILL.md`** (uppercase). Matches existing repo convention. ## Version bumps There are **four** version fields that may need bumping when a skill changes. Miss any one and the marketplace gets out of sync. | File | Field | When | |---|---|---| | `/skills//SKILL.md` | frontmatter `version:` | Every edit to that skill | | `/.claude-plugin/plugin.json` | top-level `version` | Every edit inside that plugin | | `.claude-plugin/marketplace.json` | the entry whose `name` matches the plugin | Same value as `plugin.json` | | `.claude-plugin/marketplace.json` | top-level `metadata.version` | Every release (patch for fixes, minor for new skill/plugin) | **Convention seen in repo so far:** SKILL.md `version` and the plugin's `version` move together. Always set them to the same value after a bump. **Bump size:** - Patch (`x.y.Z`) — wording fix, doc improvement, behavior unchanged. - Minor (`x.Y.0`) — new skill, new functionality, prominence change strong enough that an existing user might want to know. - Major (`X.0.0`) — breaking change to skill behavior or interface (rare). **Verify after editing:** ```bash jq '.metadata.version' .claude-plugin/marketplace.json jq '.plugins[] | select(.name=="") | .version' .claude-plugin/marketplace.json jq '.version' /.claude-plugin/plugin.json grep '^version:' /skills//SKILL.md ``` All three plugin-level numbers must agree. The marketplace top-level moves on its own cadence. ## CHANGELOG format Top of `CHANGELOG.md`. Insert a new `## [X.Y.Z] - YYYY-MM-DD` section above the previous one. Real entries from the repo are the best template; in particular `[1.14.1]` and `[1.14.0]` show the structure. The minimum useful structure: ```markdown ## [X.Y.Z] - YYYY-MM-DD ### Added | Changed | Fixed #### Plugin () - One bullet per skill or behavior change. Lead with what shipped, follow with the *why*. - Motivating case if there was one — a real session that triggered the change is gold. ### Technical Details - Marketplace: -> - plugin: -> ``` Keep it terse. The "Why" / motivating case is what makes future-you re-read it without yawning. ## PR template ```bash gh pr create --title "" --body "$(cat <<'EOF' ## Summary - Bullet 1: what shipped, in one sentence. - Bullet 2: where it lives (which plugin, which skill). - Bullet 3: version bumps (e.g., "marketplace 1.14.1 -> 1.15.0; new marketplace-author plugin at 0.1.0"). ## Why Brief paragraph: what real session/task drove this. The motivating case from the CHANGELOG can be reused here. ## Test plan - [ ] Render \`SKILL.md\` and confirm structure. - [ ] \`jq\` the manifests to confirm versions. - [ ] Reload the plugin in a real session and trigger the skill. 🤖 Generated with [Claude Code](https://claude.com/claude-code) EOF )" ``` If a PR already exists for the branch, use `gh pr edit --title ... --body ...` instead. ## After push The agent **cannot** invoke `/plugin` or `/reload-plugins` directly — they are user-side Claude Code slash commands. After the push succeeds, write a short message to the user along these lines: > Pushed. To pick up the new version in this session: > 1. Run `/plugin` — confirms the marketplace bump (will say "Updated 1 marketplace (N plugin bumped)"). > 2. Run `/reload-plugins` — actually loads the new SKILL.md from the bumped cache path. > > After reload, I can verify the new version is live by invoking the skill — its base path will be `~/.claude/plugins/cache/amitkot///...`. Once the user has run them, verify by invoking the skill (via the `Skill` tool) and confirming the cache path's version segment matches the bumped value. If the path still shows the old version, the reload didn't take — usually the marketplace cache hasn't refreshed; ask the user to run `/plugin` again. ## Edge cases - **Skill referenced by another skill** — if SKILL.md A links to skill B, version-bump B doesn't require re-bumping A. Cross-references are by name, not version. - **Multiple skills in one PR** — fine. Bump each affected plugin once. Marketplace top-level still gets a single bump (the largest of the contributing bumps). - **Editing this skill itself** — same workflow. `marketplace-author` plugin's own version moves; this skill's frontmatter `version` moves with it. - **`/reload-plugins` doesn't pick up changes** — the marketplace pin (managed by `/plugin`) controls which version the user is on. The agent shouldn't try to fix this; ask the user. ## Reference files - **`references/repo-layout.md`** — full directory structure of the marketplace, what each top-level dir is, where skills live, where versions are pinned. - **`references/version-cheatsheet.md`** — the version-bump matrix as a one-page quick lookup, plus the `jq` verification commands. ## Quick check before declaring done - [ ] SKILL.md frontmatter `version` matches the plugin's `plugin.json` version. - [ ] `plugin.json` version matches the marketplace entry's version. - [ ] Marketplace top-level `metadata.version` bumped. - [ ] CHANGELOG.md has a new top section. - [ ] All touched JSON files are valid (`jq .` runs without error). - [ ] Branch pushed, PR open or updated. - [ ] User has been told to run `/plugin` then `/reload-plugins`.