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.

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:

   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:

   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.