如何为 VibeSkills 编写自己的 SkillSKILL.md 规范与目录结构完整教程【免费下载链接】Vibe-SkillsIntelligent Skill routing and workflow orchestration for AI agents — 21.12 pp reward, −29.6% tokens on SkillsBench with DeepSeekV4Flash-VE.项目地址: https://gitcode.com/gh_mirrors/vi/Vibe-SkillsVibeSkills 是一个面向 AI Agent 的智能技能路由与工作流编排框架其核心单元就是Skill技能包。本文将作为面向新手的 VibeSkills Skill 开发教程带你从零理解 SKILL.md 规范、标准目录结构以及如何用官方脚手架完成「编写 → 校验 → 打包」全流程最终把自定义 Skill 交付给 Agent 自动触发。1. 什么是 VibeSkills 里的 Skill可以把 Skill 理解为给 AI Agent 的「上岗培训手册」它是一个模块化、自包含的包为特定领域或任务提供专业知识、工作流和工具把通用 Agent 变成专岗专家。一个 Skill 通常能提供四类价值 专项工作流— 特定领域的多步骤流程工具集成— 操作特定文件格式或 API 的说明领域知识— 业务规则、数据模式、行业术语捆绑资源— 脚本、参考文档、模板等可复用资产仓库 bundled/skills/ 目录下内置了 200 多个 Skill是理解本规范的最好教材。官方还有一个专门教你造 Skill 的「技能」bundled/skills/skill-creator/SKILL.md本文所有规范均出自它。2. 目录结构一个 Skill 的标准解剖每个 Skill 的必备件只有一个文件——SKILL.md其余资源目录均为可选skill-name/ ├── SKILL.md # 必需元数据 指令正文 └── 捆绑资源可选 ├── scripts/ # 可执行脚本Python/Bash 等 ├── references/ # 按需加载进上下文的参考文档 └── assets/ # 用于输出的文件模板、图标、字体等两个真实例子可对照阅读纯文档型 Skill只有一个 SKILL.mdbundled/skills/brainstorming/SKILL.md文档 脚本混合型 Skillbundled/skills/scrapling/SKILL.md附带scripts/目录⚠️不要在 Skill 里添加README.md、CHANGELOG.md、安装指南之类的附加文档——它只服务于 AI Agent 执行任务多余文件只会增加噪音。3. 编写 SKILL.mdFrontmatter 与正文SKILL.md由两部分组成写法上各有关键要点3.1 Frontmatter唯一的「触发开关」文件头部的 YAML 元数据只有两个必需字段不要添加其他字段字段作用写法要点name技能名称与目录名一致简洁明确description核心触发机制写清「做什么」「何时用」具体场景、文件类型、触发任务 关键认知Agent 在触发前只读取name和description。所以何时使用的信息必须写进description而不是正文——正文里的 When to Use 章节对触发毫无帮助。可参考 bundled/skills/scrapling/SKILL.md 中description Use when…的写法。3.2 正文祈使句 渐进式披露正文Markdown 指令在技能触发后才加载用祈使句/不定式描述操作步骤默认假设 Agent 已经很聪明只补充它不具备的知识每段文字都要值回 token正文控制在500 行以内接近上限时拆分为独立参考文件并在正文中明确写「何时该去读哪个文件」支持多变体多框架、多场景时正文只保留核心流程和选型指引变体细节拆到references/下4. 三类捆绑资源scripts / references / assets目录放什么什么时候用scripts/确定性、可重复执行的代码同一段代码需要反复重写、要求结果稳定时脚本可执行而无需读入上下文极省 tokenreferences/按需加载的参考文档API 文档、数据模式、公司政策等10k 词的大文件应在 SKILL.md 中提供检索提示assets/直接用于输出的文件模板、样板代码、字体、示例文档——Agent 复制/修改它们但不读进上下文黄金法则信息要么在SKILL.md要么在references/不要两边都放参考文件直接由SKILL.md一层引用避免深层嵌套超过 100 行的参考文件顶部加目录。5. 编写流程6 步让 Skill 跑起来官方提供了完整脚手架无需手写模板 理解需求— 收集具体使用例子用户会说什么话触发这个 Skill规划资源— 分析每个例子列出需要沉淀的 scripts / references / assets初始化骨架— 运行 scripts/init_skill.pyscripts/init_skill.py skill-name --path output-directory自动生成带 frontmatter 的 SKILL.md 模板与三个资源目录编辑内容— 先实现资源文件脚本必须实际运行测试再撰写 SKILL.md多步骤流程与输出格式可参考 references/workflows.md 和 references/output-patterns.md打包分发— 运行 scripts/package_skill.py 指向技能目录它会先自动校验frontmatter 格式、必填字段、命名规范、资源引用通过后才生成.skill分发包实战迭代— 在真实任务中使用发现卡点就回头修订 SKILL.md仓库根目录的 SKILL.md 是 VibeSkills 的运行时入口技能vibe运行时在任务规划阶段会读取各候选技能的 SKILL.md 来决定编排方案——这正说明了写好description的决定性作用。6. 进阶技巧匹配任务的「自由度」根据任务的脆弱程度选择约束强度 高自由度纯文字指引多种做法都可行、依赖上下文判断中自由度伪代码 参数有推荐模式、允许适度变化低自由度具体脚本、极少参数操作脆弱易错、必须保持一致性类比悬崖上的窄桥需要明确护栏开阔原野则允许自由选路。7. 参考资料速查资料路径官方 Skill 创作指南bundled/skills/skill-creator/SKILL.md初始化脚手架init_skill.py打包与校验脚本package_skill.py轻量校验工具quick_validate.py技能契约 Schema路由层schemas/skill.schema.json内置技能全集学习范本bundled/skills/按照本教程的 SKILL.md 规范与目录结构你编写的每一个 Skill 都会被 VibeSkills 的路由系统识别并编排进工作流——写一份精炼的description是它被正确触发的第一步。【免费下载链接】Vibe-SkillsIntelligent Skill routing and workflow orchestration for AI agents — 21.12 pp reward, −29.6% tokens on SkillsBench with DeepSeekV4Flash-VE.项目地址: https://gitcode.com/gh_mirrors/vi/Vibe-Skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
