如何从零编写高质量Golang AI技能cc-skills-golang的SKILL.md frontmatter、description触发与Token预算完全指南【免费下载链接】cc-skills-golang‍ A collection of Golang agentic skills that works项目地址: https://gitcode.com/gh_mirrors/cc/cc-skills-golangcc-skills-golang是一个面向生产级 Go 项目的 AI 智能体技能agentic skills集合包含 40 个 SKILL.md 技能文件为 Claude Code、Codex、Gemini、Cursor 等 AI 编码助手注入 Go 领域专家能力。本文是一份从零上手的完全指南讲透编写高质量Golang AI 技能的三大核心SKILL.md 的 frontmatter 规范、description 触发机制、Token 预算控制——它们决定你的技能会不会被调用、被调用后有多好用。 先克隆仓库所有例子都来自真实技能git clone https://gitcode.com/gh_mirrors/cc/cc-skills-golang 技能如何被触发三层渐进式加载理解 Token 预算之前先明白 AI 助手加载技能的三层机制详见 CLAUDE.md 的 Progressive disclosure 章节层级内容加载时机成本第 1 层元数据namedescription启动时全部技能加载每个已安装技能都付费第 2 层正文SKILL.md body技能被触发时每次会话持续占用第 3 层资源references/、scripts/、assets/仅当正文指向它们时按需、一次性 关键认知description 是模型决定是否加载技能前读到的唯一内容——选择失败时文件里的其他一切都不重要。所以 description 写作质量直接决定技能的生死。 技能目录结构一个技能就是一个文件夹skills/skill-name/ SKILL.md # 必需frontmatter 元数据 正文指令 references/ # 可选深度文档按需加载 scripts/ # 可选可执行脚本只有输出进上下文 assets/ # 可选模板、配置文件 evals/evals.json # 评估用例以真实的 skills/golang-context/SKILL.md 为例正文只保留核心规则深入内容由 references/cancellation.md、references/http-services.md 承载。⚠️ 两条硬约束references 只允许一层深——嵌套链接会被部分读取后静默截断最深处的内容永远到不了模型非 Markdown 内容配置、脚本、模板放assets/用相对链接引用不要内嵌进 SKILL.md。 frontmatter 完整字段指南每个 SKILL.md 以 YAML frontmatter 开头。完整字段表含项目必选字段字段必选约束要点name✅ 规范必选1-64 字符小写字母/数字/连字符必须与父目录名一致description✅ 规范必选1-1024 字符主要触发机制要具体且主动一点license✅ 项目必选本项目统一MITcompatibility✅ 项目必选1-500 字符用能力描述而非工具名写 Requires internet access 而不是某个工具名metadata✅ 项目必选必须含author、versionsemver、openclaw对象user-invocable✅ 项目必选true可作斜杠命令调用false默认为自动触发的上下文技能allowed-tools✅ 项目必选空格分隔的预批准工具清单paths可选文件 glob 作用域如**/*.go目前仅 Cursor 识别真实示例节选自 skills/golang-security/SKILL.md--- name: golang-security description: Security best practices and vulnerability prevention for Golang — ... Apply when writing, reviewing, or auditing Go code for security... user-invocable: true license: MIT compatibility: Designed for Claude Code, Codex or similar harness, and for projects using Golang. metadata: author: samber version: 1.2.2 openclaw: emoji: requires: bins: [go, govulncheck] install: - kind: go package: golang.org/x/vuln/cmd/govulnchecklatest bins: [govulncheck] allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent WebFetch WebSearch Bash(govulncheck:*) paths: [**/*.go] ---⚠️ 三种静默失败模式规范定义了 6 个标准字段写错的 frontmatter 会让技能无报错地消失添加规范外的字段→ 严格校验器直接拒绝这也是本项目禁用skills-ref校验的原因见 CLAUDE.md顶层写version:→ 打包失败必须挪到metadata.versiondescription 含冒号空格或[ ] 开头却不加引号→ YAML 解析失败技能悄悄掉出列表。所以 description 要整体加引号长描述用-块标量。 description 触发机制8 条写作法则这是全文最重要的部分。CLAUDE.md 的 Description quality 章节总结了 8 条法则先写做什么再写何时用顺序不能反用第三人称——❌ I can help you…、❌ You can use this to…人称混用会削弱发现率点出用户真实会输入的具体名词文件扩展名、工具名、import 路径、目录路径、领域术语在技能自己的关注范围内主动出击——欠触发under-triggering是文档确认的默认故障Use whenever the user mentions X, Y, or Z, even if they dont say X explicitly.与兄弟技能划清边界——两个技能重叠时说明各自不做什么把关键用例前置——加载列表过长时 description 会被截断甚至丢弃绝不概述工作流——描述里列有序步骤模型会照 description 执行而跳过正文加否定条款点名近似命中的兄弟技能Do NOT use for X — use sibling instead.对比感受一下摘自 CLAUDE.md# ✗ 坏——无触发上下文永远不被触发 description: Implements X in Golang using library/foo # ✓ 好——具体触发场景匹配真实用户行为 description: Implements X in Golang using library/foo — feature A, feature B. Apply when using or adopting library/foo, or when the codebase imports github.com/library/foo. 本项目还有一条铁律每条 description 必须包含 Golang 一词确保技能只在 Go 项目触发不误伤其他语言。 Token 预算速查表CLAUDE.md 的 Token budgets 章节给出了精确数字这是简洁的量化标准预算单位说明~100 tokens每条 description启动成本每个技能都付≤ 1,000 字符每条 description硬上限≤ 3 句每个纯正文段落表格/列表/清单不受限 2,500 tokens每个 SKILL.md本项目实际目标值规范上限 5,000 500 行每个 SKILL.md目标是 250 行以内官方中位数 147 行~10,000 tokens单次加载总和典型会话同时加载 2-4 个技能 两条实战推论承重规则放前面——自动压缩只保留技能头部边缘情况和例子放后面宁可少装技能别只压缩单个技能——启动列表本身也是共享预算超过约 20-50 个已安装技能后所有技能的触发质量都会下降。可参考 README.md 的技能表每个技能都标注了实测的 Description / SKILL.md / Directory 三项 Token 数。✍️ 正文写作指令头 教推理而非教规则顶部指令头body 开头、首个标题之前全部可选。skills/golang-security/SKILL.md 展示了全套用法**Persona:**1-2 句角色设定如 You are a senior Go security engineer…纯流程类技能可跳过**Thinking mode:**深度分析类技能性能剖析、安全审计、根因分析加这句引导充分推理**Orchestration mode:**有并行子代理扇出模式的技能加这句**Modes:**多模式技能Review / Audit / Coding列出每种模式的执行策略**Dependencies:**列出go之外需要安装的二进制及安装命令。正文风格 4 条心法祈使句、动词开头Run、Validate、Reject教为什么而不只教做什么——用破折号把理由挂在规则同一句里别单开一句解释会突破 3 句上限一个默认值 一个逃生条件永远别列五个候选库让模型纠结工具名只进allowed-tools正文只写能力写 web search 而不是某个具体工具名——这是跨 Claude Code / Codex / Cursor / Gemini 可移植的关键。️ allowed-tools默认集 按需扩展每个技能必须声明allowed-tools。从默认集出发Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent按需添加技能专属工具基准/性能技能加Bash(benchstat:*)调试技能加Bash(dlv:*)gRPC 技能加Bash(protoc:*)安全/性能/故障排查类研究性技能加WebSearch需要向用户澄清意图的技能加AskUserQuestion。 记住安全原则allowed-tools是免询问清单不是沙箱最小授权绝不用Bash(*)。 用 evals 证明技能价值技能不是写完就算——本项目要求每个技能带对抗性评估adversarial evals存放在skills/name/evals/evals.json如 skills/golang-samber-do/evals/evals.json。设计要点只测技能的独特价值——如果模型有技能和没技能都能答对这条评估毫无用处设计陷阱而非显式错误指令——任务看起来正常但自然实现恰好是错的如为 web handler 实现共享计数器诱导竞态条件规模标准约每 1,000 tokens 技能内容配 10 条断言最少 50 条。全仓库 41 个技能共 3,439 条断言的总体结果见 EVALUATIONS.md带技能 97% vs 不带技能 57%提升 40 个百分点——这就是精心编写 description 与正文的量化回报。✅ 修改技能后的检查清单按 CLAUDE.md 的 Workflows 章节每次改动后执行提升metadata.version并同步三个插件清单文件的版本号用 prettier 格式化 markdownlint 检查格式化会改变 Token 数须先做再测量用tiktoken-cli测量 description / SKILL.md / 目录三级 Token 数更新 README.md 统计表检查兄弟技能是否需要加→ See交叉引用每个概念只归一个技能所有跨技能一律用owner/reposkill全限定标识符引用且加反引号——裸引用会强制加载整个技能、烧掉预算跑评估循环带/不带技能各跑一遍LLM 评分结果追加到 EVALUATIONS.md。如果你的团队希望让技能路由始终生效还可以参考 rules/golang-always.mdc——它把技能路由表内嵌为always规则确保每个 Go 任务在开始时同时加载主技能与辅助技能。 总结编写高质量 Golang AI 技能的心法其实就三句话frontmatter 让技能能被找到字段正确 引号护体description 让技能在对的时机被触发what when 具体名词 兄弟边界Token 预算让技能加载得起2,500 tokens 正文 references 下沉 承重规则前置。照此执行并用对抗性评估验证你的技能就能像 cc-skills-golang 的 40 个技能一样稳定产出可衡量的能力提升。【免费下载链接】cc-skills-golang‍ A collection of Golang agentic skills that works项目地址: https://gitcode.com/gh_mirrors/cc/cc-skills-golang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考