Publish Ability

Publish an Ability to the Vetta Marketplace

Submitting is a local action: it reads an archive from the user's disk, so it runs through the bundled script rather than a tool call.

bashCopy code
node "$SKILL_DIR/scripts/publish.mjs" --input /abs/path/to/payload.json

Checking review status afterwards is a remote action — use the list_my_abilities tool from the built-in vetta MCP server. It is always available and needs no setup.

Procedure

1. Determine the type. Ask the user if it is not obvious from the artifact.

   Type	What it is	Physical artifact
   skill	A SKILL.md workflow	.zip / .tar.gz containing SKILL.md
   scene	A skill installed into the scene directory	same as skill
   plugin	A Vetta plugin	.zip containing plugin.json
   mcp	One entry in the user's mcp.json	none — config only
   bundle	A named group of already-published abilities	none — references only

2. Source detail from the package. Do not invent it. name, description, author, and content are all required and the submission is rejected without them. Read plugin.json (name/description/author), SKILL.md frontmatter, README.md, LICENSE. Ask the user for anything you cannot source.

   For plugins, also list locales/*.json: those filenames are the exact locale keys your detail.i18n must use, and whatever they already translate is text you should not restate. See Multi-language.

   content is the detail-page body in markdown — it is what a user reads to decide whether to install. Write what the ability does, when to use it, and any setup it needs. A one-line content is not acceptable.

3. Read the available categories before you set one. category is matched by name — a name that matches nothing is not an error, it silently lands in "uncategorised". So never invent one:

   bashCopy code
   node "$SKILL_DIR/scripts/categories.mjs"          # human-readable
   node "$SKILL_DIR/scripts/categories.mjs" --json   # machine-readable
   

   Put the name field verbatim into the payload's category. The i18n values are display translations only — matching accepts them, but the canonical name is what you should write. Omit category entirely if nothing fits.

4. Write the payload to a JSON file, then pass it with --input. Never try to pass fields as command-line arguments: content is multi-line markdown containing backticks, quotes and $, and the shell will mangle it.

   Full field reference: references/payload.md — read it when you need anything beyond the four required detail fields. It is also where the valid icon names and the meaning of each showcase.canvas value are listed; both are closed sets, and a wrong value either fails validation or renders as a fallback.

5. Dry-run first when the payload is non-trivial. It runs the full validation without submitting, so you spend no network round-trip on a payload that was never going to pass:

   bashCopy code
   node "$SKILL_DIR/scripts/publish.mjs" --input payload.json --dry-run
   

   For skill/scene/plugin this also opens the archive and cross-checks the payload against plugin.json, locales/*.json, and SKILL.md frontmatter. That is the only place the "same data, two sources" mistakes surface: a translation key that does not match the package's own locale files, a slug or version that the server will ignore, a vetta.json that your detail silently supersedes. None of these fail the upload — they just make part of what you wrote unreachable. Do not skip the dry-run on packaged types.

6. Submit. On failure the script returns all problems at once — fix the whole list before retrying rather than resubmitting after each single fix.

Script contract

• stdout is a single JSON object; exit code 0 = success, 1 = failure.
• Failure shape: {"ok": false, "message": "...", "errors": [...]} — errors is present for validation failures.
• Success shape: {"ok": true, "message": "...", "slug": "...", "version": "...", "review_status": "...", "has_pending": bool, "warnings": [...]}.
• warnings are things that did not block the submission but changed what gets published — a hand-written translation overriding the package's own, a slug that was ignored, a vetta.json that was skipped. Relay them to the user; do not treat the run as clean.
• Input may also arrive on stdin (cat payload.json | node .../publish.mjs) if that is more convenient than a temp file.
• The script reads the login token from ~/.vetta/auth.json itself. If it reports "未登录", tell the user to log in through the Vetta client — do not attempt to pass credentials yourself.

Review

Submissions from non-administrators enter a review queue and are not visible in the marketplace until an administrator approves them. Tell the user this rather than implying the ability is live.

Re-submitting an ability that is already published does not disturb it: the new version waits in a pending slot while the marketplace keeps serving the current version, so installed users are unaffected until the update is approved. has_pending: true in the result means exactly this.

A re-submission replaces detail.i18n wholesale. Sending only the locale you changed drops every other translation on that entry, including any an administrator added later. Fetch the current state first (list_my_abilities) or resend the complete set of locales.

You may only submit updates to abilities you own. Submitting to a slug owned by someone else is rejected.

Verify

After a successful run, state the returned slug, version, and whether the ability is live or pending review. If the run failed, fix every listed error and retry — do not report success.

Use list_my_abilities to report progress later: review_status is pending, approved, or rejected (reason in review_note); a non-empty pending_version means an update is queued behind the live version.