plugin-dev: friction points - Missing CLI syntax, TTY awareness, /plugin guidance, and version bumping documentation

Summary

Plugins are awesome. I've been writing some to help Claude with very specific tool knowledge. In the course of that work, I hit a few friction points that it would be great if they were covered in plugin-dev plugin's knowledge base.

1. claude plugin vs claude plugins (singular vs plural)

Claude consistently generates claude plugins list, claude plugins install, etc. The correct subcommand is claude plugin (singular). This generalizes to Claude doesn't seem to know its own CLI commands or flags, but I hit it trying to manage plugin setups across hosts.

2. TTY requirement for CLI commands?

Claude loves to try and run the claude plugin command, which it seems it can't — I imagine because it needs a TTY? There's no mention of this limitation anywhere in plugin-dev, and no guidance to tell users to run these in a separate terminal. Which leads into:

3. /plugin slash command as the session-safe alternative

The /plugin slash command works inside a Claude Code session without a TTY. plugin-dev's README uses /plugin install and /plugin update in its install instructions. I think the challenge is it's not framed as "use this instead of the CLI when you're inside a session." In my experience Claude always ignores /plugin in favor of the cli.

4. Version bumping requirements

manifest-reference.md has one line: "Bump version on changes: Follow semantic versioning." In practice, this is the single biggest pain for me.

• The plugin manager uses the version field as a cache key
• If you change plugin files without bumping the version, users who already have it cached never see the update
• You must bump in both plugin.json and the marketplace registry file
• This needs to happen on every commit that touches plugin files

I spun for a long time debugging "my plugin changes aren't showing up" before figuring this out. It also seems that the cache really doesn't like repeat installs of the "same version" of the plugin with differing files.

5. Syntax for claude plugin marketplace add

The command takes owner/repo format directly. No github: prefix, no full URL. This isn't documented anywhere, which wouldn't be a problem except Claude repeatedly inferred github:owner/repo from conventions in other tools (Cargo, npm, etc.). Here's an example generated script snippet that broke:

# Wrong — Claude generated this
claude plugin marketplace add "github:metcalfc/claude-plugin"
# Should have generated this
claude plugin marketplace add metcalfc/claude-plugin

My workarounds/fixes

I created a claude-code-setup plugin that augments plugin-dev. Claude picked the name and of course it conflicts with an upstream.

• claude-cli-knowledge skill — Correct CLI syntax, TTY rules, /plugin equivalence table, version bumping rules
• PreToolUse hook — Catches claude plugins (plural), github: prefix, TTY-requiring commands, and deprecated flags before execution
• CLI reference — Complete flag and subcommand reference
• Plugin lifecycle reference — Cache flow, version resolution, common debugging

Patches welcome?

We're happy to submit a PR adding any of these to the existing skill set (or as a new skill). If you'd prefer to handle it internally, no worries — I'll keep maintaining my supplemental plugin and can close this issue.

Either way, wanted to surface the friction in case it's useful signal.