skill-bridge

# skill-bridge Bring a non-mavis skill into the mavis world. The skill itself is the **thin LLM-facing layer**; the heavy lifting lives in the stdio MCP server declared in `mcp.json` at the plugin root. The MCP server exposes four tools, named after the original v0.1 CLI subcommands: | Tool | Purpose | | --- | --- | | `detect(source)` | Identify UTF-8 vs GBK; restore mojibake if needed. | | `analyze(source)` | Full report: frontmatter, body, hardcoded paths, external commands. | | `classify(source)` | One of `pure` (translatable), `pure-wrapped-fix`, `wrapped-*`, or `abandon`. | | `convert(source, target_dir, force?, run_lint?)` | Run the full pipeline; write to `target_dir`. Lint runs unless `run_lint=false`. | `source` accepts either an absolute path to a `SKILL.md` file or to a directory containing one. `target_dir` is an absolute path that will be created or replaced atomically. ## When to use this skill - The user has an `openclaw` workspace (or any non-mavis skill bundle) and wants to use those skills inside mavis. - The user found a skill on GitHub written in a different agent framework and wants to reuse it. - The user wrote a `SKILL.md` themselves years ago and wants to bring it up to mavis's current schema. Do **not** use this skill for: - Creating a new skill from scratch → `skill-creator` - Fixing or refining an existing mavis skill → `skill-refiner` - Listing what skills are available → read `<available_skills>` from the system prompt ## Inputs to collect - **Source path**: an absolute path to either a `SKILL.md` file or to a folder containing one. If the user gave a relative path, resolve it against the user's cwd before calling the tool. - **Output path**: an absolute path for the converted skill. Default: a folder whose basename matches the kebab-case name. If the user names a scope: - user → `<homedir>/.minimax/skills/<name>/` - agent → `<homedir>/.minimax/agents/mavis/skills/<name>/` - project → `<repo>/.minimax/skills/<name>/` - **Force overwrite (optional)**: only confirm with the user if the target already exists. The server is safe to re-run; `force` is informational. ## Procedure 1. **Detect** the source. Call `detect(source)` and inspect `encoding`. - If `encoding === "unknown"`, warn the user before continuing. - If `encoding === "gbk"` and `replaced === true`, tell the user the source was GBK and we restored it. 2. **Analyze** the full report. Call `analyze(source)` and check `hardcodedPaths` and `externalCommands`. - Non-empty `externalCommands` → the skill is likely `wrapped-*` (v0.2 only emits `pure`; stop and tell the user). 3. **Classify**. Call `classify(source)`. In v0.2, proceed only if `tier === "pure"`. 4. **Convert**. Call `convert(source, target_dir)`. - If the tool returns `ok: false` with `tier: "abandon"` or `tier: "wrapped"`, stop and explain why. - If `ok: true`, read `target_dir/conversion-report.md` and surface the `warnings` array to the user verbatim. - Skim `target_dir/SKILL.md`. If anything looks wrong (missing section, garbled encoding, broken path), tell the user **before** claiming success. 5. **Lint feedback**. The `convert` response already includes the `lint` object (`ok`, `code`, `stdout`, `stderr`). If `ok === false`, surface the lint output and do not claim the conversion is done. 6. **Tell the user** what was written, what to review, and how to use the new skill. Suggest `skill({name: "<converted-name>"})` to verify it loads. ## Output contract - A directory at `target_dir` containing at minimum: - `SKILL.md` — mavis-schema-compliant - `conversion-report.md` — what was changed - optionally `references/<topic>.md` if the body was split The server replaces `target_dir` atomically: at every observable point in time the directory is either the OLD content or the NEW content, never empty or half-written. Re-running with the same `target_dir` is always safe. ## Failure handling - `tier: abandon` from `classify` → do not write; explain the reason to the user. - `tier: wrapped` in v0.2 → tell the user the server only supports `pure` right now; v0.3 will add `wrapped`. - `lint.ok === false` → do not claim success; show the `lint.stdout` and `lint.stderr` verbatim. - `encoding === "unknown"` → ask the user to confirm the source is genuinely UTF-8 before writing. - Target already exists → atomic replace happens by default; only ask the user if you want to confirm before overwriting. ## Examples **Input**: `/path/to/openclaw/skills/task-tracker` **Good path**: 1. `detect(...)` → `utf-8`, no replacement. 2. `classify(...)` → `pure / pure-wrapped-fix` (one hardcoded path group). 3. `convert(source, target_dir)` → `ok: true`, two warnings about path parameterization. 4. Confirm `lint.ok === true`, surface the two warnings to the user. **Bad path**: copy the `SKILL.md` to `<homedir>/.minimax/agents/mavis/skills/<name>/` directly. The user's previous attempt at this failed because (a) the path is not in the mavis scan list and (b) GBK content was not detected. ## Additional resources - `references/compatibility-matrix.md` — known openclaw skills and their tier - `references/path-patterns.md` — the hardcoded path patterns we replace - The MCP server itself: see `mcp.json` + `server.mjs` in the plugin root - The plan that produced this skill: see the plugin's `README.md`