如果你准备写第一个 Claude Code Skill，最容易踩的坑不是语法，而是先把 Codex 的目录、命名和调用方式拿来套。Claude Code 的 Skill 结构有自己的一套规则：入口文件仍然是 SKILL.md，但默认目录是 ~/.claude/skills/ 或项目内 .claude/skills/，而且通过 YAML frontmatter 决定何时自动触发。把这层边界弄清楚，第一次上手其实并不难。
核心结论：先做一个最小可用 Skill，再逐步扩展
第一个 Claude Code Skill 最好只解决一个清楚任务，例如“总结改动”“准备发布说明”“检查 PR 风险”。官方文档明确要求 Skill 目录里有 SKILL.md，其中前半部分是 YAML frontmatter，至少写清 description；后半部分才是具体指令。你不需要一开始就加上脚本、子代理、复杂前言字段，先把一个最小闭环跑通最重要。
适用人群与准备条件
这篇文章适合已经在用 Claude Code、想把重复操作沉淀成命令的人，也适合从别的平台迁移过来、需要先理解目录和作用域差异的用户。准备条件很简单：确认你能访问 ~/.claude/skills/ 或项目内 .claude/skills/，并且知道这份 Skill 只想给自己用，还是想随仓库一起共享给团队。
第一个最小目录应该长什么样
.claude/
skills/
summarize-changes/
SKILL.md根据官方文档，目录名会变成你输入的命令名，description 则帮助 Claude 判断何时自动加载。一个最小可用的 SKILL.md 可以是：
---
description: 当用户要求总结当前代码改动、整理提交说明或生成变更摘要时使用
---
读取当前改动，按“改了什么、为什么改、需要注意什么”三个部分输出摘要。实际使用示例
假设你正在整理一次前端提交，平时总要反复解释“先看改动、再归纳影响、最后给出简洁摘要”。这时就可以把这套固定流程做成 summarize-changes Skill。项目级放法是 .claude/skills/summarize-changes/SKILL.md，个人级放法是 ~/.claude/skills/summarize-changes/SKILL.md。如果它只是当前仓库规范，放项目目录更合适；如果它是你所有项目都会用到的习惯，就放个人目录。
Claude Code 的层级规则要先记住
官方文档说明，Claude Code 的同名 Skill 存在明确覆盖关系：企业级覆盖个人级，个人级覆盖项目级；插件 Skill 使用 plugin-name:skill-name 命名空间，因此不会和普通层级直接冲突。也就是说，当你发现“明明改了项目里的 Skill，结果调用的还是旧版本”时，首先要检查是不是上层目录已经有同名 Skill 抢先生效。
常见错误、限制和避坑
- 把 Codex 的
.agents/skills当成 Claude Code 的目录来用。 description写得太宽，结果模型在不该触发时也加载它。- 一开始就把 Skill 做成大杂烩，导致后面难维护。
- 项目和个人目录里放了同名 Skill，却没意识到存在覆盖关系。
最后建议：先小范围试运行，再放大
无论你现在看到的是概念解释、目录结构、安装方法还是排查思路，真正落地时都建议先选一个低风险、小范围、可回滚的任务试运行。先把输入样本、执行步骤、关键命令、最终结果和失败情况记录下来，再回头看哪些规则是稳定的、哪些描述还太宽、哪些动作应该交给脚本或工具。这样做的好处是，你不会因为第一次就追求完整而把流程做得过重，也不会在边界还没摸清时过早共享给团队。
如果试运行期间仍然需要频繁口头补充，说明这部分知识还没有真正沉淀进正文。等一次小范围试运行已经能稳定复现同样结果，再把它扩展到更多目录、更多同事或更多系统，并补上禁用、回滚、验收和来源更新规则。对 Skill、MCP 和自动化来说，最省时间的路线通常不是一开始就做大，而是先做小、做稳、保留证据，再逐步放权。
如果你准备把第一版给同事试用，最好再配一个“应该触发”和“不要触发”的示例提示。这样你一方面能验证 description 是否收得够窄，另一方面也能更快判断这份最小 Skill 是否已经到了可共享的程度。
相关阅读
总结
写第一个 Claude Code Skill，关键不是追求复杂，而是先用正确目录放好 SKILL.md，用清楚的 description 缩小触发范围，再让正文只解决一个明确任务。把最小闭环跑通后，再继续加脚本、模板或更细的前言字段，会稳得多。
