Migrate Zhin Plugin Runtime

What it does

When your agent uses it

• Tasks that involve Scheduled and recurring tasks

Example prompts

• “does not default-export a Plugin definition”
• “migrate”
• “/migrate-zhin-plugin-runtime”

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

1. 1盘点：读目标包的 README、最近的测试、旧入口，弄清用户可见行为（命令、消息、定时、
2. 2看计划：zhin runtime migrate extract --check，逐条读 changes 与 diagnostics。
3. 3搬能力：zhin runtime migrate extract --write。它只搬模块顶层、且闭包干净的注册，
4. 4清诊断：每条 manual 都要人工处理，见 人工诊断处理。
5. 5装配：zhin runtime migrate cutover --write 生成 package.json#zhin 与 plugin.ts，
6. 6迁移剩余配置：schema.json（只声明本包字段）、Feature mounts、child plugin mounts。
7. 7删旧：删掉旧注册代码、旧入口、compat 依赖。
8. 8验证：构建 + 测试 + 行为验证（命令路由、消息发送、配置默认值、热更新）。

What it can do on your machine

Read from SKILL.md and the folder at commit f38698f. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • pnpm
  • rg

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use pnpm, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Migrate Zhin Plugin Runtime loads about 1.6k tokens when it runs, and up to ~4.3k if it reads all its reference files. Until then it costs about 182 tokens; SKILL.md has 345 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~182

When it runs · the whole SKILL.md, loaded when a task matches

~1.6k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~4.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from zhinjs/zhin at commit f38698f, republished under its MIT licence (© zhinjs). 345 words, ~1,572 tokens.

name

migrate-zhin-plugin-runtime

description

Migrate legacy Zhin.js plugins and projects to the convention-based Plugin Runtime — from usePlugin/getPlugin/addCommand/addMiddleware/addComponent/addTool/addCron/declareConfig/useContext and mutable registries to definePlugin + capability directories + Scope/Token resources. Use this whenever a Zhin plugin fails to load under `zhin runtime start`, errors with "does not default-export a Plugin definition", still imports zhin.js/@zhin.js/core/@zhin.js/kernel, or when asked to upgrade, port, modernize, or migrate a Zhin plugin, command, middleware, component, tool, cron job, config schema, or package manifest — even if the user does not say the word "migrate". 适用于旧 Zhin 插件向约定式目录与快照运行时的破坏性迁移。

zhin runtime migrate status        # 输出 JSON；state 为 ready 时退出码 0，否则 1

// plugin.ts
import { createToken, definePlugin, databaseHostToken } from 'zhin.js';

export const storeToken = createToken<Store>('my-plugin.store');

export default definePlugin({
  name: 'my-plugin',                       // /^[a-z][a-z0-9-]*$/
  setup(context) {
    // Host 资源都是可选的：先 has 再 use，否则精简安装会装配失败
    if (!context.resources.has(databaseHostToken)) return;
    const db = context.resources.use(databaseHostToken);
    context.resources.provide(storeToken, createStore(db));
    return () => { /* disposer；HMR 回滚时调用 */ };
  },
});

// commands/profile/index.ts —— 目录路径即路由；参数写在目录名里
import { defineCommand } from 'zhin.js/command';
import { storeToken } from '../../plugin.js';

export default defineCommand({
  description: 'Show current user profile',
  async execute(context) {
    const store = context.use(storeToken);   // 能力上下文直接 use，不 import 单例
    return store.describe(context.input.sender.id);
  },
});

zhin runtime migrate status                  # state 必须是 ready（退出码 0）
rg -n "usePlugin\(|getPlugin\(|add(Command|Middleware|Component|Tool|Cron)\(|@zhin.js/next-" .
pnpm --filter <plugin-package> build
pnpm --filter <plugin-package> test
pnpm check:plugin-runtime-migration-readiness
pnpm check:plugin-runtime-migration-verify

pnpm --filter <plugin-package> run build
pnpm --filter <plugin-package> pack
# 解开 tarball，确认 package/plugin.js、package/plugin.d.ts 和已编译的能力目录存在

© zhinjs, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in .github/skills/migrate-zhin-plugin-runtime of zhinjs/zhin.

• SKILL.md
• references/manual-diagnostics.md
• references/migration-map.md

Open the folder on GitHubat commit f38698f