Claude Skills 为什么总是不触发在 Claude Code 的日常 workflow 里你很可能已经踩过这个坑花了半天写好一个 SKILL.md放进~/.claude/skills/description 也写了结果一连串 prompt 下去Claude 完全视而不见。你只好手动/skill-name硬召输出还时好时坏格式乱飞。我起初以为这是 prompt 工程不够精细的问题后来把 Anthropic 官方技能仓库和社区高频使用的几十个技能全部拆开才发现根源远比“描述不够长”深刻大多数自定义技能在架构层面就输在了“6个模式”上。缺少任意一个技能要么不被加载要么加载了也产出垃圾。这不是 Claude 不聪明而是技能本质上是一份机器可读的微型 Agent 协议。它必须同时满足 Claude 的决策机制description 扫描、执行纪律directive output format和上下文安全read first out-of-scope。掌握这 6 个模式你就不再是“写 prompt 的人”而是真正拥有第二大脑的开发者——技能会自动在正确时机介入把你的生产力拉到另一个数量级。技能的本质一份被 Claude 自动加载的微协议30 秒快速回顾技能就是一个带 YAML frontmatter 的 Markdown 文件放在~/.claude/skills/skill-name/SKILL.md。Claude 在每次响应前会扫描所有 skills 的 description根据上下文自动匹配加载或者你用/skill-name手动触发。架构本身极简真正决定生死的是 SKILL.md 里面的内容。技能就像你给外包团队发的一份“工作手册”。手册写得模糊外包就会乱来手册把触发条件、执行步骤、交付格式、边界全部写死外包才能像机器人一样稳定输出。Claude 也是同一个逻辑——它不是读心术大师它只执行你写进协议的规则。就像操作系统里的设备驱动。驱动只声明“当 USB 设备插入时执行这套初始化流程”而不是泛泛说“我是个 USB 驱动”。前者能被内核自动加载后者只能手动安装还容易蓝屏。模式一Description 必须说清楚“什么时候触发”而非“它能干什么”这是所有模式里权重最高的一条。Claude 在决定加载哪个技能时只看 description 的前 250 个字符左右。光写“what”不够必须把 use-case、trigger keywords、场景全部前置。坏描述几乎不会被自动触发description:生成 commit message好描述触发率提升 3-5 倍description:用户请求 git commit、写 commit message、生成 Conventional Commit 时自动分析 git status 和 git diff输出符合规范的 commit message前者是“功能描述”后者是“触发协议”。社区实测描述越前置具体用例自动命中率越高。模式二指令必须是命令式而非对话式技能是执行指令不是聊天。使用祈使句、编号步骤、明确动词Claude 的遵循率会大幅上升。对话式弱请你帮我生成一个 commit message 好吗命令式强1. 先执行 git status 和 git diff 2. 分析变更内容 3. 按照 Conventional Commit 规范生成 messageAnthropic 官方所有高频技能frontend-design、code-review 等全部采用这种写法。模式三必须明确指定输出格式这是自定义技能最容易翻车的点。没有格式约束Claude 每次都会即兴发挥结果不可复用。无格式→ 输出时而一行、时而多段、时而带前缀有格式输出必须严格遵循以下格式 COMMIT_TITLE: 50字符以内摘要 TYPE: feat|fix|docs|... SCOPE: 可选 BODY: 详细说明模式四永远加上“read first”步骤顶级技能绝不假设 Claude 已经了解你的项目。它必须先主动读取上下文。经典示例来自 awesome-claude-skills 的 /test 技能1. 先执行 git ls-files | grep test 读取现有测试文件 2. 阅读当前变更文件的内容 3. 再生成对应的测试用例这一步直接把“泛化代码”变成“适配你项目”的代码。模式五明确定义“不做什么”out-of-scope反直觉但极其有效。把边界说清楚Claude 就不会硬着头皮乱试。Anthropic 官方 PDF 技能示例本技能不处理 - 图片提取 - 表格转 Markdown - 复杂布局重建 遇到以上情况直接回复“超出范围请使用其他技能”70% 的高质量技能都有这一段低质量技能几乎没有。模式六单文件控制在 500 行以内必要时拆分技能加载时会整个塞进上下文。2000 行技能等于白白吃掉 5000 tokens还容易让 Claude 后半段失焦。解决办法是“渐进式披露”主 SKILL.md 里只放核心逻辑用include: other.md引用辅助文件Claude 只在需要时加载。一个真实可直接复制的 /commit 技能完整重构版下面是我根据社区高频使用的 /commit 技能重构后的生产版已增加中文关键注释长度控制在 50 行以内--- name: commit description: 用户请求 git commit、生成 commit message 时自动分析 git status 和 git diff输出 Conventional Commit 格式的消息。仅用于 git 仓库环境。 tools: [git_status, git_diff] --- # /commit 技能 ## 工作原则 1. 永远先执行 read first 2. 使用命令式指令 3. 输出格式固定 4. 超出范围直接拒绝 ## 执行步骤 1. 运行 git status 和 git diff --cached 获取变更信息 2. 分析变更类型和影响范围 3. 按照 Conventional Commit 规范生成消息 4. 输出必须严格符合以下格式 ## 输出格式 COMMIT_TITLE: 50字符以内摘要 TYPE: feat|fix|docs|style|refactor|perf|test|chore SCOPE: 可选模块名 BODY: 详细说明每行不超过72字符 ## Out of scope - 不处理非 git 仓库环境 - 不生成 breaking change 说明需手动补充这个技能在任意项目、任意语言下都能稳定工作。坏技能 vs 好技能的真实对比矩阵维度坏技能最常见的失败模式好技能6模式全覆盖核心收益Description只写 what“生成 commit”前置 when trigger keywords自动触发率提升 3-5 倍指令风格对话式、礼貌请求命令式 编号步骤执行一致性大幅提高输出格式完全不指定明确结构化模板结果可复用、可解析上下文读取直接假设已知项目强制 read first 步骤代码适配项目而非泛化边界定义完全缺失明确列出 out-of-scope减少失败输出和错误路由文件长度1000 行全塞一个文件主文件 500 行 按需 includeToken 效率高、不失焦实际效果很少被自动调用、输出不稳定系统自动介入、输出可预测成为真正的第二大脑我起初以为写技能就是“把需求写清楚就行”后来把上百个技能拆解后才发现真正拉开差距的是把技能当成微型 Agent 协议来设计而不是当成 prompt 模板。掌握这 6 个模式后你的 skills 文件夹会从“一堆实验品”变成一套能自我进化的生产力系统。6 个月后你会发现 Claude 越来越“懂你”——因为你给它的协议越来越精准。现在轮到你了你在写 Claude Skills 时最常踩的坑是 description 不触发、还是输出格式乱飞欢迎在评论区贴出你最头疼的技能案例或者直接甩 SKILL.md 片段我们一起用这 6 个模式把它彻底重构让它真正成为你的系统级武器。我是紫微AI在做一个「人格操作系统ZPF」。后面会持续分享AI Agent和系统实验。感兴趣可以关注我们下期见。