CLIAI 技能【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址https://gitcode.com/gh_mirrors/cli414/cli点击查看免费下载本篇技术指南以 lark-cli 开源仓库中的scripts/skill-format-check校验工具及其负向测试夹具bad-skill-unclosed-frontmatter为核心系统讲解SKILL.md文件的 YAML frontmatter 格式规范、校验器的解析原理、完整测试矩阵与运行方式帮助开发者为 Lark 飞书 CLI 编写可通过 CI 校验的 Agent Skill。背景Lark CLI 的 Agent Skills 体系lark-cli由 larksuite 团队维护的官方飞书 CLI不仅提供 200 条覆盖 Messenger、Docs、Base、Sheets、Calendar、Mail、Tasks、Meetings 等核心业务域的指令还内置了 20 个 AI Agent Skills。这些技能以 Markdown 形式存放在仓库的 skills/ 目录下如lark-approval、lark-im、lark-calendar等每个技能目录中都必须包含一个名为SKILL.md的描述文件。为保证海量技能文件的质量与可解析性仓库在 scripts/skill-format-check/ 目录中提供了一套基于 Node.js 的格式校验工具专门验证SKILL.md是否符合标准模板模板见 skill-template/skill-template.md的 frontmatter 约定并在 GitHub Actions 的 PR 流程中自动执行。校验规则frontmatter 的三个核心字段根据 scripts/skill-format-check/README.md 与 scripts/skill-format-check/index.js校验器对每个技能的SKILL.md执行如下规则字段要求失败等级name必需❌ 错误build 失败description必需❌ 错误build 失败metadata建议提供⚠️ 警告不阻塞构建其中lark-shared技能被显式排除在校验范围之外index.js中if (skill lark-shared)直接跳过。参考 skill-template/skill-template.md 的标准模板一个合规的 frontmatter 形如--- name: lark-{{project}} version: {{meta_version}} description: {{meta_description}} metadata: requires: bins: [lark-cli] cliHelp: lark-cli {{service}} --help ---模板还展示了description可以使用多行折叠语法、metadata可以携带bins、cliHelp等扩展信息见 tests/good-skill-complex/SKILL.md。解析原理三层递进的 frontmatter 校验逻辑scripts/skill-format-check/index.js 的校验分为三层递进检查必须以---\n开头文件内容已统一换行符若不以---\n开头直接报错SKILL.md must start with YAML frontmatter (---)。frontmatter 必须闭合通过正则^---\n([\s\S]*?)\n---(?:\n|$)匹配开闭边界。若匹配失败报错SKILL.md has unclosed or invalid YAML frontmatter。字段完整性对匹配到的 frontmatter 内容分别用^name:、^description:、^metadata:多行模式检测三个字段是否存在其中前两者缺失即失败metadata缺失仅输出警告。从源码结构看该校验器并未真正调用 YAML 解析库而是以正则文本匹配作为快速门禁保证 frontmatter 的结构完整性字段语义的正确性仍依赖模板约定与人工 review 兜底。核心用例解剖未闭合的 frontmatter本次分析的关联文档 scripts/skill-format-check/tests/bad-skill-unclosed-frontmatter/SKILL.md 是校验器的负向测试夹具fixture全文如下--- name: bad-skill-unclosed version: 1.0.0 description: This skill has an unclosed frontmatter block. metadata: {} # Unclosed Frontmatter Skill This frontmatter does not have a closing --- block.逐行分析可以发现它的缺陷恰好击中校验逻辑的第二层第 1 行以---开始满足必须以 frontmatter 开头的检查name、description、metadata三个字段在内容上其实都存在第一、三层检查从文本上难以发现异常但整个文件始终没有出现第二组闭合的---分隔行因此正则^---\n([\s\S]*?)\n---(?:\n|$)无法找到匹配触发SKILL.md has unclosed or invalid YAML frontmatter错误。这说明该校验器的关键防线在于开闭边界完整性即使字段齐全只要缺少闭合分隔符整个 frontmatter 与正文的边界就无法确定YAML 解析器会将其后的 Markdown 正文误吞进元数据导致name、description等字段解析失败。因此这类文件必须被拦截。测试矩阵三正三负六个夹具scripts/skill-format-check/test.sh 通过tests/目录下的六个夹具验证校验器行为夹具目录类型校验结果特点good-skill正向✅ 通过标准格式含metadata.requires.binsgood-skill-minimal正向✅ 通过仅含必需字段的极简格式good-skill-complex正向✅ 通过多行描述 复杂 metadatabad-skill负向❌ 拒绝缺少name、descriptionbad-skill-no-frontmatter负向❌ 拒绝完全没有 frontmatterbad-skill-unclosed-frontmatter负向❌ 拒绝frontmatter 未闭合本文核心用例test.sh中的run_positive_test/run_negative_test分别断言正向夹具运行node index.js 目录必须返回退出码 0负向夹具必须返回非 0 退出码任一方向不符合预期即测试失败。这从测试层面锁定了校验器的行为契约。运行方式1. 运行完整校验在仓库根目录执行node scripts/skill-format-check/index.js默认扫描scripts/skill-format-check/../../skills即仓库根目录下的 skills/打印每个技能的检查结果存在错误时以退出码 1 结束。2. 指定自定义技能目录校验器支持将第一个命令行参数作为目标目录相对process.cwd()解析node scripts/skill-format-check/index.js ./path/to/my/skills3. 运行测试套件./scripts/skill-format-check/test.sh脚本会依次将三个正向夹具复制进临时目录断言通过、三个负向夹具断言拒绝全部通过后输出 All tests passed successfully!。实践建议编写可通过校验的 SKILL.md结合校验器规则、模板与测试夹具编写新技能时应注意文件必须严格以---\n开头并以第二个---行闭合且闭合行后应有换行这是最容易被忽略也最致命的错误必填name与description缺失会导致 CI 失败metadata缺失仅告警但仍建议按模板补全requires.bins与cliHelp不要在 frontmatter 内使用与模板相悖的字段缩进避免正则多行匹配无法命中字段行提交前在本地运行node scripts/skill-format-check/index.js或完整跑一遍test.sh确保与 CI 行为一致后再发起 PR。通过理解校验器的三层解析逻辑与负向用例的设计意图开发者既能快速定位自己SKILL.md的格式问题也能在需要时向tests/目录新增夹具持续加固这套技能质量门禁。赞分享CLIAI 技能【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址https://gitcode.com/gh_mirrors/cli414/cli点击查看免费下载相关推荐lark-cli SKILL.md 规范解析AI Agent Skill 文件格式与质量门禁校验机制lark cli SKILL.md 规范解析AI Agent Skill 文件格式与质量门禁校验机制 本文围绕 lark cli 仓库中 internal/qCLIAI 技能Rust E0030 解析为什么 1000 .. 5 这样的范围模式会被 rustc 拒绝Rust E0030 解析为什么 1000 .. 5 这样的范围模式会被 rustc 拒绝 本文讲解 Rust 编译错误 E0030 lower bou编程语言编译器语言运行时标准库Joplin YAML Frontmatter 导入以短横线开头的未加引号标题为何不会被误判为列表项Joplin YAML Frontmatter 导入以短横线开头的未加引号标题为何不会被误判为列表项 导读 本文以 Joplin 仓库中的测试样例 title知识管理跨平台插件系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
