convert-marketplace

name	convert-marketplace
description	Guided conversion of a Claude Code marketplace into Tome's native plugin format. Drives `tome convert` and `tome lint` for the mechanical work, applies judgment to the parts Tome cannot represent, verifies the result, then reports to you and waits for explicit confirmation before registering anything in a workspace.
tome_prompt_name	add-tome-conversion-skill

Convert a Claude Code marketplace to Tome

You are converting a Claude Code marketplace (a collection of plugins, each with skills / commands / agents) into Tome's native format so the plugins work across every harness Tome supports. Tome does the mechanical 80% — format translation, harness-variable rewriting, manifest synthesis — through tome convert and tome lint. Your job is the judgment 20%: the components Tome cannot represent, the verification, and — above all — stopping to report and get the user's explicit confirmation before you register anything in a workspace.

Work through the steps in order. Do not skip the report-and-confirm gate (Step 5) even if everything converted cleanly with nothing left over.

Step 1 — Inventory first, change nothing

Before touching anything, build a complete picture of what the source contains and what Tome can and cannot carry over.

• Run the conversion in dry-run mode and read the plan:

  tome catalog convert <source> --dry-run --json
  

  <source> is the marketplace directory. (For a single plugin or skill rather than a whole marketplace, use tome plugin convert / tome skill convert instead.) The --json output is JSONL: one type: "diagnostic" line per finding (rule, severity, message, file, line, autofixable), then a final type: "result" line carrying counts only — how many files would be written, and the number of errors, warnings and infos. It reports the unsupported components Tome flagged (monitors, themes, LSP servers, output-styles, bin/ executables, channels, and exotic manifest fields such as userConfig), but it does not enumerate the skills, commands and agents that convert cleanly. Build that inventory yourself.
• Walk the source tree and record, per plugin, every skill / command / agent, so you know what a clean conversion must produce. Convert does not flag several classes that will not survive the conversion — check for each explicitly:
  • Non-standard plugin-root directories (scripts/, lib/, and anything other than skills/, commands/, agents/, hooks/, .mcp.json): convert reads none of these and warns about none of them. A hook that shells out to a CLAUDE_PLUGIN_ROOT-relative path such as scripts/… breaks after conversion unless you copy the directory across by hand.
  • Nested commands/ or agents/ subdirectories (namespaced entries such as commands/git/commit.md): these are dropped with no diagnostic.
  • plugin.json component-path overrides (for example "hooks": "./config/hooks.json"): convert records the override as an info line but does not import the component it points at. Everything you find here — the flagged components and these unflagged classes — is your Step 3 work queue. Nothing leaves it without an explicit decision.

Do not run a non-dry-run convert yet.

Step 2 — Mechanical conversion

Now run the real conversion — it lands a fresh catalog directory on disk (the source is never modified) — and read what happened:

tome catalog convert <source> --output <parent-dir> --json

--output is the parent directory the new catalog lands under; the catalog itself is created at <parent-dir>/<name>/ (call that produced directory <catalog> in the steps below). --output defaults to the current directory if omitted.

From the --json output, separate two buckets:

• Auto-converted — entries Tome translated for you: native SKILL.md / command / agent files written, tome-plugin.toml / tome-catalog.toml manifests synthesised, and harness-specific variables rewritten to their Tome equivalents automatically — and each plugin's hooks/ directory copied through verbatim (Tome's harness sync consumes it). You do not need to touch these.
• Flagged — the unsupported components from Step 1, which convert leaves behind with a warning rather than guessing. These are Step 3.

Remote-source plugins. Marketplace entries that point at other repositories (github / git / url sources) are fetched and vendored automatically — each repo is shallow-cloned and converted in place, reported with a convert/remote-plugin-fetched info line. Two cases need your attention:

• A convert/remote-plugin-fetch-failed warning means one plugin could not be fetched (network, auth, or not actually a plugin repo). The rest of the catalog still converted. Fall back to converting that plugin individually into the catalog:

  tome plugin convert <repo-url> --into <catalog>
  

• npm-source plugins cannot be fetched and are skipped with a convert/remote-plugin-skipped warning; treat them as Step 3 judgment items.

Pass --no-fetch to skip all remote plugins instead (an offline conversion — they are skipped with warnings, exactly like the failures above).

If you want Tome to refuse rather than warn on anything it cannot represent, add --strict — it aborts before writing so you can decide deliberately. Without --strict, convert writes the supported parts and warns about the rest.

Note that --strict blocks on the convert/agent-lossy and convert/tool-restriction-dropped warnings that almost every marketplace with agents produces. Once you have decided how you will handle each (Step 3), re-run with those rules demoted so the block clears while the warnings still print: --strict --allow convert/agent-lossy --allow convert/tool-restriction-dropped. The abort message lists the exact rule ids to allow.

Step 3 — Judgment pass on the unsupported residue

For each flagged component, make and write down an explicit decision — one of: drop, hand-port, or document. Consult references/unsupported-component-rubric.md for a per-component decision aid. Briefly:

• Drop — the component has no Tome-native equivalent and no behavioural value worth preserving (e.g. a harness-only theme or output-style). Record that it was intentionally dropped.
• Hand-port — the behaviour matters and Tome has a native way to express it (e.g. a guardrail or a piece of agent guidance). Re-author it in the native form and note what you did.
• Document — the behaviour matters but Tome cannot represent it yet. Leave a clear note (in the plugin's docs or a KNOWN-GAPS note) so the user knows the gap exists.

Keep a running record of every decision — you will report all of them in Step 5.

Step 4 — Verify

Lint the converted catalog and resolve everything until it is clean (lint is a subcommand of catalog, not a top-level verb):

tome catalog lint <catalog> --json

• Fix any errors (these fail CI). Re-run until there are none.
• Resolve strict warnings (tome catalog lint <catalog> --strict) where they matter.
• For mechanical, safe fixes (residual harness-isms, name/dir mismatches), you can apply them automatically:

  tome catalog lint <catalog> --autofix
  

  Then re-lint to confirm. Never autofix blindly over a judgment call from Step 3 — review the diff.

Body-size warnings. tome catalog lint flags lint/body-too-large / lint/resource-too-large when a skill's SKILL.md body, or one of its text reference files, is too large to fit the harness's get_skill response budget. These are not autofixable — splitting prose is a judgment call. To resolve one, extract long inline material — large fenced code blocks, embedded reference tables, verbose background — into references/*.md files and replace each in the body with a one-line pointer to the reference. get_skill returns the body inline but supporting files as paths the agent loads on demand, so moving material out of the body directly shrinks the served response. Re-lint to confirm the warning clears.

Iterate Step 3 ↔ Step 4 until tome catalog lint is clean (or only carries intentional, documented gaps).

Step 5 — Report, then STOP and wait for confirmation

This gate is unconditional. It fires even when the conversion was perfectly clean and there were zero unsupported components. Register nothing yet.

Report to the user, plainly:

• the plugins and entries that converted, and where the catalog landed on disk;
• what auto-converted vs. what you hand-touched;
• every judgment decision from Step 3 (drop / hand-port / document), with the reason;
• the final tome lint state and any documented gaps that remain.

Then ask the user, in your own words, whether they want you to add the catalog and enable its plugins in a workspace — and wait for an explicit answer.

• If they decline (or don't answer): you are done. The converted artifacts stay on disk, fully usable, and nothing is registered. Do not proceed.
• If they confirm: continue to Step 6.

Step 6 — Confirmed registration

Only after explicit confirmation. First ask whether they want a new workspace or an existing one.

Enabling a plugin updates the workspace index; on its own it writes nothing into a harness. The rules files, MCP registration, hooks and native agents reach a harness only when you sync. So the flow is: enable the plugins, make sure a harness is configured, then sync.

New workspace:

tome workspace init <name>
tome workspace use <name>
tome catalog add <catalog>
tome plugin enable <catalog>/<plugin>     # repeat per plugin they want
tome plugin show <catalog>/<plugin>       # confirm it resolved

Existing workspace:

tome workspace list                       # let the user pick
tome workspace use <chosen>
tome catalog add <catalog>
tome plugin enable <catalog>/<plugin>
tome plugin show <catalog>/<plugin>       # confirm

When running non-interactively (e.g. in CI, or before the embedding models are downloaded), add --yes to tome plugin enable to skip its model-download confirmation prompt.

Then sync to the harness. If the workspace has no harness configured yet, add one first, then propagate everything you enabled:

tome harness use <name>                   # only if no harness is configured yet (e.g. claude-code, cursor, codex)
tome sync                                 # writes rules, registers MCP, wires hooks and native agents

You can fold the sync into the enable step instead with tome plugin enable <catalog>/<plugin> --sync, which syncs the bound harnesses once for the whole batch.

Spot-check that the plugins actually reached the harness:

tome doctor                               # reports any drift or unsynced state
tome harness info <name>                  # shows what is registered for that harness

Finish by confirming to the user what is now registered and enabled, and restate any documented gaps from Step 3 so nothing is silently lost.