Skill 从零编写到发布上线保姆级实战全流程发布日期2026-08-07作者gouxinjie主题CodeBuddy Skill 的完整生命周期——从设计、编写、打包到发布 npm、配置自动发布前置阅读《Skill技能详解从概念到发布》了解 Skill 基本概念一、写在前面上一篇博客 Skill技能详解 讲了Skill 是什么这篇直接上干货如何从一个想法把一个 Skill 完整地开发、打包、发布到 npm并配置打 tag 自动发布的全自动化流程。我用自己真实创建并上线的xinjie-review全能代码审查技能作为完整案例每一步都有可复制的代码。最终效果发布完成后用户只需一条命令即可使用你的技能npminstall-gxinjie-review而你维护技能时只需npmversion patchgitpush--tagsnpm 就会自动更新全程零手动干预。使用如下二、第一步设计 Skill动手写之前先想清楚三件事。这一步决定技能好不好用。1. 明确做什么、不做什么以xinjie-review为例我定义它做什么对前端/后端/CSS/文档/流程图/依赖安全进行质量审查输出分级报告不做什么不擅自修改代码除非用户明确要求修复——这是重要的边界约束边界约束写进SKILL.md能防止 AI 在审查过程中意外改动代码。2. 写清楚description最重要description决定 AI何时自动调用这个技能。它要具体不能泛泛而谈# ❌ 太泛AI 难以判断description:代码审查# ✅ 具体AI 一看就懂description:全能代码与文档审查专家xinjie 审查。适用于对前端、后端、CSS/样式、Markdown 文档、流程图等进行系统性质量审查覆盖正确性、性能、可访问性、安全性、可维护性、逻辑与语句通顺度等维度输出结构化分级审查报告。3. 规划目录结构一个 Skill 是独立目录至少包含SKILL.mdxinjie-review/ ├── SKILL.md # 必填核心定义 ├── README.md # 技能说明可选 ├── references/ # 分类检查清单可选按需加载 ├── examples/ # 示例输出可选帮助格式不走样 └── scripts/ # 辅助脚本可选三、第二步编写 SKILL.mdSKILL.md由YAML FrontmatterMarkdown 指令两部分组成。Frontmatter元数据---name:xinjie-reviewdescription:全能代码与文档审查专家xinjie 审查。适用于对前端、后端、CSS/样式、Markdown 文档、流程图等进行系统性质量审查...allowed-tools:Read,Write,Search,Grep,ListFiles,Bash---allowed-tools用最小权限原则只授予审查必需的只读工具。正文给 AI 的指令正文是喂给模型的培训手册建议包含身份定位一句话说明这个 AI 现在扮演什么角色核心目标要达成什么审查维度分类型列出要检查的具体项工作流程步骤化让 AI 按顺序执行分级标准统一 判定规则保证不同模型输出一致边界约束哪些不能做报告格式规定输出模板以分级标准为例这是保证输出质量稳定的关键| 级别 | 图标 | 判定标准 | |------|------|----------| | 阻断级 | | 功能错误、数据错误、崩溃、明显安全隐患 | | 严重级 | | 有明确 Bug 风险、边界情况会出错 | | 建议级 | | 可维护性、可读性可改进 | | 风格级 | | 命名、格式、风格 | 判定优先级安全 正确性 性能 可维护性 风格本地验证写完先放到.codebuddy/skills/或~/.codebuddy/skills/在 CodeBuddy 里实际跑一次用真实代码验证输出质量。我最初就是用它审查一段 Vue 组件准确识别出了 XSS、异步无捕获、内存泄漏等问题——验证通过再进入下一步。四、第三步打包成 npm 包这里有个关键认知Skill 不是传统 JS 库用户不是import它而是通过安装脚本把它放到 CodeBuddy 的技能目录。所以我们的玩法是把 Skill 打成 npm 包用postinstall钩子自动安装。目录结构改造project/ ├── package.json # npm 包清单 ├── README.md # npm 首页 使用说明 ├── bin/ │ ├── install.js # 安装脚本 │ └── uninstall.js # 卸载脚本 └── skills/ └── xinjie-review/ # 技能本体package.json核心是钩子{name:xinjie-review,version:1.0.0,description:CodeBuddy 全能代码与文档审查技能...,files:[skills/,bin/],bin:{xinjie-review-install:bin/install.js},scripts:{postinstall:node bin/install.js,postuninstall:node bin/uninstall.js,prepublishOnly:npm pack}}三个关键点postinstall/postuninstall用户npm install/npm uninstall时自动执行完成技能安装/卸载files只打包skills/和bin/把.codebuddy/等开发配置排除在外prepublishOnly发布前自动npm pack校验防止发错内容安装脚本 bin/install.js核心逻辑把skills/xinjie-review复制到~/.codebuddy/skills/#!/usr/bin/env nodeconstfsrequire(fs);constpathrequire(path);constosrequire(os);constSKILL_NAMExinjie-review;constSRCpath.join(__dirname,..,skills,SKILL_NAME);constTARGETpath.join(os.homedir(),.codebuddy,skills,SKILL_NAME);functioncopyDir(src,dest){fs.mkdirSync(dest,{recursive:true});for(constentryoffs.readdirSync(src,{withFileTypes:true})){constspath.join(src,entry.name);constdpath.join(dest,entry.name);entry.isDirectory()?copyDir(s,d):fs.copyFileSync(s,d);}}copyDir(SRC,TARGET);console.log(✅ 技能已安装到${TARGET});生产版本可加--project参数支持安装到当前项目.codebuddy/skills/便于团队共享。发布前检查npmpack --dry-run# 检查打包内容只应含 skills/ 和 bin/npmview包名# 查包名是否已被占用404 表示可用五、第四步发布到 npm1. 登录npmlogin2. 首次发布npmpublish发布后立即验证npmview xinjie-review version⚠️ 刚发布的包npm view可能短暂返回 404是 registry 传播延迟等几十秒再查即可。3. 用户侧体验用户现在可以这样用npminstall-gxinjie-review# postinstall 自动安装技能然后在 CodeBuddy 里直接说审查 src/components/Button.vueAI 自动调用技能。六、第五步配置打 tag 自动发布手动npm publish太麻烦也容易忘记。我用GitHub Actions实现了推送v*tag 自动发布。创建.github/workflows/npm-publish.ymlname:Publish to npmon:push:tags:-v*# 推送 v 开头的 tag 才触发jobs:publish:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-uses:actions/setup-nodev4with:node-version:20registry-url:https://registry.npmjs.org/-name:Verify packagerun:npm pack--dry-run# 发布前校验-name:Publish to npmrun:npm publishenv:NODE_AUTH_TOKEN:${{secrets.NPM_TOKEN}}配置 npm 令牌关键一步npmjs.com→ Access Tokens → Generate New Token类型选 AutomationGitHub 仓库→ Settings → Secrets → Actions → New repository secretName:NPM_TOKENValue: 粘贴令牌之后的发布流程全自动npmversion patch# 自动改版本号 打 tagv1.0.1gitpush# 推送 maingitpush--tags# 推送 tag → 触发 Actions → 自动发布实测验证推送v1.0.1后约 1 分钟npm view xinjie-review version返回1.0.1全流程跑通。七、经验总结做对了的事决策收益description写得具体AI 自动识别准确分级标准 边界约束写进 SKILL.md输出稳定、安全files限定打包内容包干净、不发多余文件postinstall钩子用户零操作安装GitHub Actions 打 tag 发布版本管理 自动发布踩过的坑包名冲突先npm view查重再定名避免发布失败npm view刚发布返回 404registry 有延迟不是没发布成功.codebuddy/开发目录务必用files排除不能随包发布技能名 ≠ npm 包名技能名在SKILL.mdnpm 包名在package.json两者独立一句话流程写 SKILL.md → 本地验证 → 打包成 npm 包 → npm publish → 配 GitHub Actions → 打 tag 即上线 感谢阅读想了解更多 我的博客网站 | 记录思考分享干货 我的个人主页 | 关于我、开源项目