Agent skill

Zhin Plugin Standard Development

by zhinjs in zhinjs/zhin

Implement Zhin.js plugins with Plugin Runtime. An agent skill from zhinjs/zhin.

MITAuto-check passedProductivity & Automation

Install Zhin Plugin Standard Development

skills CLI
$ npx skills add zhinjs/zhin --skill zhin-plugin-standard-development -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install zhinjs/zhin zhin-plugin-standard-development --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/zhinjs/zhin.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.github/skills/zhin-plugin-standard-development .claude/skills/zhin-plugin-standard-development && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
zhin-plugin-standard-development
GitHub stars
137
Token cost
~1.6k tokens
SKILL.md length
431 words
Files
15 (incl. references, assets)
Skills in repo
11
Repo updated
First seen
Licence
MIT

At a glance

Implement Zhin.js plugins with Plugin Runtime. An agent skill from zhinjs/zhin.

  • Works in 3 steps: 任务类型 → 目录 → 放哪一层 → 依赖
  • Asked to create a plugin
  • SKILL.md covers 何时使用, 完成标准, 决策流程 and 标准实现步骤, plus 4 more sections
  • Runs TypeScript scripts from its folder; calls pnpm

What it does

Zhin Plugin Standard Development is an agent skill from zhinjs/zhin. Implement Zhin.js plugins with Plugin Runtime. Use when asked to create a plugin or add commands, middleware, handlers, components, schedules, Agent capabilities, config, database, HTTP Host integration, or Console pages. 适用于 definePlugin / 约定目录能力落地。

Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. The skill folder holds 16 other files, including reference files and assets (for example `assets/ai-tool-template.ts`, `assets/cron-template.ts` and `assets/database-service-template.ts`).

It sits in Productivity & Automation. The repository describes itself as: AI-native TypeScript bot framework — one codebase for 20+ chat platforms (QQ, Discord, Telegram, Slack, WeChat…). Opt-in AI agent with MCP, tools & security policies. <10MB core. The licence is MIT.

When your agent uses it

  • Asked to create a plugin
  • Agent capabilities
  • HTTP Host integration

Example prompts

  • “/zhin-plugin-standard-development”

Requirements

  • Node.js

Workflow steps

3 steps, taken from the step headings in SKILL.md.

  1. 任务类型 → 目录
  2. 放哪一层
  3. 依赖

What it can do on your machine

Read from SKILL.md and the folder at commit fd5029a. 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

    Ships script files (TypeScript), which the agent can run.

    Shell commands in SKILL.md call:

    • pnpm

    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

Zhin Plugin Standard Development loads about 1.6k tokens when it runs, and up to ~4.6k if it reads all its reference files. Until then it costs about 71 tokens; SKILL.md has 431 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~71
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.6k

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

Auto-check passed

The automated check found no risky patterns in SKILL.md.

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 fd5029a, republished under its MIT licence (© zhinjs). 431 words, ~1,611 tokens.

Download SKILL.mdSave it as .claude/skills/zhin-plugin-standard-development/SKILL.md (or your agent's skills folder). This skill also uses 14 other files; get the full folder from GitHub.
name
zhin-plugin-standard-development
description
Implement Zhin.js plugins with Plugin Runtime. Use when asked to create a plugin or add commands, middleware, handlers, components, schedules, Agent capabilities, config, database, HTTP Host integration, or Console pages. 适用于 definePlugin / 约定目录能力落地。
argument-hint
Describe the plugin goal, target package, and required capabilities (commands, middleware, handlers, components, schedules, Agent tools, config, database…
user-invocable
true

Zhin 插件标准开发姿势(Plugin Runtime)

把需求落成符合仓库约定的可运行插件。唯一创作面是 Plugin Runtime。

zhin runtime start 是唯一启动路径。插件即 package:package.json#zhin 声明 manifest, plugin.ts 必须 default-export definePlugin(),否则装配抛 does not default-export a Plugin definition。

能力按命名目录发现(每个能力固定 index.ts 入口并 default export),不要命令式注册:

目录API
commands/**/index.tsdefineCommand()(目录路径即路由;[name] / [[name]] / [...name] / [[...name]] 传参,类型与默认值在 params 中声明)
middlewares/<name>/index.tsdefineMiddleware()
handlers/<name>/index.tsdefineHandler()
components/<name>/index.tsxdefineComponent()
tools/<name>/index.tsdefineAgentTool()
mcps/<name>/index.tsdefineMcp()
schedules/<name>/index.tsdefineSchedule();也可在 plugin.ts 注入
hooks/<name>/index.tsdefineHook()
pages/<name>/index.tsxdefinePage()(nav/ / footer/ 为布局槽)
skills/<name>/SKILL.mdMarkdown Skill
agents/<name>/agent.jsonAgent 元数据;提示词和边界文件与其同目录

DI:context.resources(Scope + Token)。清理:context.lifecycle。

禁止使用 usePlugin() / getPlugin() / MessageCommand / addCron(new Cron) / declareConfig 经典路径;zhin.js/node 与 bootstrapNode 已删除且不再导出。 迁移旧代码用 migrate-zhin-plugin-runtime。

配套资产:

官方指令摘要:.github/instructions/zhin-plugin.instructions.md。

何时使用

  • 新建插件,或给现有 Runtime 插件加命令/中间件/组件/定时/工具/控制台页
  • 接入数据库、HTTP、console
  • 用户要求「按 Zhin 标准方式实现插件」

完成标准

  • plugin.ts default-export definePlugin;package.json#zhin 正确
  • 能力在约定目录,default export 对应 define* API
  • 无新增 usePlugin / MessageCommand / 经典 Plugin 生命周期
  • 相对导入带 .js;Host token 先 has 再 use
  • 清理走 context.lifecycle(或 setup 返回 disposer)
  • 出站不绕过统一发送链
  • 做过与改动匹配的验证(test / 手测命令)

决策流程

1. 任务类型 → 目录
类型重点位置
命令defineCommand,路径即路由commands/**/index.ts
中间件 / 入站过滤defineMiddleware,target: 'inbound'middlewares/<name>/index.ts
出站改写target: 'outbound'middlewares/<name>/index.ts
定时defineSchedule,或 setup 注入schedules/<name>/index.ts / plugin.ts
HandlerdefineHandler,显式声明事件handlers/<name>/index.ts
HookdefineHookhooks/<name>/index.ts
组件defineComponentcomponents/<name>/index.tsx
AI 工具defineAgentTooltools/<name>/index.ts
SkillSKILL.md,按需披露专用工具skills/<name>/SKILL.md
Agentagent.json + 提示词与边界文件agents/<name>/
服务 / DIresources.provideplugin.ts setup
数据库databaseHostToken,start 前 define 表plugin.ts setup
WebdefinePagepages/<name>/index.tsx

多类型并存时先定主职责,再考虑拆分子包。

2. 放哪一层
  • Host:packages/host/;可选服务:plugins/services/ / plugins/utils/
  • 业务插件:plugins/ 对应分类
  • 示例验证:examples/minimal-bot / examples/single-file-bot
  • 平台协议 → 适配器,不要写进普通插件
3. 依赖

Host(database / schedule / outbound / agentTools)一律可选:has(token) 再 use(token)。

  • 配置:schema.json + context.config.get()
  • 推送:outboundHostToken(不旁路发送链)
  • 跨插件服务:对方 Token;必要时 definePlugin({ requires: [...] })

标准实现步骤

第 1 步:最小功能面

明确职责、用户入口(命令 / 中间件 / 页)、是否持久化。无复杂度时也直接使用最小约定入口,例如 commands/<name>/index.ts,不要先写命令式注册再迁移。

第 2 步:入口与骨架

plugin.ts 只装配与生命周期,业务在约定目录。

Show full SKILL.md (188 more words)Show less
第 3 步:命令与中间件
  • 命令:路径是路由 SSOT;execute 读 params / args / input(含 session 字段若需要)
  • 命令目录直接形成空格分隔的路由:commands/[note]/index.ts 形成 <note>,commands/add/[note]/index.ts 形成 add <note>。只有插件显式配置 commandNamespace: 'remind' 时,才分别形成 remind <note> 与 remind add <note>;默认没有命名空间。动态参数至多一个且必须位于末段。
  • 中间件:洋葱模型,明确是否 await next()
  • 组件:消息渲染,不替代服务层
  • AI 工具:inputSchema 与 execute 入参一致;副作用边界清晰
第 4 步:定时 / 数据库 / Web
  • 定时:照抄 cron-template
  • 数据库:先 数据建模,再 model / service 骨架
  • Web:definePage + 客户端与 Node 分离

结构在「单文件 vs 拆模块」间犹豫时看 实现分支参考。 已混乱的旧插件改用 refactoring / migrate skill,不要硬扩。

第 5 步:验证
  1. package.json#zhin + plugin.ts default export
  2. 相对导入 .js
  3. 无 usePlugin / MessageCommand 新增
  4. lifecycle / Host has-use
  5. pnpm --filter <pkg> test 或 Sandbox 手测命令原文
  6. 改 Tool / Skill / Agent / Hook 时运行对应 authoring boundary;发布插件再运行 pnpm check:plugin-capability-publish

常见分支

  • 很小:现有插件最小改动,不过度拆目录
  • 多能力:先服务端主流程,再拆数据访问与 pages/
  • 像适配器:停,改用 adapter 工作流

失败与兜底

触发一线仍失败
命令无响应查路径路由、zhin.features 是否含 @zhin.js/command、前缀配置对照 minimal-bot / first-plugin 文档
does not default-export a Plugin definition改成 export default definePlugin(...)查 entry 路径
Host use 炸先 has(token);确认 Host 插件已装查精简安装分档
tsc 导入错加 .js;查 exports对照官方插件 package.json
控制台页 404查 definePage / catalog 注册查 Host entries API

不要做什么

  • 不要脚手架或新增 usePlugin / MessageCommand / bootstrapNode
  • 不要绕过 Message.$reply / Adapter.sendMessage 发送链
  • 不要把适配器协议写进普通插件
  • 不要无复杂度时拆大量空目录
  • 代级状态只通过 snapshot resources / 当前 operation 的 Generation View 解析;禁止裸模块级单例或 createGenerationStore

输出要求

  1. 任务判断(哪类能力)
  2. 方案 / 已改文件
  3. 关键约束(Feature、lifecycle、config)
  4. 验证结果
  5. 剩余风险(仅与本次相关)

© 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 14 other files (references, assets) in .github/skills/zhin-plugin-standard-development of zhinjs/zhin.

  • SKILL.md
  • assets/ai-tool-template.ts
  • assets/component-template.tsx
  • assets/cron-template.ts
  • assets/database-service-template.ts
  • assets/event-hooks-template.ts
  • assets/minimal-plugin-template.ts
  • assets/model-definition-template.ts
  • assets/modular-plugin-entry-template.ts
  • assets/plugin-web-entry-template.tsx
  • references/database-modeling.md
  • references/implementation-branches.md
  • references/plugin-capabilities.md
  • references/plugin-directory-layout.md
  • test-prompts.json

Open the folder on GitHubat commit fd5029a

Compare with similar skills

Zhin Plugin Standard Development next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Zhin Plugin Standard Development compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Zhin Plugin Standard Development this skillzhinjs/zhin137—~1.6kAutomated safety check: PassMIT
Agent Browserquran/quran.com-frontend-next1.9k42 repos~3.3kAutomated safety check: PassNone
Process Inboxtelegramdesktop/tdesktop33k2 repos~4.5kAutomated safety check: PassGPL-3.0
Perform Tasktelegramdesktop/tdesktop33k2 repos~3kAutomated safety check: PassGPL-3.0
Brave Searchbadlogic/pi-skills2.6k6 repos~592Automated safety check: PassMIT
Continuetelegramdesktop/tdesktop33k2 repos~9.4kAutomated safety check: PassGPL-3.0

Similar skills

  • Agent Browser

    quran/quran.com-frontend-next

    Automates browser interactions for web testing, form filling, screenshots, and data extraction.

    1.9k GitHub starsUsed in 42 repos~3.3k tokens
    Productivity & AutomationAuto-check passed
  • Process Inbox

    telegramdesktop/tdesktop

    Process the local ignored ai-tdesktop inbox into durable, independently testable Telegram Desktop task records while task execution worktrees remain active.

    33k GitHub starsUsed in 2 repos~4.5k tokens
    Productivity & AutomationAuto-check passed
  • Perform Task

    telegramdesktop/tdesktop

    Resolve, start or resume, implement, review, test, and publish exactly one existing ai-tdesktop task by short slug or full dated id, including rare blocked retries and split-required results.

    33k GitHub starsUsed in 2 repos~3k tokens
    Productivity & AutomationAuto-check passed
  • Brave Search

    badlogic/pi-skills

    Web search and content extraction via Brave Search API. An agent skill from badlogic/pi-skills.

    2.6k GitHub starsUsed in 6 repos~592 tokens
    Productivity & AutomationAuto-check passed
  • Continue

    telegramdesktop/tdesktop

    Continue autonomous Telegram Desktop development from the shared ai-tdesktop repository.

    33k GitHub starsUsed in 2 repos~9.4k tokens
    Productivity & AutomationAuto-check passed
  • Feishu Doc

    openclaw/openclaw

    Feishu document read/write workflows. An agent skill from openclaw/openclaw.

    392k GitHub stars~516 tokensUpdated today
    Productivity & AutomationAuto-check passed

More from zhinjs/zhin

All 11 skills in this repo
  • Refactor existing Zhin.js plugins into a cleaner standard structure.

    137 GitHub stars~1.1k tokensUpdated 15 days ago
    Auto-check passed
  • Migrate legacy Zhin.js plugins and projects to the convention-based Plugin Runtime — from usePlugin/getPlugin/addCommand/addMiddleware/addComponent/addTool/addCron/declareConfig/useContext and…

    137 GitHub stars~1.6k tokensUpdated 15 days ago
    Auto-check passed
  • Zhin Audit

    zhinjs/zhin

    Audit Zhin.js changes for security, performance, lifecycle, and architecture regressions.

    137 GitHub stars~596 tokensUpdated 15 days ago
    Auto-check: notes
  • GitHub CLI

    zhinjs/zhin

    使用 gh CLI 处理内置 GitHub Tool 未覆盖的 Issue、PR、Release、Workflow、搜索和 API 操作。

    137 GitHub stars~366 tokensUpdated 15 days ago
    Auto-check passed
  • Wecom

    zhinjs/zhin

    企业微信平台管理能力。当用户在企业微信中请求用户信息查询、部门架构查询、 发送文本消息时使用。即使用户没有提到企业微信,只要上下文是企业微信/WeCom 场景且涉及用户查询、部门管理或消息发送,就应触发。

    137 GitHub stars~297 tokensUpdated 15 days ago
    Auto-check passed
  • Checkin

    zhinjs/zhin

    签到积分系统查询能力。当用户想查看自己的积分、签到排行榜、连签天数、 或了解签到奖励时使用。日常签到通过聊天命令触发,此技能提供积分查询的 AI 工具。

    137 GitHub stars~167 tokensUpdated 15 days ago
    Auto-check passed

Questions about Zhin Plugin Standard Development

What does Zhin Plugin Standard Development do?

Implement Zhin.js plugins with Plugin Runtime. An agent skill from zhinjs/zhin. Zhin Plugin Standard Development is an agent skill from zhinjs/zhin.js plugins with Plugin Runtime.

When should I use Zhin Plugin Standard Development?

Zhin Plugin Standard Development fits situations like: asked to create a plugin; agent capabilities; HTTP Host integration.

How do I install Zhin Plugin Standard Development in Claude Code?

Run `npx skills add zhinjs/zhin --skill zhin-plugin-standard-development -a claude-code`. Or copy the skill folder (.github/skills/zhin-plugin-standard-development in zhinjs/zhin) into .claude/skills/zhin-plugin-standard-development in your project. Claude Code loads it when a task matches its description.

How do I install Zhin Plugin Standard Development in Codex?

Run `npx skills add zhinjs/zhin --skill zhin-plugin-standard-development -a codex`. Or copy the skill folder (.github/skills/zhin-plugin-standard-development in zhinjs/zhin) into .agents/skills/zhin-plugin-standard-development in your project. Codex loads it when a task matches its description.

Can I use Zhin Plugin Standard Development in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add zhinjs/zhin --skill zhin-plugin-standard-development -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/zhin-plugin-standard-development, .gemini/skills/zhin-plugin-standard-development, .github/skills/zhin-plugin-standard-development and .opencode/skills/zhin-plugin-standard-development in your project.

What does Zhin Plugin Standard Development need to run?

Going by SKILL.md and its folder, Zhin Plugin Standard Development needs TypeScript for the scripts in its folder and the command-line tools its instructions call (pnpm). Our summary lists: Node.js.

Does Zhin Plugin Standard Development access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Zhin Plugin Standard Development safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Zhin Plugin Standard Development use?

Zhin Plugin Standard Development is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Zhin Plugin Standard Development use?

About 1.6k tokens (SKILL.md is roughly 6.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 3k tokens, read only when the agent opens those files.

What are the alternatives to Zhin Plugin Standard Development?

Skills that share tags, products or a category with Zhin Plugin Standard Development: Agent Browser (quran/quran.com-frontend-next, 1.9k stars), Process Inbox (telegramdesktop/tdesktop, 33k stars), Perform Task (telegramdesktop/tdesktop, 33k stars) and Brave Search (badlogic/pi-skills, 2.6k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Zhin Plugin Standard Development?

zhinjs (a GitHub organization) maintains it in zhinjs/zhin, which has 137 GitHub stars. The repository holds 11 skills in this directory. The repository was last updated on September 23, 2026.

Source: zhinjs/zhin on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.