从VibeWise学做一个Claude Code插件Skills、Hooks与Marketplace架构完全拆解【免费下载链接】vibe-wiseA Claude Code plugin that helps you learn how to build while AI writes the code.项目地址: https://gitcode.com/gh_mirrors/vi/vibe-wiseVibeWise 是一个开源的 Claude Code 插件You build. AI writes.它把学习放在写代码之前你先思考设计方案AI 负责写代码并解释改动。它的整个功能只靠三样东西搭起来——Skills技能、**Hooks钩子**和Marketplace插件市场没有任何后端、账号或额外依赖。拆解这个不到百行的插件就是学习 Claude Code 插件开发最快的路径 一、VibeWise 到底解决什么问题大多数 AI 编码工具是你提需求它直接写。VibeWise 反其道而行Build Checkpoint先问你的思路等你推理出问题该怎么解Design Checkpoint你确认设计后它才记录方案仍然不写代码Implementation Checkpoint你明确批准后AI 才实施并汇报改了什么、为什么。完整体验可以读 README.md 里的 Notion 风格笔记应用对话示例以及 docs/demos/notion-dupe.md 的完整演练记录。 对新手最友好的一点回答用大白话就行随时可以说 skip 或让 AI 解释陌生概念。二、目录结构总览一个插件的最小骨架整个仓库就是 Claude Code 插件的标准目录结构非常适合照着模仿目录/文件作用.claude-plugin/插件与市场的元数据上架身份证skills/learn/Learn 技能定义/vibe-wise:learn命令的行为skills/reset/Reset 技能备份学习笔记并重新开始hooks/SessionStart 钩子会话启动时自动恢复学习上下文tests/纯 Python 单元测试35 用例docs/development.md开发说明与本地校验流程注意一个反直觉的事实核心逻辑不是代码而是 Markdown。Skills 是写给 AI 看的操作手册真正执行它们的是 Claude 本身。三、Marketplace两步完成上架插件要能被/plugin install安装需要两个 JSON 文件都在 .claude-plugin/ 里1. 插件身份证— plugin.json声明name、version、description、作者和keywordslearning、architecture、engineering。这是插件的名片Marketplace 用它展示信息。2. 市场目录— marketplace.json一个小小的商品清单plugins数组里只有两项插件名和source: ./——表示插件根目录就是仓库本身plugins: [ { name: vibe-wise, source: ./ } ]✅ 新手要点一个仓库既可以放插件、又可以放市场市场指向./即可。用户执行/plugin marketplace add之后才能安装你仓库里的插件。四、Skills用 Markdown 给 AI 写岗位说明书Skill 的本质是一个带 YAML 头的 Markdown 文件夹。打开 skills/learn/SKILL.md头部的三个字段决定了它的行为name: learn→ 安装后生成/vibe-wise:learn命令description→ 告诉 AI 什么时候该用这个技能disable-model-invocation: true→只允许用户手动触发AI 不会自作主张调用。正文则是纯自然语言的工作守则例如学习者拥有设计权。先问他的思路然后等待。保持引导最小化……学习和学习者控制权优先于构建速度。技能还能引用同目录下的其他文件按需加载skills/learn/ 就是这样拆分的文件何时被读取behavior.md每次开发全程遵循的行为准则onboarding.md首次使用时逐题引导一次只问一个问题state-templates.md创建本地学习状态文件时套用模板skills/reset/SKILL.md 同样是一套流程说明先跑只读预览 → 用选择器让用户确认 → 才执行备份与重置。可以看到确认后才动手这类安全交互也是用 Markdown 写出来的。五、Hooks让学习上下文在重启后自动恢复这是 VibeWise 最有教育价值的部分。问题场景你关了终端再打开 Claude Code之前聊到的设计决策全忘了。VibeWise 用一个钩子解决它 1. 声明触发时机— hooks/hooks.jsonSessionStart: [ { matcher: startup|resume|clear|compact|fork, hooks: [ { type: command, command: python3 \${CLAUDE_PLUGIN_ROOT}/hooks/session_start.py\ } ] } ]五种会话开始事件启动、恢复、清空、压缩、分支都会触发这个脚本${CLAUDE_PLUGIN_ROOT}会自动替换为插件安装目录。2. 脚本只做一件事发阅读指令— session_start.py向上查找最近的.vibe-wise/目录遇到.git边界即停绝不借用别的仓库的状态检查 profile.md 是否处于激活非暂停状态如果有就输出一段 JSON把去读哪些文件的指令注入 AI 的上下文。⚠️ 精妙之处在于钩子不把笔记内容塞进上下文只发一段固定大小的指令。这样无论学习历史涨到多大钩子输出都不会膨胀——docs/development.md 中专门解释了为什么刻意不解析对话记录。 配套测试在 tests/test_session_start.py 和 tests/test_reset.py覆盖激活、暂停、符号链接拒绝、worktree 边界等场景python3 -m unittest discover -s tests即可运行。六、本地状态.vibe-wise/三个 Markdown 文件插件学到的东西全部存在你项目的.vibe-wise/目录而不是插件目录只有三个文件模板见 state-templates.mdprofile.md—— 学习者画像经验水平、目标、偏好progress.md—— 学习进度已掌握/待强化的概念以及Pending decision等待你确认的设计决策project-map.md—— 项目地图组件、主流程、未知项。建议把.vibe-wise/加进.gitignore学习笔记不进 Git。想推倒重来运行/vibe-wise:reset原始笔记会先备份到backups/子目录源码完全不受影响。七、动手体验安装这个插件git clone https://gitcode.com/gh_mirrors/vi/vibe-wise也可以在 Claude Code 中依次执行/plugin marketplace add nykooi1/vibe-wise /plugin install vibe-wisevibe-wise重启后在你的项目里运行/vibe-wise:learn然后描述你想构建的东西——接下来 AI 会先问你打算怎么做而不是直接开写。八、从 VibeWise 提炼的插件开发清单 ✅步骤VibeWise 的做法你可以抄的技巧1. 元数据两个 JSON 文件plugin.jsonmarketplace.json指向./2. 技能每个能力一个 Markdown 文件夹用disable-model-invocation控制触发方式3. 行为规则自然语言写岗位说明书按需拆分成子文档避免单次加载过多4. 自动化SessionStart 钩子 小 Python 脚本钩子输出保持恒定大小内容让 AI 自己读5. 状态项目内的本地 Markdown数据放用户项目插件只读边界清晰6. 质量35 个纯 Python 测试钩子可用真实 JSON stdin 在临时项目里测试一句话总结Claude Code 插件 JSON 声明我是谁 Markdown 教 AI怎么做 钩子脚本管什么时候做。VibeWise 用最小的组件实现了完整的体验闭环是学习插件架构的最佳范本。照着它的目录结构起步你也能在几小时内做出自己的第一个插件 【免费下载链接】vibe-wiseA Claude Code plugin that helps you learn how to build while AI writes the code.项目地址: https://gitcode.com/gh_mirrors/vi/vibe-wise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考