Skill 写得越详细越被忽略你信不信你试着把团队所有的代码审查规范、所有安全检查清单、所有性能优化套路统统塞进一个SKILL.md洋洋洒洒 2000 字。结果呢Claude 跑 review 的时候该报的 SQL 注入没报该揪的 N1 查询漏了。你以为它读懂了其实它只读了开头三段——后面 1500 字在上下文里被静默丢弃。这不是模型笨是上下文膨胀逼出来的选择性失明。Token 池子就那么大正文越长注意力越分散关键的触发条件反而被淹没。正确做法是把SKILL.md当路由器不是说明书。一、YAML 前置元数据Skill 的身份证每个 Skill 顶部那一段 YAML frontmatter才是 Claude 真正读的部分。正文反而是命中之后才加载的二等公民。---name:api-doc-generator# 唯一标识符最多 64 字符省略时用目录名description:Generate API documentation from source code. Use when the user asks to write API docs,document endpoints,or create OpenAPI specs. Supports Express,FastAPI,and Spring Boot.# 触发描述最多 1024 字符——路由匹配的真正依据argument-hint:[source directory] [output format]# 参数提示在 / 菜单中显示disable-model-invocation:true# true 时禁止自动调用只能 /skill-name 手动触发allowed-tools:-Read-Grep-Glob-Write-Bash(python:*)# 工具白名单精确控制能力边界model:haiku# 简单任务用 haiku更快更省context:fork# fork 时在隔离子智能体中执行不污染主对话---frontmatter 里没有流程详解全是身份证字段name是名字description是触发条件allowed-tools是权限边界disable-model-invocation决定显式触发还是语义匹配。Claude 在路由阶段只看这些。二、description 是 Skill 的灵魂很多人把心思花在正文description 随便糊一句帮助用户处理代码相关任务。这是把灵魂写废了——Claude 路由匹配靠的就是 description 里那几个触发词不是你正文里写的第一步、第二步。# ❌ Claude 根本不知道何时触发description:Helps with projects.# ❌ 只写了做什么没写触发场景description:Generates API documentation.# ✅ 触发词 使用场景 能力边界description:Generate API documentation from Express,FastAPI,or Spring Boot source code. Use when user asks to write API docs,document endpoints,create OpenAPI specs,or mentions Swagger. Supports route detection,request/response schema extraction,and authentication requirement marking.写 description 的三句话公式前两句说能力Claude 靠这两句判断意图中间用Use when...枚举用户可能说的关键词最后限定能力边界。上限 1024 字符别超。三、路由器思维Quick Reference 表才是正文的主角SKILL.md 的正文不是给你写说明书用的是给 Claude 当路由表用的。复合型 Skill 最该这么写## Quick Reference | Analysis Type | When to Use | Reference | |-------------------|-----------------------|-----------------------------| | Revenue Analysis | 收入、营收、销售额 | reference/revenue.md | | Cost Analysis | 成本、费用、支出 | reference/costs.md | | Profitability | 利润、毛利率、净利率 | reference/profitability.md |Claude 看到这张表就知道用户问营收加载revenue.md问成本加载costs.md。正文本身只放路由表和总流程具体公式全部分散到reference/下按需加载。顺便一提我给雷达鸭收录中国一人公司赚钱案例的 AppUni-apparkTSUniCloud华为应用市场微信小程序的搜索页写过一份代码审查 Skill把所有 ArkTS 规范铺了 1800 字在正文里结果 Claude review 时连State没初始化这种低级问题都没揪出来——后来改成路由器契约式引用正文压到 200 字反而灵了。四、契约式引用加载条件 路径 内容预期弱引用是另一个坑。你写一句See reference/revenue.md for more detailsClaude 压根不知道何时该去读。# ❌ 弱引用——Claude 不知道何时加载 See reference/revenue.md for more details. # ✅ 契约式引用——三要素齐全 ## Revenue Analysis When the user asks about revenue growth, ARPU, or revenue composition: → Load reference/revenue.md for calculation formulas and industry benchmarks.契约三要素加载条件用户问 revenue growth/ARPU/revenue composition 时、路径reference/revenue.md、内容预期计算公式和行业基准。三要素齐全模型才知道哦现在该去读这个文件了。五、渐进式披露别一次性把正文喂完把上面三步串起来就是渐进式披露的完整链路路由阶段Claude 只看 frontmatter 的description判断要不要进入这个 Skill。命中后加载SKILL.md正文但正文里只有 Quick Reference 路由表和总流程。深度执行根据契约式引用按需加载reference/*.md里的具体公式/规范。每一层只加载当下需要的上下文窗口始终干净。你写的 2000 字详细流程拆成 5 个 reference 文件分散加载比一次性塞进去强 10 倍。六、权限设计模板最小权限禁止Bash(*)Skill 的allowed-tools不是越宽越好是越精确越好。Harness 给了四套现成模板# 审计类严格只读allowed-tools:[Read,Grep,Glob]# 生成类可写不可改allowed-tools:[Read,Grep,Glob,Write]# 分析类只读 特定脚本allowed-tools:[Read,Grep,Glob,Bash(python:*)]# 执行类受控命令allowed-tools:-Read-Bash(git status:*)-Bash(git add:*)-Bash(git commit:*)-Bash(npm test:*)Bash 的精细控制语法记一下Bash(git:*)允许所有 git 子命令Bash(git log:*)只允许 logBash(./scripts/*:*)只允许 scripts 目录。Bash(*)等于授权所有 shell禁用。代码审查 Skill 给 Read/Grep/Glob 就够给 Write 就是给自己挖坑。七、$ARGUMENTS 和!command动态上下文注入任务型 Skill 经常要接参数、要感知当前环境。两个语法搞定---name:migrate-componentdescription:Migrate a component between frameworksargument-hint:[component] [from] [to]disable-model-invocation:true---Migrate the $0 component from $1 to $2. Preserve all existing behavior and tests.$ARGUMENTS是全部参数$0/$1/$2是位置参数。用户敲/migrate-component Button Vue React正文里的$0就替换成 Button。!command 则是动态上下文注入命令输出在加载时就被嵌进正文## Current State (Auto-detected) Git status: !git status --short 2/dev/null || echo Not a git repository Staged changes: !git diff --staged --stat 2/dev/null || echo Nothing stagedClaude 一进 Skill 就能看见当前 git 状态不用再跑一遍命令。提交类 Skill 用这招最爽。八、三套完整 YAML参考型 / 任务型 / 复合型参考型 Skill语义触发注入领域知识---name:code-reviewingdescription:Performs structured code reviews following team standards. Checks security vulnerabilities,performance issues,and code quality in priority order. Use when user asks to review code,do a code review,check this PR,audit this function,or provides code and asks for feedback.allowed-tools:-Read-Grep-Glob---# 代码审查流程你是一名资深代码审查员。按以下优先级执行## 第一优先级安全检查-SQL 注入、XSS、硬编码密钥、越权访问## 第二优先级性能问题-N1 查询、未加索引、循环内重复计算## 第三优先级代码质量-函数过长、命名不清、空 catch、违反 DRY任务型 Skill显式触发执行动作---name:committingdescription:Quick git commit with auto-generated or specified messageargument-hint:[optional: commit message]disable-model-invocation:trueallowed-tools:-Bash(git status:*)-Bash(git add:*)-Bash(git commit:*)-Bash(git diff:*)model:haiku---Create a git commit.If a message is provided:$ARGUMENTS-Use that as the commit messageIf no message is provided:-Analyze git diff--staged and generate a message## Current State (Auto-detected)!git status--short 2/dev/null||echo Not a git repository复合型 Skill路由器渐进式披露---name:financial-analyzingdescription:Analyze financial data,calculate financial ratios,and generate analysis reports. Use when the user asks about revenue,costs,profits,margins,ROI,financial metrics,or needs financial analysis of a company or project.allowed-tools:-Read-Grep-Glob-Bash(python:*)---# Financial Analysis Skill## Quick Reference|Analysis Type|When to Use|Reference||-------------------|---------------------|----------------------------||Revenue Analysis|收入、营收、销售额|reference/revenue.md||Cost Analysis|成本、费用、支出|reference/costs.md||Profitability|利润、毛利率、净利率|reference/profitability.md|参考型靠 description 语义命中任务型靠/skill-name显式触发复合型靠 Quick Reference 表路由到 reference 文件。三种类型对应三种触发方式别混。那么问题来了你手头那个写了 2000 字正文的 Skill是打算继续赌 Claude 心情好读完还是花半小时拆成路由器reference关于作者雷达鸭 App 独立开发者10 年软件开发经验软件设计师、人工智能应用工程师专注鸿蒙 ArkTSWeb 前端探索 AI 自动化。版权声明本文基于《Claude Code 实战Harness 工程之道》黄佳 著第 3 章内容整理与改写遵循 MIT 协议转载请注明出处。