Add skill-bridge plugin (antianqi/skill-bridge) v0.2.0

[antianqi]

What

A stdio MCP server plugin that converts openclaw (or similar) skills into portable mavis / mcode-compatible Skills.

Why this PR is being opened on MiniMax-AI/MiniMax-Code-Plugins

A v0.1 of this plugin was opened as PR #3 against the now-superseded hetaoBackend/MiniMax-Code-Plugins repository, which has since been transferred to MiniMax-AI/MiniMax-Code-Plugins. The old PR was lost in the transfer (verified: GET /MiniMax-AI/.../pulls/3 returns 404; list pulls?state=all shows only #1).

This PR reopens the same plugin against the new official repo. The single commit (64ede9f) is a clean replacement of the old three-commit series (3c41ee0 + 3dfa159 + 1a22b12) on hetaoBackend/main#64bc5dd, in the same direction hetaoBackend had asked for in their round-2 review.

What changed from v0.1 (the round-2 blockers)

1. Portable delivery model. Dropped package.json / package-lock.json / index.js and the CLI surface. Added mcp.json + server.mjs, a single stdio MCP server (node ./server.mjs) declared per the portable Agent Plugins 1.0 contract. The plugin needs no npm install and no global bin to work.
2. Zero npm dependencies. The encoding detector now uses Node 22+'s built-in TextDecoder('gb18030'); the YAML frontmatter is parsed/serialized by a hand-rolled subset parser in lib/analyze.js. npm run validate and npm test pass without any package install.
3. Atomic replace. lib/transform-skill.js uses a backup-and-rename dance: a pre-existing outDir is moved to <outDir>.bak-<pid>-<rand>, the staging dir is renamed onto outDir, the backup is then removed. If anything fails, the backup is moved back, so outDir is preserved. Regression test: tests/transform-atomic.test.mjs.
4. Lint failure semantics. lib/lint.js returns { ok: false, code: 2, stdout, stderr } faithfully; the MCP convert tool surfaces that in its response. Callers see lint.ok === false and act accordingly. Regression test: tests/lint.test.mjs (the fast-path failure case).
5. In-tree scope. The only previously out-of-tree change (the root .gitignore) has been reverted; the plugin-local ignores now live under plugins/antianqi/skill-bridge/.gitignore.

Schema

plugin.json targets https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. mcp.json declares one stdio server. server.mjs exposes four tools:

Tool	Returns
detect(source)	{ encoding, originalEncoding, replaced, confidence, reason }
analyze(source)	full frontmatter, body, hardcoded paths, external commands, warnings
classify(source)	{ tier, subTier, reason } in pure / pure-wrapped-fix / wrapped-* / abandon
convert(source, target_dir, force?, run_lint?)	writes the converted skill, returns { ok, tier, subTier, written, warnings, lint }

Tests

node --test plugins/antianqi/skill-bridge/tests/*.test.mjs → 50/50 pass.

npm run validate → OK plugin antianqi/skill-bridge.

npm run check shows two pre-existing failures unrelated to this plugin (CRLF line endings in examples/hello-mcode/SKILL.md; Windows path.separator in test/hosted-plugins.test.mjs). Happy to open a follow-up PR to address either if you want them.

Demo

The only demo is examples/output/task-tracker/, the result of running convert on examples/input/task-tracker/. examples/regen.mjs regenerates it locally.

The two upstream-openclaw demos from v0.1 (investor-brand-kit, self-improving-agent) are removed: the first contained end-user business data; the second was a copy of a third-party repo whose license is not declared in that repo.

Data and network

• No network access. No credentials. Reads only the source path the caller provides.
• Writes only to the caller-provided target_dir and to a unique os.tmpdir()/sb-lint-<pid>-<rand>/ directory that is removed after the lint step completes.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[antianqi]

@hetaoBackend Thanks for the round-2 review. I've stepped back from
the v0.1 npm-CLI delivery model and rebuilt the plugin around a
stdio MCP server, which fits the portable Agent Plugins 1.0
contract you cited.

Three new commits on top of 64bc5dd:

1. 3c41ee0 — revert the root .gitignore overwrite.
   Plugin-local ignores now live under
   plugins/antianqi/skill-bridge/.gitignore.
2. 3dfa159 — restructure to v0.2.0:
   • Drop package.json / package-lock.json / index.js
     (the CLI surface they implied).
   • Add mcp.json + server.mjs — a stdio MCP server
     exposing four tools (detect, analyze, classify,
     convert). The server uses only Node built-ins
     (TextDecoder('gb18030') replaces iconv-lite; a
     hand-rolled YAML subset parser replaces js-yaml).
   • Rewrite skills/skill-bridge/SKILL.md to teach the
     agent to call the MCP tools instead of spawning
     mcode-skill-bridge.
3. 1a22b12 — regenerate the task-tracker demo with
   v0.2; add examples/regen.mjs so contributors can
   reproduce the demo locally.

Point-by-point on the round-2 blockers:

1. Portable delivery model: the MCP server is a
   single node ./server.mjs invocation. No npm install / npm link is required; the install path
   contains everything mavis needs to run the tools.
2. Build / dependency surface: no npm dependencies
   ship with the plugin. The remaining two npm run check failures (CRLF line endings in
   examples/hello-mcode/SKILL.md; Windows
   path.separator in hosted-plugins.test.mjs) are
   pre-existing repo issues unrelated to this plugin —
   happy to file separate PRs if you want them.
3. Atomic replace: lib/transform-skill.js now uses
   a backup-and-rename dance. The pre-existing outDir
   is moved to <outDir>.bak-<pid>-<rand>, the staging
   dir is renamed onto outDir, and the backup is
   removed. If any step fails, the backup is renamed
   back so outDir is restored. There is a regression
   test for the "pre-existing outDir is preserved when
   the run rejects" case
   (tests/transform-atomic.test.mjs).
4. Lint failure semantics: lib/lint.js no longer
   conflates FAIL with WARN. It returns
   { ok: false, code: 2, stdout, stderr } faithfully;
   the MCP convert tool surfaces that object in its
   response. Callers see lint.ok === false and act
   accordingly. There is a fast-path test
   (tests/lint.test.mjs) that exercises the failure
   path without spawning a subprocess.
5. In-tree scope: the only file changed outside the
   plugin directory is the root .gitignore, and that
   change is reverted in 3c41ee0.

Test count: 50 (was 33 in v0.1). All pass. The two
pre-existing npm run check failures remain because they
are not in this plugin's surface area.

Demo inventory: the v0.1 PR carried three demos; v0.2
ships only task-tracker (the author's own content).
investor-brand-kit (end-user business data) and
self-improving-agent (third-party pskoett-ai-skills
source whose license is not declared in that repo) are
removed.

[hetaoBackend]

Review result: do not approve / do not merge yet.

The repository check passes (77 tests), but the default product path has blocking defects:

• plugins/antianqi/skill-bridge/lib/lint.js:46-53: the default host linter is a CLI-only module that calls process.exit(2) when imported without a CLI argument. A default convert(..., run_lint=true) therefore terminates the MCP server before it can return the documented response.
• The docs advertise both a SKILL.md path and a directory source (README.md:50, skills/skill-bridge/SKILL.md:35,51), but server.mjs:155, analyze.js:193-194, and detect.js:88-90 pass directories directly to readFile, producing EISDIR.
• Unsupported YAML lists are treated as parse failure (analyze.js:79-82,147-154), then conversion proceeds with empty frontmatter (transform-skill.js:64-100), silently discarding metadata and embedding the original frontmatter in the body. This should either be supported or fail closed.
• transform-skill.js:187-195 moves the existing output away and only then moves staging into place; there is a missing-target window and a crash can leave the output absent despite the atomicity claim.

Please fix the default lint lifecycle first, add directory/list-frontmatter regression tests, and narrow the atomic replacement guarantee before requesting another review.

[antianqi]

Thanks for the review. Pushed four commits on top of 64ede9f, one per blocking issue. Quick recap:

Code fixes

• lib/detect.js, lib/analyze.js (review Add skill-bridge plugin (antianqi/skill-bridge) v0.2.0 #2)
  • readFileSafe and analyzeSkillFile now route through a new resolveSkillSource(filePath) that stats the path and, for a directory, looks for SKILL.md inside. The contract documented in the README and SKILL.md (directory sources) is now honored.
  • 3 new tests in tests/detect.test.mjs (directory reads cleanly, directory without SKILL.md throws a descriptive error, file path round-trips unchanged).
• lib/lint.js (review Add searxng-search plugin: self-hosted SearXNG web search Skill #1)
  • Dropped the in-process fast path entirely. The default host linter calls process.exit(2) when invoked without CLI arguments, and process.exit is not catchable — so the fast path was the exact bug the review called out. Every convert call now spawns a child process (~100 ms overhead, worth the determinism).
  • Pre-flight fs.stat(lintScript) so a missing host linter surfaces as { ok: false, code: -1, stderr: 'lint script not available: ...' } instead of an uncaught ENOENT.
  • 3 new tests: subprocess path leaves the install dir untouched, linter calls process.exit(2) and the MCP server still replies, missing lintScript returns ok: false cleanly.
• lib/transform-skill.js (review fix(validator): sandbox MCP stdio cwd, headers, and cross-platform SKILL.md #4)
  • Exported atomicReplace and added two test-only hooks (opts.rename, opts.renameStaging) so the missing-target window can be exercised deterministically.
  • Replaced .catch(() => {}) with proper error propagation: if the rollback itself fails, the thrown error now has a .recovery = { message, cause } field that names the backup path so the caller can recover manually.
  • 2 new tests: staging rename fails → original outDir is restored from the backup with no stray <outDir>.bak-*; swap AND rollback fail → the thrown error carries the recovery breadcrumb.
• lib/analyze.js, server.mjs (review Add antianqi/openclaw-acp-bridge v0.1.3 - peer collaboration Bridge for MiniMax Code #3)
  • Rewrote parseYamlBlock to support block-style lists (key:\n - item), flow-style lists (key: [a, b, c]), and list items that are themselves mappings (- name: foo\n value: 1). Found and fixed two latent bugs while writing this path:
    • the nested-object branch forgot to advance i (infinite loop on any input with a nested mapping — added a regression test)
    • dumpYamlBlock produced role: maintainer at the same indent as the next - name: bob, which the parser could not disambiguate; the recursion now indents one level deeper so the dump→parse round-trip is sound.
  • analyzeSkillFile now reports ok: boolean and err: string on the returned AnalyzedSkill.
  • The convert tool in server.mjs checks report.ok first and returns { ok: false, reason: 'frontmatter parse failed', err } without ever calling the transformer. A bad parse can no longer drop the original metadata.
  • 5 new tests in tests/analyze.test.mjs and 2 in tests/server.test.mjs covering block list, flow list, list of objects, the round-trip on arrays, the i++ regression, the directory-source end-to-end path, and the fail-closed convert contract.

Local verification

• node scripts/validate.mjs reports OK plugin antianqi/skill-bridge.
• node --test plugins/antianqi/skill-bridge/tests/*.test.mjs reports 63/63 pass (was 50/50; +13 new cases, 0 regressions).

Out of scope (still pre-existing repo issues)

• examples/hello-mcode/SKILL.md CRLF and the path.separator issue in test/hosted-plugins.test.mjs were not touched; happy to send separate PRs for those if you want.

Ready for another pass.

[hetaoBackend]

Reviewed the current head and the plugin implementation. No blocking issue found in the scoped review. Note: the repository's [code]smith check is SKIPPED, so this approval is based on source review and the submitted evidence.