Claude Code Skills 完全指南：SKILL.md 怎么写、放哪、怎么防坑

这篇指南系统讲清了 Claude Code Skills 的机制：SKILL.md 的结构、渐进式加载如何省上下文、各级目录的优先级，以及和 CLAUDE.md、hooks、MCP 的分工。文中还引用了 2026 年 2 月对 3,984 个 skill 的安全审计数据，提醒 skill 本质是指令而非防线。

Skill 是什么：一个带 SKILL.md 的文件夹

• 每个 skill 是一个文件夹，核心是带 YAML frontmatter 的 SKILL.md，可附带脚本、模板和参考文件
• Claude 平时只读 description，任务匹配或你手动输入 /skill-name 时才加载正文，不会撑爆上下文
• 这是开放标准：Anthropic 2025 年 10 月提出 Agent Skills，同年 12 月发布开放规范，Claude Code 在其上加了扩展字段
• 适合场景：反复粘贴同一套流程、CLAUDE.md 里某段已长成操作手册、或部署这类想自己手动触发的副作用任务

渐进式加载与关键参数

• 加载分三层：名称和描述常驻上下文，SKILL.md 正文在判定相关时加载，链接的文件和脚本按需读取
• 描述加 when_to_use 在列表里会被截断到 1,536 字符；压缩后每个被调用的 skill 保留前 5,000 token，共享 25,000 token 预算
• 官方建议 SKILL.md 控制在 500 行以内，细节移到附属文件
• 常用 frontmatter 字段：name（即斜杠命令名）、description、disable-model-invocation（禁止自动触发）、allowed-tools、context: fork（在独立 subagent 中运行）、paths、model/effort

存放位置与优先级

• 五个层级：企业托管设置、个人 ~/.claude/skills/、项目 .claude/skills/、monorepo 子目录、插件内（命名空间为 plugin-name:skill-name）
• 同名冲突时企业级 > 个人 > 项目；skill 还会覆盖同名的内置 skill 或旧版 command
• 旧目录 .claude/commands/ 里的文件仍然有效，但同名时 skill 优先
• 注意：克隆仓库时 .claude/ 下的所有内容都是别人写的，包括 skill

和 CLAUDE.md、hooks、MCP 怎么选

• CLAUDE.md 每次会话都加载，适合放始终适用的事实和约定，建议 200 行以内
• Skill 按需加载，适合偶尔要用的操作手册和参考资料；slash command 是旧格式，已并入 skill
• Hooks 在生命周期事件上运行确定性代码，零上下文成本，是唯一能真正强制执行规则的方式
• MCP 用于连接外部系统，通过权限和网关做约束；subagent 提供独立上下文的隔离执行

安全：skill 是请求，不是保证

• Anthropic 官方明确：写在 skill 里的规则是请求而非保证，硬性限制要用 hooks
• Cloud Security Alliance 引用的 2026 年 2 月审计显示：3,984 个 skill 中 1,467 个（36.82%）存在安全缺陷，76 个带确认的恶意载荷
• Check Point 2026 年 2 月报告了三个由恶意项目配置触发的 Claude Code 漏洞，现已修复
• 两个要警惕的机制：附属脚本通过 shell 执行而非载入上下文；动态上下文注入会在 Claude 看到 skill 前运行 shell 命令——都省 token，也都是攻击面

上手建议

• 先看内置的 /code-review、/batch、/debug，用法和自己写的 skill 一样
• 写 description 时说清两件事：这个 skill 做什么、什么时候该用，因为这段文字每次请求都占上下文
• 有副作用的任务（如部署）加 disable-model-invocation，只允许自己手动触发
• 安装第三方 skill 前先读 SKILL.md 和附带的脚本，把它当成会以你的权限运行的代码来审查