【Skills 系统从入门到精通】第 12 篇Frontmatter 必填字段详解——name、description、version本篇你将学到name 字段的命名规范、约束和最佳实践description 字段的写作公式和 57 字符截断规则version 字段的语义化版本号规范每个字段的常见错误和修复方法读完本篇你将能为技能写出规范的身份证信息确保技能能被正确发现和加载。一、name 字段1.1 规范与约束name是技能的唯一标识符贯穿技能的整个生命周期——斜杠命令、技能索引、Bundle 引用、Hub 安装都使用这个值。name 字段技能唯一标识斜杠命令斜杠加技能名调用Level 0 技能索引Bundle 引用skills 列表中的名称Hub 安装标识硬性约束约束项规则示例字符集小写字母、数字、连字符、下划线log-analysis✅首字符必须是小写字母Log-analysis❌长度≤ 64 字符—全局唯一同一系统中不能有两个同 name 的技能—1.2 命名最佳实践实践一动词对象 或 场景描述✅ code-review 动词对象审查代码 ✅ deploy-k8s 动词对象部署 K8s ✅ log-analysis 场景日志分析 ✅ gif-search 动词对象搜索 GIF ❌ skill-1 无意义 ❌ my-tool 太泛 ❌ very-long-name-that-goes-on-and-on 太长实践二全拼不缩写✅ github-code-review 全拼 ✅ test-driven-development ❌ gh-cd-rv 过度缩写无法理解 ❌ tdd-wf 只有自己知道是什么实践三连字符分隔单词✅ systematic-debugging ❌ systematic_debugging 下划线也可以但不推荐 ❌ systematicdebugging 无法阅读1.3 常见错误# 错误1大写字母name:Log-Analysis → 应为 log-analysis# 错误2包含空格name:log analysis → 应为 log-analysis# 错误3以数字开头name:3scale-api → 应为 three-scale-api 或 scale-api二、description 字段2.1 规范与约束约束项规则最大长度1,024 字符推荐长度80-200 字符推荐句式以 “Use when…” 开头2.2 写作公式一个高质量的 description 遵循以下公式Use when [触发场景]. [覆盖的具体能力列表].公式拆解Use when标准开头告诉 Agent “什么情况下用我”[触发场景]简明描述适用场景[能力列表]列出技能包含的关键能力同时是语义匹配的关键词来源示例拆解Use when analyzing server logs. Error extraction, pattern matching, root cause identification.触发场景analyzing server logs能力列表Error extraction、pattern matching、root cause identification当用户说帮我分析日志里的错误模式时这段描述中的关键词analyzing、logs、Error、pattern matching都能被匹配到。Use when 标准开头description触发场景什么情况下用我能力列表语义匹配的关键词来源Agent 自然语言匹配关键词命中即触发加载2.3 57 字符截断规则这是一个容易被忽略但极其重要的细节。在系统提示中技能索引以紧凑格式呈现。description 会被截断到约 57 个字符加省略号。这意味着完整 description: Use when analyzing server logs. Error extraction, pattern matching, root cause. 截断后57字符: Use when analyzing server logs. Error extraction, pattern...Agent 在做自然语言匹配时首先看到的是截断版本。如果最重要的关键词在 57 字符之后可能被忽略。在前 57 字符内在 57 字符之后完整 description最长 1024 字符系统提示索引截断到约 57 字符核心关键词位置命中 匹配成功被省略号截断可能漏触发写作策略关键词前置写作策略核心关键词前置✅ Use when reviewing code. Security scan, quality gates, auto-fix. 前57字符Use when reviewing code. Security scan, quality gates, → reviewing code、Security scan 等核心词都在前57字符内 ❌ This skill provides comprehensive code review capabilities including security analysis and quality assurance checks. 前57字符This skill provides comprehensive code review capabilit → 关键词被铺垫语淹没security 在很后面2.4 好描述 vs 差描述对比差的 description好的 description问题分析Log tool.Use when analyzing server logs. Error extraction, pattern matching, root cause.太短缺少触发信号A comprehensive solution for all your deployment needs.Use when deploying to Kubernetes. Rolling updates, health checks, rollback.虚词太多无具体关键词Use when: doing things with k8sUse when deploying to Kubernetes. Pod management, service mesh, ingress config.冒号问题 太模糊Kubernetes deployment, service management, ingress configuration, pod scaling, volume management, secret rotation, certificate management, monitoring setup.Use when deploying to Kubernetes. Rolling updates, health checks, rollback.太长关键词被稀释2.5 多语言考量description 通常用英文编写因为大部分 LLM 对英文语义匹配更精准。但如果你的主要用户群体使用中文也可以双语description:Use when analyzing server logs. 错误提取, 模式匹配, 根因分析.不过要注意 1024 字符的限制——双语会消耗更多字符额度。三、version 字段3.1 语义化版本号version 字段使用语义化版本号Semantic Versioning格式为主版本.次版本.修订号例如1.2.33.2 版本号规则版本变化何时使用示例修订号x.x.N1修复错误、小幅改进、补充陷阱说明1.0.0 → 1.0.1次版本x.N1.0新增功能章节、增加新步骤、新增辅助文件1.0.1 → 1.1.0主版本N1.0.0核心流程变更、不兼容的修改、完全重写1.1.0 → 2.0.0修复错误 小幅改进补充陷阱说明新增功能章节新步骤 新辅助文件核心流程变更不兼容修改 完全重写准备发布技能修改修改类型修订号加一1.0.0 到 1.0.1次版本加一1.0.1 到 1.1.0主版本加一1.1.0 到 2.0.03.3 初始版本新创建的技能使用1.0.0作为初始版本version:1.0.03.4 版本号的价值虽然 version 字段不是必填的验证器不会因为缺少 version 而拒绝但它有以下价值变更追踪知道技能的演进历史Hub 更新检测Skills Hub 通过版本号判断是否有上游更新团队协作多人维护同一技能时版本号帮助协调修改专业度包含 version 的技能看起来更规范四、完整 Frontmatter 示例集4.1 最简 Frontmatter只有两个必填字段---name:hello-worlddescription:Use when greeting users. Simple hello world demonstration.---4.2 标准 Frontmatter包含推荐字段---name:code-reviewdescription:Use when reviewing code. Security scan,quality gates,auto-fix suggestions.version:1.0.0---4.3 完整 Frontmatter包含所有推荐和可选字段---name:deploy-kubernetesdescription:Use when deploying to Kubernetes. Rolling updates,health checks,rollback procedures,ingress configuration.version:2.1.0author:DevOps Teamlicense:MITplatforms:[linux,macos]metadata:hermes:tags:[devops,kubernetes,deployment]category:devopsrelated_skills:[github-code-review,systematic-debugging]---本篇小结字段必填约束核心要点name✅小写连字符≤64字符全局唯一动词对象命名全拼不缩写description✅≤1024字符推荐80-200“Use when…” 句式核心关键词前置57字符version推荐语义化版本号修复→修订号新增→次版本核心变更→主版本三个必填字段name 技能身份证小写加连字符64 字符以内动词加对象命名全拼不缩写description 触发器Use when 句式核心词前置 57 字符80 到 200 字符最佳version 演进史语义化版本号修复升修订号新增升次版本重写升主版本下篇预告下一篇继续 Frontmatter 的可选字段——platforms、tags、category、related_skills。这些字段虽然不强制但对技能的组织、搜索和跨平台行为有重要影响。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。