marketplace-author

Marketplace Author

Authoring skills in the 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 <plugin>/skills/<skill-name>/.

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.
2. Branch off main — git checkout main && git pull && git checkout -b feat/<short-slug>. Never edit on main directly.
3. Make the changes — write or edit SKILL.md, references, examples, scripts. Follow the 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 — getting this wrong is the most common bug.
5. Update CHANGELOG.md — at the top, with a new section. See CHANGELOG format.
6. Verify JSON validity — jq . .claude-plugin/marketplace.json and jq . <plugin>/.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.
9. Hand off to user for plugin reload — see 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:

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/<topic>.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
<plugin>/skills/<skill>/SKILL.md	frontmatter version:	Every edit to that skill
<plugin>/.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:

jq '.metadata.version' .claude-plugin/marketplace.json
jq '.plugins[] | select(.name=="<plugin>") | .version' .claude-plugin/marketplace.json
jq '.version' <plugin>/.claude-plugin/plugin.json
grep '^version:' <plugin>/skills/<skill>/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:

## [X.Y.Z] - YYYY-MM-DD

### Added | Changed | Fixed

#### <Plugin Name> Plugin (<plugin-version>)
- 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: <prev> -> <new>
- <Plugin Name> plugin: <prev> -> <new>

Keep it terse. The "Why" / motivating case is what makes future-you re-read it without yawning.

PR template

gh pr create --title "<conventional-style title under 70 chars>" --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 <num> --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/<plugin>/<new-version>/....

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.