Skip to content
This repository was archived by the owner on Sep 7, 2026. It is now read-only.

Commit 99a6324

Browse files
antianqiantianqi
committed
Add skill-bridge plugin (antianqi/skill-bridge)
Convert openclaw (and similar) skills into mavis/mcode-compatible skills or plugins. Detects encoding, parameterizes hardcoded paths, enriches frontmatter, runs the official lint, and produces a portable Skill-only Agent Plugin. - 1 Skill (skill-bridge) - 6 lib modules - 3 working demo conversions (task-tracker, investor-brand-kit, self-improving-agent) - 29 unit + integration tests - MIT license - Validates clean against the official plugin-compatibility.md schema
1 parent fa2c6b2 commit 99a6324

54 files changed

Lines changed: 4194 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎plugins/antianqi/skill-bridge/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules/
2+
tests/last-run.log

‎plugins/antianqi/skill-bridge/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 antianqi
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎plugins/antianqi/skill-bridge/README.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# skill-bridge
2+
3+
> Convert openclaw (and similar) skills into mavis/mcode-compatible skills or plugins.
4+
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
6+
[![Node](https://img.shields.io/badge/node-%3E%3D22.19-brightgreen)](package.json)
7+
8+
## Why
9+
10+
`openclaw` (and other agent frameworks) and `mavis` / `mcode` don't share a skill format. The hard parts are:
11+
12+
1. **Schema gap** — openclaw skills are 2-field frontmatter; mavis needs `descriptions.zh-Hans`, `displayNames`, `metadata`, locale keys.
13+
2. **Encoding gap** — openclaw wrote Chinese as GBK and filenames as mojibake. mavis requires UTF-8.
14+
3. **Path gap** — openclaw skills hardcode `C:\Users\Administrator\.openclaw\workspace\...` and `/tmp/CLI-Anything/...`. mavis needs parameterized paths.
15+
4. **Platform gap** — openclaw assumes `bash` / `pip install -e .` / `python3` in PATH. mavis (especially on Windows) needs PowerShell equivalents.
16+
5. **Discovery gap** — openclaw's staging directory is not in mavis's skill scan path. Copying files there does nothing.
17+
18+
**skill-bridge** turns "copy the folder and pray" into a deterministic pipeline: detect → analyze → classify → transform → lint.
19+
20+
## Install
21+
22+
```bash
23+
# from a clone of this repo
24+
npm install
25+
npm link # so `mcode-skill-bridge` is on PATH
26+
# OR via mcode plugin install (after this is published):
27+
# mcode plugin add https://github.com/antianqi/skill-bridge
28+
```
29+
30+
Requires **Node.js 22.19+ or 24+** (matches the mcode engine).
31+
32+
## Quick start
33+
34+
```bash
35+
# 1. Look at one openclaw skill
36+
mcode-skill-bridge analyze /path/to/openclaw/skills/task-tracker
37+
38+
# 2. See what tier it falls into
39+
mcode-skill-bridge classify /path/to/openclaw/skills/task-tracker
40+
41+
# 3. Convert to a mavis-compatible skill
42+
mcode-skill-bridge convert /path/to/openclaw/skills/task-tracker \
43+
--out ~/.minimax/agents/mavis/skills/task-tracker
44+
```
45+
46+
After step 3, restart mavis (or start a new session) and the converted skill shows up in `<available_skills>`.
47+
48+
## How it works
49+
50+
```
51+
input SKILL.md
52+
│
53+
▼
54+
[detect] GBK vs UTF-8; restore mojibake if needed
55+
│
56+
▼
57+
[analyze] parse frontmatter, scan hardcoded paths, scan external commands
58+
│
59+
▼
60+
[classify] pure-translate | pure-wrapped-fix | wrapped-* | abandon
61+
│
62+
▼
63+
[transform] write new SKILL.md (+ optional references/) to mavis schema
64+
│
65+
▼
66+
[lint] run the official skill-creator lint on the output
67+
│
68+
▼
69+
output: mavis-compatible skill
70+
```
71+
72+
### The three tiers
73+
74+
| Tier | What it is | Output in v0.1 |
75+
|---|---|---|
76+
| `pure-translate` | Pure instruction, ASCII-clean, no hardcoded paths | A `SKILL.md` with enriched frontmatter only |
77+
| `pure-wrapped-fix` | Pure instruction but with hardcoded paths or GBK | A `SKILL.md` with paths parameterized + encoding fixed + Windows notes added |
78+
| `wrapped-*` | Needs an external CLI/API (Python, ComfyUI, Douyin, …) | **Not supported in v0.1.** v0.2 will emit a plugin skeleton. |
79+
80+
## What's in v0.1
81+
82+
- ✅ `lib/detect.js` — UTF-8 / GBK detection via `iconv-lite` + heuristic mojibake detection
83+
- ✅ `lib/paths.js` — 6 hardcoded path patterns → `${OPENCLAW_HOME}`, `${OPENCLAW_WORKSPACE}`, `${SCRATCH}`, `${DATA_DIR}`
84+
- ✅ `lib/analyze.js` — YAML frontmatter parse, hardcoded-path scan, external-command scan
85+
- ✅ `lib/classify.js` — 4-question decision tree
86+
- ✅ `lib/transform-skill.js` — frontmatter enrichment, body path rewriting, 500-line body splitter, Windows notes injection
87+
- ✅ `lib/lint.js` — wraps the official `~/.minimax/.builtin-skills/skill-creator/scripts/lint-skill.js` (handles the `.js`-as-ESM quirk)
88+
- ✅ `index.js` — CLI with `detect` / `analyze` / `classify` / `convert` / `lint`
89+
- ✅ `skills/SKILL.md` — discoverable LLM entry (so a Mavis session can use it without remembering the CLI)
90+
- ✅ 29 unit + integration tests
91+
- ✅ 3 working demos (see `examples/output/`)
92+
93+
## What's NOT in v0.1
94+
95+
- ❌ `wrapped-*` → plugin skeleton generation (planned for v0.2)
96+
- ❌ GBK **filename** restoration (we warn, we don't rename)
97+
- ❌ npm publish (planned for v0.2)
98+
- ❌ Reverse tool (mavis → openclaw)
99+
- ❌ Auto-registration into mavis's scan path (you have to restart the session)
100+
101+
## Try the demos
102+
103+
```bash
104+
git clone https://github.com/antianqi/skill-bridge
105+
cd skill-bridge
106+
npm install
107+
npm run demo:all
108+
# inspect the output
109+
ls examples/output/task-tracker
110+
cat examples/output/task-tracker/SKILL.md
111+
cat examples/output/task-tracker/conversion-report.md
112+
```
113+
114+
The three demos cover the main pure-tier shapes:
115+
116+
| Demo | What it stresses |
117+
|---|---|
118+
| `task-tracker` | Chinese name in source, hardcoded `${OPENCLAW_WORKSPACE}` path, no external deps |
119+
| `investor-brand-kit` | CJK body with rich content, no path/encoding issues (pure-translate) |
120+
| `self-improving-agent` | 600+ line body → automatically split into `references/` |
121+
122+
## CLI reference
123+
124+
```
125+
mcode-skill-bridge detect <file> Detect encoding of a SKILL.md
126+
mcode-skill-bridge analyze <file-or-dir> Analyze (frontmatter, paths, external cmds)
127+
mcode-skill-bridge classify <file-or-dir> Classify into pure / wrapped / abandon
128+
mcode-skill-bridge convert <file-or-dir> Convert and write to --out
129+
mcode-skill-bridge lint <skill-dir> Lint a converted skill
130+
131+
Options:
132+
--out <dir> Output directory (default: ./out/<name>)
133+
--force Overwrite existing output
134+
--no-lint Skip lint after convert
135+
--scope <s> user | agent | project (informational)
136+
--json Machine-readable output
137+
```
138+
139+
## Project layout
140+
141+
```
142+
skill-bridge/
143+
├── plugin.json # mcode plugin manifest
144+
├── index.js # CLI entry
145+
├── package.json
146+
├── lib/ # pure ESM modules
147+
│ ├── detect.js
148+
│ ├── paths.js
149+
│ ├── analyze.js
150+
│ ├── classify.js
151+
│ ├── transform-skill.js
152+
│ └── lint.js
153+
├── skills/
154+
│ └── SKILL.md # discoverable LLM entry
155+
├── references/ # human docs
156+
│ ├── compatibility-matrix.md
157+
│ ├── path-patterns.md
158+
│ └── encoding-tables.md
159+
├── examples/
160+
│ ├── input/ # original openclaw skills (CC0 from openclaw)
161+
│ └── output/ # converted mavis skills
162+
└── tests/
163+
├── detect.test.mjs
164+
├── paths.test.mjs
165+
├── classify.test.mjs
166+
├── transform-skill.test.mjs
167+
└── cli.test.mjs
168+
```
169+
170+
## Method — how we decided what's a "compatible skill"
171+
172+
See [`references/compatibility-matrix.md`](references/compatibility-matrix.md) for the full mapping of all 36 openclaw skills into the three tiers.
173+
174+
The high-level rule:
175+
176+
> If the skill is a self-contained instruction (you can read it and act on it without installing anything else), it is `pure`. Otherwise, it is `wrapped`. If it depends on openclaw-specific runtime (e.g. the openclaw TUI, a specific Python venv, a non-replicable hard-coded directory), it is `abandon`.
177+
178+
## Roadmap
179+
180+
- **v0.2** — `wrapped-*` tier: generate a real mavis plugin (`plugin.json` + `index.js`) for skills that need external CLIs/APIs
181+
- **v0.3** — Web UI via the `visual-page` skill, history-aware incremental conversion
182+
- **v0.4** — Reverse tool: mavis skill → openclaw-compatible bundle
183+
184+
## Contributing
185+
186+
1. Fork the repo.
187+
2. Add a fixture under `tests/fixtures/` for the new edge case.
188+
3. Add a test under `tests/`.
189+
4. Open a PR. CI will run `npm test`.
190+
191+
## License
192+
193+
MIT — see [LICENSE](LICENSE).
194+
195+
## Credits
196+
197+
- The mavis skill schema and lint rules are owned by MiniMax.
198+
- The three demo skills (`task-tracker`, `investor-brand-kit`, `self-improving-agent`) are adapted from the openclaw workspace with the author's permission.
199+
- Built by [antianqi](https://github.com/antianqi).

0 commit comments

Comments
 (0)