发布时间:2026/9/3 15:34:08
第12篇-Frontmatter必填字段详解-name-description-version 【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。这些字段虽然不强制但对技能的组织、搜索和跨平台行为有重要影响。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。

相关新闻

2026/9/3 15:34:08

婚恋平台技术架构解析:从PHP+MySQL到二次开发与安全部署

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/3 15:29:01

2026年7月张家口市新房价格深度分析报告

一、报告概述本报告基于2026年7月张家口市新房实际成交案例,结合区域分布、楼盘类型、价格区间等多维度数据,对当前张家口市新房市场进行深度分析。报告旨在为购房者、投资者及行业研究者提供真实、客观的市场参考。数据说明:本报告所引用成交…

2026/9/3 15:49:11

基于TensorFlow.js的野生动物边缘AI识别系统:从模型优化到工程部署

简介:这是一套面向生态学研究者与野外保护工作者的轻量化野生动物识别系统,解决传统人工巡护效率低、覆盖窄、物种识别依赖经验等痛点,特别适用于森林、湿地等难以持续驻守的监测场景。资源包共110个文件,含38个核心JavaScript模型…

2026/9/3 15:49:11

Plasticity瓶体建模全流程:NURBS曲面、圆角与抽壳实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/3 15:49:11

ChatGPT进阶指南:从问答机到工作流引擎的三大核心场景

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/3 15:49:11

拇指相机充电检测,MH248 与 MH251 全极霍尔该怎么选

随着Vlog、户外运动、短视频直播的兴起,拇指相机因其超小体积、磁吸易用性和第一人称视角的独特优势,迅速成为影像市场的新宠。无论是Insta360 GO系列、大疆DJI Action 2,还是其他各类拇指相机,都离不开一个核心配件——充电仓。不…

2026/9/3 15:49:11

微信小程序实战开发教程

开发前的必修课 在写代码前,需要完成账号注册和工具安装,这是进入微信生态的第一步。 注册小程序账号:访问微信公众平台,使用未被注册过的邮箱注册“小程序”类型的账号。注册后会拿到唯一的 AppID,它就像小程序的身份…

2026/9/3 15:44:11

音游高难度谱面攻关:从谱面拆解到肌肉记忆的系统方法论

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/9/1 16:02:17

vSound小提琴数字处理器实操指南:从接线到演出的完整配置

电小提琴或者原声小提琴插电演出,第一个绕不开的坎就是声音难听。原声琴的共鸣和空气感一旦进了拾音器,出来的往往是一坨干瘪、发尖、带着奇怪塑料味的信号。我当初第一次把琴接上乐队调音台,直接被主唱吐槽"你这声音像在锯钢丝"。…

2026/9/3 14:29:47

传感器接口IC如何攻克生物化学传感的微弱信号难题?

1. 从电极到比特流:为什么生物化学传感必须依赖专用接口IC 做生物化学传感的人都有过类似的经历:明明传感器本身性能很好,信号输出却一塌糊涂——噪声大、漂移明显、重复性差,怎么调都达不到预期。很多时候问题并不在传感器&#…

2026/9/3 14:30:35

STM32F411CEU6多通道ADC采集:扫描模式+DMA实现详解

1. 多通道 ADC 的用武之地把“Multichannel ADC”和“STM32F411CEU6”这两个关键字放在一起,其实就是嵌入式开发里最常遇到的一类需求:用一块不算贵的 MCU,同时采集多路模拟信号。STM32F411CEU6 是 48 引脚的 Cortex-M4F 主控,主频…

2026/9/3 0:02:06

零基础装 OpenClaw 小龙虾 AI:Windows 一键部署教程与避坑要点

Windows 部署 OpenClaw 完整教程|本地 AI 智能体 5 分钟落地,环境配置一次搞定 版本说明:Windows 3.1.0 / Mac 2.7.9 写在前面 近两年开源 AI 领域有一款被称作「数字员工」的工具持续走热,它就是 OpenClaw,圈内人更习…

2026/9/3 0:02:06

Hermes Agent 本地部署新方案:Windows 整合包减少依赖报错

Windows 本地部署 Hermes 太麻烦?这版一键包 5 分钟快速跑通 很多人想体验 Hermes Agent,但真正开始部署时,往往会卡在环境配置这一步。 需要安装各类依赖、调试运行环境、处理路径问题,还容易遇到命令行报错、系统拦截、文件缺…

2026/9/3 0:02:06

实测 OpenClaw 一键包,5 分钟完成本地自动化环境搭建

OpenClaw 本地 AI 自动化工具部署指南|使用一键包规避环境配置难题 痛点:部署 AI 自动化工具常常要处理 Python、Node.js 各类依赖,版本冲突、环境配置耗费大量时间,OpenClaw 提供一键安装包,降低部署门槛。 适配系统&…

2026/9/2 1:15:22

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/2 1:15:22

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/2 1:15:20

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…