Claude Code Skills：不仅是 Markdown，更是工程化排查逻辑
“Skills 不就是写了步骤的 Markdown 吗？”
这句话往往暴露了对 Claude Code 理解仅停留在表面。在官方定义中，Skills 虽以 Markdown 形式存在（包含 YAML frontmatter 和指令），但其核心价值在于通过description、paths、when_to_use等元数据，控制 AI 在特定上下文中的自动加载与行为约束。
许多开发者将SKILL.md误写为给人看的 README，而非给 AI 执行的运行指令。有效的 Skill 必须具备明确的边界、触发条件、输入约定及标准化产出格式。
从“泛泛而谈”到“精准执行”
低质量的 Skill 通常缺乏场景约束，例如仅写“帮我检查 Java 代码”。这会导致 AI 输出笼统的可读性或安全性建议，缺乏实际指导意义。
高质量的 Skill 应模拟资深工程师的排查思路。以 Java PR 审查为例，应明确指定触发场景（如接口改动、并发代码），并固化检查顺序：
---
name: java-pr-review
description: 当用户要求检查 Java PR、接口改动、并发代码、数据库访问代码时使用。重点检查线上风险，不做教学式点评。
paths:
- "src/main/java/**/*.java"
- "pom.xml"
disable-model-invocation: false
---
你是负责 Java 后端上线前检查的人。
检查顺序固定：
1. 先看接口入口和事务边界
2. 再看数据库访问，有没有 N+1、全表扫、循环查库
3. 再看线程池、异步任务、锁
4. 最后看异常兜底和日志
输出只保留三类：
- 必须改
- 建议改
- 我没看懂，需要补上下文
不要泛泛评价“代码可维护性不错”。
差异在于：description是 AI 判断是否加载的入口，而正文则是固化的专家经验。同样的逻辑适用于日志排查，应规定先查 ERROR、再定位耗时 Span、最后分析业务逻辑的顺序，而非简单要求“分析问题”。
Skills 的工程化加载机制
Skills 的本质是在合适上下文中被自动加载的能力包，而非手动复制的提示词。其工作机制类似于一个带元数据的路由器：
- 触发判断：基于用户输入关键词与文件路径匹配（
paths）。 - 资源引用：支持引用同目录下的脚本、参考文档（如
references/、scripts/），避免主文件过于臃肿。 - 按需加载：仅在满足条件时读取详细规范，提升响应速度并减少上下文干扰。
例如，数据库规范审查可将通用规则写在SKILL.md，而复杂的 SQL 风险清单存放在references/mysql-risk.md中，仅在检测到复杂 SQL 时调用。
关键陷阱：会话状态持久化
需注意，Skill 被调用后，其内容会进入当前会话上下文并在后续对话中持续生效。Claude Code 在同一个会话的后续回合中不会重新读取技能文件。
这意味着修改SKILL.md后，若未重新 invoke 或开启新会话，旧规则仍将生效。因此，Skill 中的约束应设计为“站立指令”（持续生效的规则），而非一次性步骤。
总结
Claude Code 的 Skills 功能并非简单的步骤罗列，而是将团队的排查顺序、上线禁忌、日志格式及脚本入口等隐性知识显性化、工具化。真正的门槛在于能否将这些工程经验转化为具备触发边界和行为约束的自动化能力，从而让 AI 成为符合团队规范的可靠协作者。