从零搭建Claude Skill：完整实操教程与避坑指南

说实话最近后台私信里问得最多的一个问题就是Claude的Skill到底怎么搭是不是不会写代码就玩不了网上关于ClaudeSkill的资料并不少但要么是官方文档的翻译腔要么是“一分钟上手”的标题党真正能让人从头到尾跑通的完整教程不多。我这几周正好把一个内部自动化流程整体迁到Claude上Skill从零搭了好几套踩过的坑比写过的步骤还多。干脆把整个过程沉淀成一篇实操向的长文从环境准备讲起到你亲手写完第一个能用的Skill为止。适合完全零基础、刚接触Claude Code的朋友也适合想系统理一遍Skill设计逻辑的人。看完你大概能明白Skill没那么多玄学就是把你的重复劳动包装成一套Claude能照着跑的流程。1. Skill到底是个啥先建立正确认知1.1 Claude Code和Skill是什么关系Claude Code是Anthropic推出的命令行编程助手名字里带Code但实际能力不限于写代码。它能读你本地文件、执行终端命令、调用各种工具像一个长在终端里的智能助理。Skill是这个体系里最有意思的设计你把一套固定工作流程写成说明书Claude在合适的场景下会照着说明书一步步执行。用一个生活化类比理解把Claude Code想象成一个新来的实习生能力很强但不知道你的工作习惯。你每天给他派活都要现场交代一遍“先查数据、再整理、最后写报告”。Skill就是一份标准作业手册。实习生拿到手册不用你重复交代自己就知道按编号步骤干。你要是没给他手册他每次都会来问你给了他且写得好他就能独立干活质量还稳定。在Claude Code的语境里这个“手册”叫SKILL.md放在固定的Skill目录下。Claude运行时会根据当前对话内容判断要不要调用这个Skill一旦启用它就会读取SKILL.md里的指令按步骤执行中间可以调用同目录下的脚本、读取参考资料。说白了Skill做的就是“把隐性的个人经验显性化”。1.2 为什么零基础也能搞定很多人一听Skill就以为要写复杂程序其实大部分Skill只有三个零件一段给Claude看的操作说明、一个可选的执行脚本、一段用来触发调用的描述信息。你不需要会写代码会用Markdown写清单就能做最基础的知识型Skill就算要写脚本来处理数据也只需要复制粘贴一个单文件脚本的起步水平。我见过很多从零开始的朋友第一反应是去研究Python、研究API结果卡在环境配置上就放弃了。实际上Skill的构成里最核心的是SKILL.md这个文本文件它占了一个Skill可靠性的七成。脚本只是辅助手段用来执行那些模型做不了的事情比如读取系统信息、运行外部命令、精确计算。理解这一点之后你会发现搭一个Skill的门槛其实极低跟写一份详细的会议纪要差不多。2. 环境准备把Claude Code装好跑起来2.1 安装前的检查清单在折腾Skill之前你得先把Claude Code本身装好。这里我给一份清单一次检查完再动手能省去后面很多莫名其妙的问题。检查项要求备注操作系统Windows 10/11、macOS、主流Linux发行版都能跑体验略有差异Node.js18及以上npm安装方式依赖它终端Windows建议用PowerShell或Windows Terminal老版cmd对命令支持不太行网络能正常访问官方服务即可安装和登录都要求连通性正常Windows用户特别注意一条如果你计划在本地跑完整功能要去“控制面板 - 启用或关闭Windows功能”里确认“虚拟机平台”这一项已开启。这不是Claude Code的Bug而是它依赖的Windows功能没开很多人装完启动直接报“Claudes workspace requires the virtual machine platform on Windows”就是因为这里。macOS和Linux用户相对省心只要Node.js版本没问题终端有权限写入全局目录基本就是一路顺畅。建议装之前先跑一下node -v和npm -v确认环境。版本号太低或者干脆没装Node的先去装一个Node.js长期支持版这是最稳的路。2.2 三种安装方式实测对比Claude Code的安装方式有好几种我这里只讲亲自试过、且给身边朋友推荐过的三种各有适用人群。第一种npm全局安装最通用npm install -g anthropic-ai/claude-code装完直接用claude命令启动。升级也是同一行命令后面加latest即可。这种方式的好处是干净、跨平台、好管理我自己的主力机器就是这么装的。第二种VSCode插件。你如果平时主要在一个代码编辑器里工作直接在扩展市场搜“Claude Code”装好之后可以从侧边栏或命令面板启动。它本质上是把CLI嵌进编辑器好处是代码上下文天然可见边聊边看代码很舒服。这种方式也自动帮你处理了部分环境问题Windows用户如果命令行装的时候报错可以试试它。第三种官方安装脚本适合macOS和Linux用户curl -fsSL https://claude.ai/install.sh | bash一句话就跑完但它会自动往你的shell配置里写环境变量介意的话用npm方式更可控。这三种方式没有绝对的好坏我的建议是刚开始折腾就用npm遇到问题好排查如果你本来天天开着VSCode就装插件版少一个学习成本。桌面版我没把它放进来做首选原因很简单这套流程主打轻量和灵活CLI是生态里迭代最快、资料最多的入口。2.3 第一次启动登录与授权装完之后在项目文件夹里打开终端输入claude如果是第一次运行它会让选择登录方式。选你手头可用的邮箱或官方账号渠道登录然后在浏览器里完成授权终端窗口会自动进入交互界面。到这里Claude Code就算跑起来了。有一点很多人第一次会踩Claude默认只操作当前目录内的文件。你想让它“看看这个项目”或者“分析一下昨天的日志”得先cd到那个目录再启动。这不是限制是安全设计免得AI随手翻你整台电脑。实际用久了你会发现这个机制配合Skill目录反而让权限边界很清晰。登录成功之后顺手验证一下版本claude --version看到版本号输出就说明CLI正常。如果你在这个步骤就遇到了Windows那个虚拟机平台报错重启电脑后再跑一次基本都能解决。3. 拆解Skill的标准结构先看懂官方设计3.1 一个Skill最少需要什么Skill在Claude Code里的组织方式是“一个目录一个Skill”。下面是一个最典型的目录结构~/.claude/skills/ └── weekly-report/ ├── SKILL.md └── scripts/ └── generate.py对应到实际使用~/.claude/skills/是全局Skill仓库所有项目都能看到如果你只想让某个项目用某个Skill可以在项目根目录下建.claude/skills/效果相同。这个目录里的主角是SKILL.md它由两部分组成。开头是YAML格式的元信息核心就两个字段--- name: weekly-report description: 当用户要求生成周报、周总结或提到分析git提交记录时使用 ---name是Skill的短名称尽量用连字符分隔的小写单词description是重中之重它决定了Claude什么时候想起还藏着一个你写的Skill。接着是正文部分用普通Markdown写给Claude看的操作指令。Claude一旦决定调用这个Skill就会把正文读进上下文按你写的步骤执行。这不是给人看的说明书而是给模型看的标准作业程序所以要尽可能具体、可执行。3.2 description是灵魂为什么Claude会找错Skill很多人写完Skill之后最沮丧的时刻就是明明目录对了、文档也写了Claude却死活不调用或者该用A Skill的时候用了B Skill。问题十有八九出在description上。Claude判断要不要用某个Skill主要靠语义匹配description和当前对话的相似度。它不是把所有Skill内容都读一遍再决定而是先快速扫描描述信息觉得你正在说的这件事和某条描述匹配才把那个Skill加载进来执行。所以description写得好不好直接决定了Skill会不会被激活。我对比几个写法你感受一下。差的写法用于生成周报的skill。周报生成器功能强大支持多种格式。好的写法当用户要求生成周报、周总结或提到需要查看git提交记录并汇总本周工作时使用。在用户提供项目目录、要求把最近的代码提交整理成工作总结时触发。看出差别没有好的description把“用户可能怎么表达需求”都装进去了动词是“要求”“提到”“需要”场景是具体的“查看git提交记录”“整理代码提交”。Claude匹配到这种描述命中率明显提升。还有一个容易被忽略的点description里不要塞形容词和功能吹嘘。什么“功能强大”“业界领先”“极速处理”模型不靠这个判断反而稀释了触发意图。写清楚“什么时候用”比写“我多厉害”重要得多。3.3 Skill脚本与模型能力的分工一个Skill里既有文本指导又有脚本那哪些事让模型做哪些事让脚本做这是设计Skill时最需要想清楚的问题。我的原则很简单模型擅长自然语言理解和生成脚本擅长确定性操作。凡是“理解语义、归纳总结、改写润色、按规则输出文档”这类事交给模型凡是“执行命令、读文件系统、解析数据、调API、做精确计算”这类事交给脚本。举周报的例子收集最近7天的git提交记录这件事用脚本做一条命令就拿到结构化数据又快又准把提交信息润色成面向团队的工作总结这件事用脚本做不现实用自然语言规则让模型做最合适。新手最常犯的错是“过度工程化”试图把整个流程都写进Python脚本模型只负责把脚本输出原样贴出去。结果就是脚本越写越长改一个格式要求就要动代码Skill失去灵活性。记住这句话脚本是给模型打辅助的不是反过来让模型给脚本打辅助。4. 从零写一个Skill周报生成器全流程实操4.1 先明确需求再动手空谈设计理念没用我拿自己实际用的周报Skill当例子完整走一遍从零到能跑你照着做就能复现。先说场景。我在一个项目里每天有多次git提交每周要交一份工作总结。人工流程是打开终端敲git log翻一堆提交记录在脑子里边回忆边总结最后拼成一封信格式的周报。这套流程每周重复一次烦而且每次格式都不太统一。那我希望达到的效果是什么在Claude里直接说一句“帮我把上周的提交生成一份周报”它自己去跑git命令、读提交记录、按我习惯的格式输出中间不用我再操心。这件事听起来小但它把“从数据收集到文档产出”的整条链路都覆盖了拿它当第一个Skill再合适不过。4.2 创建目录和SKILL.md先建目录。在终端里执行mkdir -p ~/.claude/skills/weekly-report/scriptsWindows PowerShell下可以写mkdir $HOME\.claude\skills\weekly-report\scripts然后创建SKILL.md把下面内容放进去--- name: weekly-report description: 当用户要求生成周报、周总结或提到分析git提交记录汇总本周工作时使用 --- # 周报生成流程 你的任务是根据git提交历史生成一份中文周工作总结。 ## 执行步骤 1. 运行以下脚本获取最近7天的提交记录 python scripts/generate.py --since 7 days ago 2. 读取脚本输出的JSON数组数组每个元素包含hash、author、date、subject四个字段。 3. 根据commit的subject判断工作内容按以下规则归纳总结 - 将同一功能模块的提交合并为一条要点 - 用一句话概括每个要点开头不用重复“本周完成了”这类套话 - 涉及bug修复的在要点后标注“修复” 4. 按下面的Markdown模板输出 ## 本周工作总结 ### 功能开发 - 要点1 - 要点2 ### 问题修复 - 修复项1 - 修复项2 本周共处理 N 条提交记录涉及 M 个模块。这里面每一步都有讲究。步骤1是脚本调用明确写了命令和参数Claude不会自己去猜步骤2规定了数据的读取方式告诉它脚本输出是JSON步骤3是核心我把“同一个模块的提交要合并”“bug修复要标注”这种个人习惯写成了给模型的规则步骤4给了输出模板让它知道最终交付物的格式。写SKILL.md的时候有两条经验一是命令路径要写相对路径因为Claude会在Skill目录下执行命令二是步骤宁可细不要短模型和实习生一样你交代得越具体它干得越接近你想要的样子。4.3 写一个不啰嗦的脚本接下来创建scripts/generate.py内容如下#!/usr/bin/env python3 import subprocess import json import sys def main(): since sys.argv[1] if len(sys.argv) 1 else 7 days ago result subprocess.run( [git, log, --since, since, --prettyformat:%h|%an|%ad|%s, --dateshort], capture_outputTrue, textTrue ) commits [] for line in result.stdout.strip().splitlines(): parts line.split(|, 3) if len(parts) 4: commits.append({ hash: parts[0], author: parts[1], date: parts[2], subject: parts[3] }) print(json.dumps(commits, ensure_asciiFalse, indent2)) if __name__ __main__: main()这个脚本做的事非常简单调git命令拿最近指定天数的提交把提交拆成哈希、作者、日期、提交说明四个字段最后以JSON格式输出。为什么输出选JSON而不是一段文本因为我踩过坑。脚本输出越规整模型解析得越准。早期版本我让脚本直接打印git原始日志模型经常把时间格式和提交信息混在一起理解润色出来的周报质量忽高忽低。改成JSON之后字段边界清晰模型总结的稳定度上一个台阶。不要小看这个单文件脚本它已经用到了两点工程上的讲究一是参数--since可以接收外部传入的时间范围SKILL.md里写的是“7 days ago”你再要“昨天”也能用二是用ensure_asciiFalse保证中文提交信息不乱码这点在中文项目里特别关键。4.4 挂载、运行与效果目录建好、文件写好Skill就算挂载了。不过有一个很多人容易漏的环节Claude Code不会在每个会话里实时扫描最新Skill建议你先重启一下终端里的会话再进对话。启动Claude Code后直接说帮我把上周的提交生成一份周报CLI这边会自动匹配description认为周报Skill适合当前任务然后依序执行SKILL.md里的步骤。它会先去找脚本、运行脚本、读取JSON输出最后按模板生成周报。我实测过几次效果符合预期周报里有功能开发模块、有问题修复模块末尾还有一句统计“本周共处理23条提交记录涉及5个模块”。生成模型需要一点“粗读数据再归纳”的时间但整个流程你不用再开第二次终端。需要提醒一点如果你的项目不在当前工作目录比如Skill在别的文件夹里Claude在运行脚本时会找不到git仓库。这时候在SKILL.md的步骤里补一句“先在项目目录下执行”或者干脆每次启动Claude时先cd到项目根目录实操里后者的成本最低。5. 进阶用法让Skill真正融入工作流5.1 大需求拆成小Skill第一个Skill跑通之后很多人会兴奋地想把所有需求都塞进Skill里。我劝你冷静。一个Skill里写七八个步骤、塞三四个脚本看着全能实际用起来既慢又容易出岔子。Skill设计上更推荐“小而专”。拿周报这个场景举例你可以拆成两个Skill一个叫git-log-collector专职负责从Git仓库里收集提交数据并输出JSON一个叫weekly-report负责把JSON数据润色成周报。如果哪天你想做一个“本月代码变动总览”前者还能复用后者也不用被动改。拆开之后还有一个额外好处description可以做得很干净各自在自己的触发场景里命中。“收集提交数据”和“生成周报”本来就是两回事硬绑在一起Claude在该调用A的时候会把B一起加载浪费上下文也拖慢响应。5.2 不带脚本的知识型Skill不是所有Skill都要带脚本。实际上我后来用得最频繁的一类Skill就是纯文本的知识型Skill连一行命令都没有。举个例子团队有代码Review规范包括命名、异常处理、不要写死配置等。以前我把这些规则写成文档贴在群里没人看。后来我建了一个code-review-skill目录SKILL.md里只写规范正文--- name: code-review-rules description: 当用户要求Review代码、检查代码质量或提到代码规范时使用 --- # 代码Review检查清单 按以下顺序检查提交的代码 1. 命名是否清晰是否使用项目约定缩写 2. 是否有硬编码的IP、密钥、路径 3. 异常分支是否有日志输出 4. 数据库操作是否做了参数校验 5. 改动是否影响了其他模块是否写了对应测试实际用了一周效果比文档好太多Claude在Review代码时会主动按这个清单逐条检查给出的意见明显更贴合团队习惯。这类Skill的价值是“把团队隐性知识变成AI的执行标准”。新人来了不用追着老人问Review要注意什么Claude替你承担了“记忆规范”的职责。5.3 社区生态现成Skill去哪找你不需要所有Skill都从零写。社区里已经有大量现成Skill可以抄来改网上有人做了“book to skill”把一本书的知识结构转成一个Skill方便Claude在特定话题下引用也有人做了“workbuddy skill”这类偏工作流管理的工具型Skill还有人在讨论“codex skill”的写法说明Skill这套模式在Agent工具圈里已经慢慢成了通用概念。我的建议是看到感兴趣的Skill先拆开看结构重点看它的description怎么写的、步骤怎么拆分的理解作者的设计思路比你从头闭门造车快很多。但注意不要为了图省事把网上七八个Skill一把梭全装进去。每加载一个Skill模型在判断时都要多扫描一条描述装太多无关Skill反而影响核心任务的响应质量。另外凡是带脚本的Skill第三方来源的最好先看一遍代码再放进目录。虽然大多数Skill是纯文本或简单脚本但“不运行不明代码”这条安全底线什么时候都不能丢。6. 常见问题与排查技巧实录6.1 问题速查表我在搭Skill的过程中遇到不少问题也帮朋友排查过好几轮。把最常遇到的整理成表遇到同样的问题直接对号入座。问题现象常见原因解决办法安装时EACCES权限报错npm全局目录没有写入权限用nvm重装Node避免直接给sudoWindows启动报VM Platform错误系统“虚拟机平台”未开启控制面板开启Windows功能中的“虚拟机平台”重启新增Skill后Claude不响应会话缓存未刷新退出并重新进入Claude会话Skill在错误场景触发description写得太泛把触发场景写具体限定“仅当……”该触发时没触发description缺少用户常用说法在description里补“提到……时使用”脚本报找不到python系统PATH里没有pythonSKILL.md命令改成python3或写绝对路径脚本输出中文乱码没有指定UTF-8编码在输出时用ensure_asciiFalse或加encoding参数命令在错误目录执行git仓库不在当前目录在SKILL.md里先写cd到项目目录的步骤6.2 我的几个避坑心得最后说几个从实际使用里沉淀出来的经验这些不太会写在官方文档里但直接影响体验。第一SKILL.md不要写成“法案”。我一开始习惯在文档里堆“必须”“严禁”“绝对不要”想让模型行为完全受控。结果发现约束太多反而让模型变得僵硬稍微超出模板范围就不会变通。后来换成“默认按这个执行除非用户另有说明”效果立刻变好该守的规则守住了该灵活的地方也灵活了。第二让脚本输出结构化数据。这一点我用很重的教训换来的脚本输出越规整模型表现越稳定。统一输出JSON远比输出一段散文式文本要强。靠模型做最终呈现脚本只负责把数据整理到“模型好读”的形态这是Skill设计里性价比最高的一条优化。第三Skill目录记得纳入版本管理。我的~/.claude/skills/本身就是个Git仓库每改一个Skill都会提交一次。改坏了随时回滚想去找“上周还能用的版本”也有地方查。不要高估自己的记忆力这个目录不纳入版本管理迟早会后悔。第四第一个Skill务必短小。控制在二十行Markdown以内先跑通整个链路再说。Skill的目录结构、触发机制、脚本调用方式这些链路跑通了后面一切好说一上来就想写“全公司自动周报系统”的大概率卡在写文档这一步就放弃了。如果你正准备搭第一个Skill别急着研究那些花哨的例子就把手头最烦的重复任务列出来挑一个最小的开始。我个人体会是Skill这套东西真正难的不是技术而是想清楚“什么事值得被固化下来”。我搭到第三个Skill的时候才明白少而精永远比多而全好用。先跑通一个让手边的活变轻一点再慢慢加后面你会越来越顺手。