【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载本文以 Context Hub 仓库中的测试样例 SKILL.md 为核心逐字段拆解一个标准 skill 的内容结构frontmatter 正文步骤并结合chubCLI 的构建、检索与获取源码说明该文件是如何被chub build解析为注册表条目、被chub search命中、再被chub get完整取回的。读完后你可以独立编写一个符合 Context Hub 内容规范的 skill并验证其在构建与检索链路中的完整行为。一、这个文件是什么Context Hub 的 deploy skill 测试样例SKILL.md位于cli/test/fixtures/testskills/skills/deploy/目录下是chubCLI 端到端测试套件使用的一个内容样例fixture。它模拟了一个真实社区作者author 目录名为testskills发布的一个名为deploy的 skill——一个面向 CI/CD 流水线的部署自动化技能。从内容组织规范看该路径遵循 docs/content-guide.md 中定义的“作者 → 类型 → 条目”三级目录结构内容按作者vendor/org组织其下按类型分为docs与skills每个条目一个目录skill 的入口文件固定命名为SKILL.mdmy-content/ acme/ docs/ widgets/ DOC.md skills/ deploy/ SKILL.md # a skill由于它被放进chub build的输入目录参与构建构建产物中的注册表 id 会带有作者前缀成为testskills/deploy——这一点在后文的 e2e 测试断言中会被反复验证。二、SKILL.md 全文解析原文档全文很短但每个部分都对应着chub build的一个具体解析动作。下面完整继承原文内容并逐段展开。2.1 YAML Frontmatter原文 frontmatter 如下--- name: deploy description: Deployment automation skill for CI/CD pipelines metadata: updated-on: 2026-01-01 source: community tags: deploy,ci,automation ---各字段在构建链路上的作用依据 cli/src/commands/build.js 中discoverAuthor的实现字段样例值构建时的处理namedeploy必填。缺失会直接报错missing name in frontmatter并跳过该条目同名 skill 重复会被报duplicate skill name错误descriptionDeployment automation skill for CI/CD pipelines缺失只产生 warning它是 BM25 检索索引的核心语料e2e 测试正是靠它被关键词 “deployment” 模糊命中metadata.updated-on2026-01-01记录内容最后修订日期缺失时源码会回退为构建当天的日期new Date().toISOString().split(T)[0]metadata.sourcecommunity信任级别合法取值为official、maintainer、community见 docs/content-guide.md 的字段表缺失时默认community并产生 warningmetadata.tagsdeploy,ci,automation逗号分隔字符串解析为数组后用于chub search --tags tag过滤值得注意的是与DOC.md不同skill 的 frontmatter不需要metadata.languages和metadata.versions——构建源码中对 doc 分支会强制校验这两项缺失即报错而 skill 分支完全没有这一逻辑因为 skill 是语言无关的language-agnostic这一点也被 docs/content-guide.md 的 “Skills have the same fields as docs exceptlanguagesandversionsare not required” 明确说明。另外可以观察到一个细节docs/content-guide.md 中给出的 SKILL.md frontmatter 示例还包含revision: 1内容修订号而本样例省略了它且构建照常通过——从源码结构看discoverAuthor并没有对revision做任何校验因此它是规范建议字段而非构建强制字段。2.2 正文内容frontmatter 之后的正文是 skill 的实际指令内容# Deploy Skill Automate deployments with this skill. ## Steps 1. Build the project 2. Run tests 3. Deploy to production正文即 Agent 获取该 skill 后看到并执行的操作指南三步标准 CI/CD 流程——构建项目、运行测试、部署到生产环境。e2e 测试断言chub get testskills/deploy的输出必须同时包含# Deploy Skill标题与Automate deployments正文见 cli/test/e2e.test.js 第 363–367 行说明正文内容被原样透传给用户构建过程不做任何改写。三、构建链路chub build 如何消费这份 SKILL.mdchub build content-dir的完整流程在 cli/src/commands/build.js 中实现对该样例的作用可分为四步3.1 入口文件发现findEntryFiles递归遍历每个作者目录文件名恰好等于DOC.md或SKILL.md的文件被识别为入口文件并据此标记类型cli/src/commands/build.js 第 20–31 行。本样例因此被识别为type: skill。同时listDirFiles与dirSize会把条目目录下所有文件列表与总字节数一并记入注册表条目——本样例目录下只有SKILL.md一个文件因此没有额外可拉取的参考文件。3.2 Frontmatter 解析正文与元数据由 cli/src/lib/frontmatter.js 中的parseFrontmatter切分它用正则^---\r?\n([\s\S]*?)\r?\n---\r?\n?定位 frontmatter 块再用yaml库解析为对象。YAML 解析失败时抛出FrontmatterParseError携带 1 起始的行列号相对完整 frontmatter 文档含开头---行构建器会输出形如skills/deploy/SKILL.md:行:列: invalid YAML frontmatter — …的定位错误方便作者快速修复。3.3 生成注册表与搜索索引skill 分支cli/src/commands/build.js 第 151–167 行会生成如下结构的条目{ id: testskills/deploy, // ${authorName}/${name} name: deploy, description: Deployment automation skill for CI/CD pipelines, source: community, tags: [deploy, ci, automation], path: testskills/skills/deploy, files: [SKILL.md], size: 目录总字节数, lastUpdated: 2026-01-01, }最终写入output/registry.jsonversion: 1.0.0、生成时间戳、docs与skills两大数组同时用buildIndex生成 BM25 搜索索引search-index.json其中每个条目打上_type: skill标记内容目录树则整体拷贝到输出目录跳过作者级registry.json。常用构建命令与 docs/content-guide.md 一致chub build test-content/ # 构建到 test-content/dist/ chub build test-content/ -o dist/ # 自定义输出目录 chub build test-content/ --validate-only # 只校验不产出报告 docs/skills 数量与错误 chub build test-content/ --base-url url # 写入 CDN 部署基地址四、检索与获取该样例在 e2e 测试中的行为验证cli/test/e2e.test.js 用本 fixture 构建出一个包含 3 个 doc 1 个 skill 的注册表以下断言可直接复制为可验证的预期行为注册表计数registry.json中docs.length 3、skills.length 1该唯一 skill 即testskills/deploy第 86–90 行--validate-only模式会输出 “3 docs, 1 skills”第 97–101 行。描述模糊检索chub search deployment --json的results[0].id testskills/deploy——关键词只出现在 description 中证明 BM25 索引确实索引了 skill 描述第 121–125 行。标签过滤chub search --tags automation --json恰好返回该 skill 一条第 134–138 行对应 frontmatter 中tags的第三项。内容获取chub get testskills/deploy输出包含# Deploy Skill与Automate deployments第 363–367 行。获取侧的类型判定在 cli/src/commands/get.js 中const type entry.languages ? doc : skill第 35 行——由于 skill 条目没有languages字段chub get无需--lang即可直接取回 skill 全文入口文件名按类型切换为SKILL.md第 67 行。如果条目目录除入口文件外还有参考文件则可用--file path精确拉取或--full拉取全部本样例只有SKILL.md因此不会触发 “Additional files available” 页脚。此外search命令对 skill 条目的展示会打印其path与文件列表行为在 cli/tests/commands/search.test.js 中有专门用例覆盖。构建侧的单测 cli/tests/commands/build.test.js 同样断言build该 fixture 目录产出 3 个 doc、1 个 skill。五、对照参考CLI 自带的 get-api-docs skill仓库中还有一份“生产级” skill 可供对照cli/skills/get-api-docs/SKILL.md。它的 frontmatter 结构与本样例完全同构namedescriptionmetadata.updated-on/source/tags区别在于正文是一份给 Agent 的可执行流程指南先chub --help确认安装再chub search keywords --json选 id然后chub get id --lang py取文档最后用chub annotate/chub feedback沉淀经验与反馈。cli/README.md 说明了如何把它安装进 Claude Code.claude/skills/或 Cursor.cursor/rules/等 Agent 工具——也就是说deploy样例所展示的格式正是被 Agent 消费的 skill 的标准载体。六、编写你自己的 SKILL.md实践清单基于本样例与源码行为一个可被chub build正确收录的 skill 应满足目录content/author/skills/entry-name/SKILL.md入口文件名必须精确为SKILL.mdfrontmatter 必填name缺失构建错误description、metadata.source、metadata.updated-on强烈建议填写缺失仅 warning 或自动回退但会影响检索质量与展示metadata.tags用英文逗号分隔正文面向 Agent 的清晰步骤指令构建过程原样透传不做改写验证chub build content/ --validate-only确认 skills 计数与 warning再chub search description 中的关键词 --json与chub get author/entry-name验证检索命中与内容取回避免踩坑同一作者下 skillname不得重复、跨作者 skillid不得冲突均为构建期硬错误skill 无需也无法声明languages/versions与 doc 的多语言多版本模型不同。综上testskills/skills/deploy/SKILL.md虽只有 17 行却是 Context Hub skill 格式的最小完整范例frontmatter 决定它如何被索引与过滤正文决定 Agent 拿到后做什么而 cli/src/commands/build.js、cli/src/lib/frontmatter.js、cli/src/commands/get.js 与 cli/test/e2e.test.js 共同构成了从“一个 Markdown 文件”到“可检索、可获取的注册表条目”的完整证据链。赞分享【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载相关推荐ClawHub Skill 格式完全指南SKILL.md、frontmatter 元数据与发布规范ClawHub Skill 格式完全指南SKILL.md、frontmatter 元数据与发布规范 Skill技能是 ClawHub面向 OpenCla后端前端AI 技能AI 插件搜索引擎lark-cli Skill 格式校验入门从最小合法 SKILL.md 理解 Frontmatter 规范lark cli Skill 格式校验入门从最小合法 SKILL.md 理解 Frontmatter 规范 导读 本文以 lark cli 仓库官方飞书 CCLIAI 技能lark-cli Skill 体系中的 SKILL.md 格式规范从 good-skill-complex 夹具看 YAML frontmatter 校验与最佳实践lark cli Skill 体系中的 SKILL.md 格式规范从 good skill complex 夹具看 YAML frontmatter 校验与最CLIAI 技能上一篇ServerPackCreator GUI 使用教程手把手生成你的第一个 Forge 服务器包下一篇F´ 框架事件自动编码实战从 XML 事件定义到 Event Dictionary 生成与收发解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考