fix(kyberforge): clarify skill descriptions, trim gotchas, and clean up marketplace-author

## Why
Several small quality issues accumulated across plugin-author and
marketplace-author: the plugin-author description was ambiguous about
scope, the ADD flow asked an unnecessary clarifying question when local
path is the obvious default, VALIDATE had redundant wording already
captured inline, the keywords field was missing from the validation
checklist, and tests/README.md was a placeholder with nothing to test.

## Implementation Notes
- plugin-author: tightened description scope to "inside those
  directories"; added `keywords` identical-in-both-manifests check to
  VALIDATE checklist.
- marketplace-author: moved reserved-prefix constraint from gotchas
  into the ADD checklist item; replaced the four-option prompt with a
  default+escape-hatch ("I'll treat this as local path — is that right?");
  folded the validate-from-root note inline and removed trailing padding;
  deleted tests/README.md — no scripts/ directory exists, so the
  placeholder was noise.
- README.md: removed the tests/README.md row from the file table.
This commit is contained in:
2026-06-28 11:17:28 +00:00
parent a203e99b08
commit b1663c9dfd
4 changed files with 7 additions and 52 deletions

View File

@@ -26,15 +26,7 @@ metadata:
- Both marketplace files must be identical after every operation — never update one without the other in the same edit pass.
- `source` for local plugins is a relative path from the marketplace root, not the plugin directory name alone (e.g. `"./plugins/kyberforge"`, not `"kyberforge"`).
- `claude plugin validate .` must be run from the repo root, not from the plugin directory or the `.claude-plugin/` directory.
- The `{ "source": "github", ... }` object form is only for GitHub. For GitLab, Gitea, or any other git host, use `{ "source": "git", "url": "https://..." }` with a full URL.
- Removing an entry from the marketplace does NOT delete the plugin files — it only removes the catalog listing.
- `version` in a marketplace entry is optional for git-sourced plugins; Claude Code derives version from git tags automatically. Include it when the source is npm or when the user explicitly wants a pinned version visible in the catalog.
- `name` must be kebab-case. Reserved prefixes (`anthropic-*`, `claude-*`, `agent-skills`, `official-claude-plugins`) are rejected by the validator.
- The `plugins[]` array order is not semantically significant, but maintain it consistently — add new entries at the end.
- For Copilot CLI, the canonical marketplace.json location is `.github/plugin/marketplace.json`. Claude Code also reads `.claude-plugin/marketplace.json`. Both are equivalent; this repo maintains both files in sync.
- Copilot CLI places top-level `description` and `version` under a `metadata` object (`metadata.description`, `metadata.version`). Claude Code accepts them at the top level. For dual-tool repos, use the `metadata` form — it is valid in both tools.
- Set `"strict": false` on a plugin entry to allow relaxed schema validation for that entry. This is the right choice for plugins distributed as `.claude-plugin/` directories that also serve Claude Code — it prevents Copilot CLI from failing on CC-specific fields that are not in the Copilot schema.
## Route
@@ -105,7 +97,7 @@ Run this flow when a plugin name does not yet exist in `plugins[]` and the inten
### Prerequisites
Confirm you have:
- [ ] Plugin name (kebab-case)
- [ ] Plugin name (kebab-case; reserved prefixes `anthropic-*`, `claude-*`, `agent-skills`, `official-claude-plugins` are rejected by the validator)
- [ ] Plugin description
- [ ] Source type and source value (see source type branching below)
- [ ] Version (optional; omit for git-sourced plugins)
@@ -114,13 +106,7 @@ If you need details on a specific source type shape or per-entry optional fields
### Source type branching
If the user has not specified a source type, ask:
> "Which source type does this plugin use?
> 1. **Local path** — plugin lives in this repo (e.g. `./plugins/<name>`)
> 2. **GitHub** — separate GitHub repo (e.g. `owner/repo`)
> 3. **Git URL** — any git host via full URL (e.g. `https://gitlab.com/org/repo.git`)
> 4. **npm** — distributed on npm (e.g. `@scope/package`)"
If the user has not specified a source type, assume local path (the most common case for in-repo plugins). Only ask if the user's intent is unclear: "I'll treat this as a local path plugin — is that right, or does it live on GitHub, a git URL, or npm?"
Source shapes per type:
@@ -169,7 +155,7 @@ Read `.claude-plugin/marketplace.json` and `.github/plugin/marketplace.json`. Ve
### Step 2 — Add the entry
Append the new entry to the `plugins[]` array in `.claude-plugin/marketplace.json`.
Append the new entry to the end of the `plugins[]` array in `.claude-plugin/marketplace.json`. Array order is not semantically significant, but always add at the end for consistency.
### Step 3 — Mirror
@@ -233,7 +219,7 @@ Follow the **VALIDATE** flow.
## VALIDATE
Run `claude plugin validate .` from the repo root:
Run from the repo root (not from the plugin directory or `.claude-plugin/`):
```bash
claude plugin validate .
@@ -242,5 +228,3 @@ claude plugin validate .
Add `--strict` to promote warnings to errors — recommended in CI.
Report the output. If validation fails, describe the specific error and what needs to be fixed. Do not attempt to auto-fix validation errors unless the fix is unambiguous (e.g. a trailing comma that violates JSON syntax); otherwise, describe the fix and ask the user to confirm.
Validation checks include: `marketplace.json` schema compliance, duplicate plugin names, source path traversal, and version mismatches.