最近 Claude Code 的 Skills 机制算是彻底火起来了。我自己的项目里真正让我把重复劳动交给 Agent 的反而不是那些花哨的系统提示词而是 Claude Code skills 官方版这套明确定义的技能体系。之前我也试过把各种“万能提示词”塞进 CLAUDE.md结果上下文被占得厉害任务一多就乱换成官方版 Skills 之后整个工作流一下清爽了。这篇文章把我从理解技能机制、安装环境、踩坑社区技能包到亲手写自己 skill 的过程完整梳理一遍适合正在用或者准备用 Claude Code 的前端、全栈还有拿它写论文、做数学建模的同学。1. 先搞清楚Skills 和“多写一段提示词”到底差在哪1.1 为什么 Agent 时代需要“技能”这种新抽象用 Claude Code 之前大多数人处理重复任务的思路就是“把提示词存在某个地方下次复制粘贴”。我一开始也是这么干的把各种开发规范、代码生成模板、论文润色要求全堆在 CLAUDE.md 里。项目小的时候没问题项目一复杂就开始头疼Claude 每次对话都要读一遍全局规则几千行的 CLAUDE.md 等于每次都在烧上下文而且规则之间容易互相干扰比如给前端项目写的组件规范会被模型错误地用到后端代码上。Skills 解决的就是这个问题。它把“领域知识 操作步骤 可执行脚本 参考资料”打包成一个自包含的模块平时 Claude 只扫描每个技能的 name 和 description不把细节全部读进上下文。等用户任务真正匹配到某个技能时才把 SKILL.md 正文、脚本、参考文档加载进来。这就像 CLAUDE.md 是公司的员工手册人人入职都要看而 Skill 是某个部门的作业指导书加上工具包只有接到相关工单才会翻开。这个抽象层级的变化才是官方版 Skills 最有价值的地方。1.2 官方版 Skills 的核心设计一个目录加一个 SKILL.md如果你看过 Anthropic 官方发布的 skills 文档会发现整个机制简单到有点不像官方功能一个技能就是一个子目录目录里放一个 SKILL.md 文件文件名固定再按需放脚本和参考资料。~/.claude/skills/ ├── pdf-helper/ │ ├── SKILL.md │ └── scripts/ │ └── extract_text.py └── docx-builder/ ├── SKILL.md └── references/ └── template.docxSKILL.md 采用 Markdown 格式顶部是 YAML frontmatter里面有两个关键字段name和description。name是技能的唯一标识description则是给模型看的“技能说明书”用来判断什么时候该触发这个技能。正文部分写具体的执行步骤、输出格式、注意事项。目录里还可以放scripts/放可执行脚本references/放模板和参考资料模型在执行任务时能按需读取。为什么官方做成这么简单的结构我理解是为了降低门槛和保证兼容性。不用搞复杂的依赖管理不用写插件框架一个会写 Markdown 的人就能开发技能模型也能很自然地理解这套约定扫描目录成本极低。对普通用户来说把 GitHub 上别人做好的技能 clone 到目录里就能用这也解释了为什么社区里 skills 生态涨得这么快。1.3 一条技能在对话里是怎么被激活的官方的触发逻辑大致是这样Claude Code 启动一个新会话时会扫描用户级和项目级技能目录解析每个 SKILL.md 的 frontmatter。当你提出任务时模型根据当前对话内容和各技能的 description 做匹配判断哪个技能“最对口”。一旦命中就把该技能的正文和引用文件加入上下文然后按步骤执行。这个机制里最容易被忽略的是description的写法。很多人写 description 时喜欢堆形容词例如“这是一个功能强大的 PDF 处理工具”结果模型根本不知道什么时候该用它。正确做法是把触发场景写清楚比如“当用户需要提取 PDF 文本、合并 PDF 文件、或者把 PDF 转成 Markdown 时使用本技能”。description 写得好不好直接决定模型会不会在关键时刻想起这个技能。我自己早期写的几个技能就因为描述太含糊在实战里一次都没被触发过。2. 环境预备把 Claude Code 装到能“用技能”的状态2.1 安装的三种姿势命令行、VS Code、桌面端命令行是主流的用法Node 环境下一条命令就装好npm install -g anthropic-ai/claude-code如果你所在地区访问官方 npm 源不太稳定可以把 registry 切到国内的 npmmirror 镜像速度会好很多这是常规做法不影响功能。除了命令行官方还提供了 Claude Code 的 VS Code 扩展和桌面客户端。桌面客户端适合不爱敲命令的同学会话管理更直观底层的技能机制和命令行完全一致VS Code 扩展则适合边写代码边和 Agent 协作的场景选中代码直接提问技能照常生效。我个人的习惯是日常全部用命令行只有在涉及前端页面调试时才打开 VS Code 扩展同一个账号体系下的技能配置是共享的不用来回迁移。装完先别急着用跑一下claude进入交互界面确认版本号正常。因为官方更新很勤不同版本的技能加载行为会有细微差异建议保持最新版本升级的时候技能目录一般不会动不用担心自己的 skills 丢失。2.2 账号订阅和组织权限那个让人抓狂的“disabled”报错很多人第一次用 Claude Code 会碰见这句话Your organization has disabled Claude subscription access for Claude Code。我第一次看到还以为是网络问题折腾了半天发现完全不是。这个报错的含义很直接你的账号属于某个组织Organization而组织管理员在后台设置里把 Claude Code 的访问权限关掉了。Claude Code 需要绑定 Claude 付费订阅Pro 或 Max或者 API 计费而组织管理员可以在 Settings 里的 Member permissions 中关闭对 Claude Code 的开关。所以这是个权限问题不是安装问题。解决路径有三条如果你是组织成员找管理员打开 Claude Code access如果你只是被拉进一个组织但不需要团队协作直接退出组织、用个人账号登录反而最省事如果你本来就用 API 计费那就走 API key 的认证方式不依赖订阅开关。我建议团队用户直接找管理员开权限别用共享账号登录 Claude Code后患无穷。2.3 确认默认技能目录和第一个技能生效安装完成后Claude 会自动识别两个技能目录用户级目录~/.claude/skills/和项目级目录.claude/skills/。用户级的是所有项目通用的项目级的只对当前仓库生效后者的优先级更高。两条目录同时存在时项目级会覆盖用户级同名技能。验证整个链路是否通畅我的做法是放一个最简单的测试技能进去。在~/.claude/skills/hello-skill/下创建SKILL.md--- name: hello-skill description: 当用户说打招呼或测试技能时使用本技能回复一段问候。 --- ## 步骤 1. 用友好的语气和用户打招呼。 2. 告诉用户技能机制运行正常。然后进入 Claude Code输入“帮我测试一下技能”如果能得到一段问候说明技能扫描、触发、加载全链路都通了。新版本的 Claude Code 还支持/skills命令查看当前加载的技能列表如果你的版本不支持这个命令直接看目录结构也行。3. 官方技能仓与社区热门 Skills我实测过值得装的几个3.1 官方技能仓先从 anthropics/skills 装起最稳的来源永远是 Anthropic 官方仓库anthropics/skills。里面有官方维护的文档处理技能集比如 docx、pptx、xlsx、pdf 的创建和编辑能力还有 webapp 生成、artifacts 构建等偏向开发类的技能。用官方技能的好处是质量和模型行为配合得最好不会出现社区技能那种指令和模型版本不兼容的问题。把 GitHub 上的 skills 手动装到本地方案很简单git clone --depth 1 https://github.com/anthropics/skills.git # 然后把需要的子目录复制到 ~/.claude/skills/ cp -r skills/document-skills/docx ~/.claude/skills/只复制你用到的那几个子目录不要整个仓库都塞进技能目录否则每次对话扫描技能时会有大量无关条目既拖慢启动速度也让模型的技能匹配变得混乱。3.2 社区全家桶superpowers skills 到底值不值得装社区里最出名的技能包是 superpowers一个包含头脑风暴、调试、规划、代码审查等十几个技能的合集。我刚知道的时候很兴奋一次性全装进去了结果反而不太好用。原因很典型技能之间 description 互相重叠模型经常不知道该触发“头脑风暴”还是“规划”或者干脆选了错误的那一个帮我生成了一堆形式化的流程文档没任何实际价值。现在我倾向于只挑其中两三个核心技能来用。如果你要装 superpowers不要直接把整个仓库链接到技能目录而是进到子目录里按需复制单个技能进来。技能不是越多越好每个技能就像是给 Agent 多塞了一张“名片”名片多了反而让它认不出人。3.3 按场景挑技能前端、数学建模、论文和嵌入式不同人群需要的技能完全不同我按常见的搜索热词总结过一批实测体验使用场景值得装的技能方向实际效果前端开发组件代码生成、React/Vue 项目结构审计、Tailwind 样式修复生成代码的规范度明显提高能自动匹配项目里已有设计模式数学建模LaTeX 排版、符号计算辅助、数据拟合脚本生成写论文公式和调模型参数时省了大量手工活论文写作参考文献格式整理、学术语言润色、摘要提炼避免常见的“AI 味”词汇格式准确率很高嵌入式开发STM32 工程模板生成、引脚配置脚本、烧录日志解析处理寄存器配置和管脚定义时更专业但需要自己核对挑选建议就一句话按“你每周都会重复做的事”来选技能偶尔才做一次的事情不值得占技能名额。我之前看到一个处理安卓包分析的技能热度挺高但这不属于我常规工作流就没装技能目录保持精简模型触发才足够精准。4. 手把手开发一个自己的官方版 Skills4.1 最小可用的技能先写一个“项目复盘”技能与其到处找现成的不如自己写一个。我从一个非常简单的需求开始让 AI 按固定结构做项目复盘。这个技能不需要脚本纯靠 SKILL.md 约束输出格式。在~/.claude/skills/project-review/下创建SKILL.md--- name: project-review description: 当用户要求做项目复盘、项目总结或回顾迭代情况时使用本技能生成结构化复盘报告。 --- ## 任务 对当前项目或最近迭代进行复盘。 ## 输出格式 1. **目标回顾**本次项目的核心目标是什么。 2. **完成情况**对比目标逐条说明完成度。 3. **问题与根因**列出遇到的问题分析原因不要只列现象。 4. **改进措施**给出下个迭代可以落地的行动项。 ## 注意 - 先用 git log 和文件变更情况了解实际进度不要凭空总结。 - 改进措施要具体不要写“加强沟通”这类空话。这个技能写完后你在对话里说“帮我对这周的工作做个复盘”Claude 就会按规定结构输出。注意我特别写了“先看 git log”这一步是为了避免 AI 在缺少上下文时瞎编进度。4.2 SKILL.md 的编写规范名字起得好触发率才高写技能时最忌讳的是把 SKILL.md 当成一篇随笔。name要简短尽量用连字符连接例如pdf-helper、code-reviewerdescription要包含触发条件和使用场景。我发现一个实用的写法是套用这个格式“当用户需要做 X 时使用本技能完成 Y最终输出 Z”。这样模型能快速判断匹配度。正文部分建议分成这几个板块任务目标、执行步骤、输出格式、注意事项。执行步骤写得越明确模型就越不容易自由发挥。比如你让它处理 PDF就明确写“先用 scripts 目录下的 extract_text.py 提取文本再做清洗最后输出 Markdown”而不是只写“处理 PDF 并输出结果”。另外有一点常被忽略SKILL.md 正文本身也是上下文的一部分别写得像论文那么长。能用 200 字说明白的不要写 2000 字。更详细的参考资料放到references/目录里Claude 只有需要时才会去读。这其实就是一种“上下文经济学”。4.3 带脚本的进阶技能用 Python 处理本地文件纯提示词约束的技能效果有限真正厉害的是让技能携带可执行脚本。比如我写了一个批量清理项目日志和临时文件的技能在技能目录里放了一个 Python 脚本#!/usr/bin/env python3 import os import sys import shutil target_dir sys.argv[1] if len(sys.argv) 1 else . cleaned 0 for root, dirs, files in os.walk(target_dir): for file in files: if file.endswith(.log) or file.endswith(.tmp): path os.path.join(root, file) os.remove(path) cleaned 1 print(f清理完成共删除 {cleaned} 个临时文件)然后在 SKILL.md 里告诉模型触发的完整动作先运行python3 scripts/clean_temps.py 目标目录根据输出总结清理结果再询问用户是否需要把删除列表记录到日志。这里的关键是模型不会自己猜脚本的传参你必须在技能文档里写清楚“运行什么命令、传什么参数、拿到输出之后怎么处理”。实际使用下来这种“技能即工具包”的方式比纯提示词更可靠。因为脚本处理的是确定性操作AI 只需要负责判断何时执行、如何解释结果、是否要请求用户确认分工很合理。4.4 在技能里带参考资料references 目录的正确用法如果你的任务依赖固定模板比如论文格式要求、周报模板、数据库表结构说明那一定要用 references 目录。Claude 默认不会主动加载 references 里的全部内容而是在技能被触发且需要模板时才去读取这对上下文非常友好。我自己写论文润色技能时就把目标期刊的写作规范、参考文献样例放进了 references 目录SKILL.md 正文里只写“当需要润色论文时先读取 references/format_guide.md 中的规范再按该规范改写”。这样既保证了输出风格符合要求又不会每个对话都白白占用大量 token。references 里还能放代码片段模板、SQL 示例、配置文件样例。本质上是在给技能提供“旁路记忆”把不需要常驻上下文但偶尔必须用到的信息沉淀下来。4.5 调试技巧怎么判断技能有没有真正触发写完技能后最怕的情况是明明写了Claude 却像没看见一样。判断技能是否触发可以用两条路径一是直接在对话里输出与 description 高度匹配的任务描述观察模型是否按 SKILL.md 里的步骤走二是打开模型日志在调试模式里看技能扫描和加载的记录。我踩过一个典型坑给技能写的 description 是“处理 Markdown 文件”结果我测试时说的是“帮我把这份 md 文档整理一下”模型始终没触发。改成“当用户提到 md 文档、Markdown 文件整理、排版修正时使用本技能”之后立刻就能命中。原因就是模型匹配的是语义近似不是关键词完全一致你的 description 要把可能的用户表述都覆盖到但又不能范围大到什么都接。5. 进阶玩法接入 DeepSeek、LM Studio 本地模型1M 上下文5.1 用兼容 API 让 Claude Code 跑不同的模型Claude Code 官方支持通过环境变量把模型端点指向任何兼容 Anthropic API 的服务。这也是社区里很多人把 Claude Code 接 DeepSeek 的原理。配置方式很简单export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的 API Key设置好后再启动 claude它就会走新的端点。这种用法适合预算有限或者想试试开源模型的用户。但我要提醒一点Claude Code 的 skills 机制高度依赖模型的工具调用能力也就是说模型必须能准确理解 SKILL.md 的结构并且愿意按照步骤执行脚本。换成兼容 API 后不同模型对技能的理解程度差异很大我实测过有些模型根本不会按 frontmatter 的 description 做匹配结果就是技能形同虚设。所以优先还是用官方模型跑 skills兼容 API 适合跑一些不太依赖技能链的简单任务。5.2 调 LM Studio 本地模型离线场景的取舍LM Studio 这类本地推理工具也能作为 Claude Code 的后端。把 LM Studio 启动本地服务后设置ANTHROPIC_BASE_URL为本地地址即可常见的是http://localhost:1234。本地模型最大的优势是隐私和免费但用在 skills 场景上有明显短板技能里的脚本类操作、复杂的多步执行逻辑小参数模型往往执行不到位。我的建议是本地模型适合做代码补全、简单问答这类低强度任务如果你想用 skills 做完整工作流还是老实回到云端模型。另外本地模型对工具调用的支持因模型而异先用一个最简单的测试技能跑通链路再谈复杂技能。5.3 1M 上下文与技能配合的“上下文经济学”Claude Code 支持的 1M 超长上下文对技能使用有一个微妙影响很多人的第一反应是“上下文大了可以把所有技能内容一次性塞进去”。我的看法恰恰相反超长上下文更应该配合技能按需加载的设计。1M 上下文的优势在于海纳整个大型代码仓库、长文档而不在于代替 skills 做知识管理。如果项目仓库特别大你可以让技能引用索引文件SKILL.md 里只写“先从 references/index.md 中确定相关代码位置”再把目标文件加入上下文。这样 1M 上下文留给真正需要反复分析的代码内容而技能描述、索引这类轻量信息只占用很小的空间。两者配合起来才能做到既不爆上下文又能在大项目里精准作业。6. 我踩过的坑装了一堆 skills 之后的真实教训6.1 同名技能互相覆盖行为变得不可预测Skills 生态起来之后同名技能的情况非常多。比如“pdf-tools”这个技能官方仓库有社区里可能有三四个不同作者也做了。如果都装到技能目录里会发生项目级覆盖用户级的情况或者两个同名技能并存模型扫到的是哪一个完全看运气。我遇到过最坑的一次是装了一个社区版代码审计技能结果项目里有另一个同名但功能不同的技能模型做出了完全错误的审计动作白白浪费了半天。现在我的做法是装任何技能之前先检查~/.claude/skills和.claude/skills里有没有同名目录用/skills命令确认当前加载的是哪个版本。如果项目必须用某个特定版本就把它单独放在项目级目录里确保优先级。6.2 安全风险来路不明的脚本不要直接执行Skills 最强大的地方也伴随最大风险技能可以携带任意脚本。你从 GitHub 上下载一个技能时它目录里的 Python 或 Shell 脚本在你的机器上拥有和本地用户一样的权限。官方对技能脚本有权限确认机制首次执行之前通常需要你确认但很多人习惯了回车确认危险就在这里。我现在对来路不明的技能秉持极简原则只看官方仓库和 star 数高、作者名声好的技能包安装后先打开脚本文件读一遍确认没有删除文件、外传数据、读取敏感目录等危险操作真正在项目里执行时第一次执行一定让它“先说明要运行什么命令”让我确认后再放行。技能这个机制每多一份便利就多一份责任宁可麻烦一点也别让自己的机器变成实验场。6.3 触发失灵时的排查清单按顺序检查这几项如果你加了新技能但发现 Claude 始终不调用我建议按这个顺序排查技能目录路径是否正确。个人级是~/.claude/skills项目级是.claude/skills别放错地方。SKILL.md 文件名和 frontmatter 格式是否正确。YAML 语法出错会导致整个技能被跳过。description 是否覆盖了你测试时用的描述。语义匹配不是关键词匹配测试时最好用你平时说话的口吻。是否被同名技能覆盖。项目级同名技能会“压住”用户级技能。模型版本是否太旧。新技能格式在老版本上可能不被支持升级 Claude Code 后再测。把这五步走完95% 的触发问题都能定位。剩下的 5% 可能是模型偶发行为把会话重启一次往往就好了。我自己现在维护的技能库基本控制在十个以内全部在 Git 仓库里管理每个技能的改动都留记录出了问题随时回滚。Skills 这个机制最吸引人的地方不在于“收集得多”而在于它让 AI 从一个通用对话工具变成了真正适配个人工作流的助手。与其到处找别人的技能包不如从自己最重复、最头疼的任务开始动手写一个属于自己的 SKILL.md。等你跑通第一个技能再看 Claude Code整个使用体验会完全不一样。