这次我们不聊模型参数也不看跑分榜直接来看 Anthropic 官方在 Claude 生态里推出的一个非常实用的能力Agent Skills项目名anthropics/skills。它的定位很明确给 Claude 智能体装上“可复用的技能包”让你能把一套固定的工作流、提示词、脚本、参考资料打包成一个标准化模块在需要时自动被模型加载并执行。换句话说Claude 不再只能“即兴聊天”而是可以按你预先写好的操作手册去完成具体任务。这个机制最核心的几个点值得先记住第一格式统一一个 Skill 就是一个包含SKILL.md和资源文件的目录第二按需触发模型会根据任务描述自动判断要不要加载哪个技能第三生态发展很快社区里已经出现了大量现成 Skill覆盖前端开发、学术研究、PPT 制作、测试执行、音视频处理等场景。这篇文章我会带你把 Anthropic Skills 从概念到落地完整过一遍包括 Skills 的目录结构、如何安装社区 Skill、如何自己写一个 Skill以及在 Claude Code 和 API 环境里怎么验证它真的生效了。阅读这篇文章你会得到一套可以直接照做的技能包开发流程而不是只停留在“听说过”的层面。如果你正在用 Claude Code 做自动化任务、批量处理文档或者想把团队的固定流程沉淀成可复用的“技能”这篇内容值得收藏。1. 核心能力速览在开始之前先把 Anthropic Skills 的关键规格整理成一张表方便你快速判断这个项目适不适合你现在的工作流。能力项说明项目类型Claude 智能体的技能扩展机制 / 开源标准格式来源Anthropic 官方推出项目名为anthropics/skills核心机制把指令、脚本、参考资料打包成 Skill由模型按需加载主要功能代码编写、文档处理、测试执行、前端开发、研究分析等触发方式模型根据任务描述自动选择也可在 prompt 中显式指定硬件要求无需本地显卡普通开发机即可通过 Claude API 或 Claude Code 运行支持平台Claude Code、Claude Agent SDK、支持 Skill 的第三方工具启动方式claude启动后自动扫描 skills 目录或通过命令行安装是否支持 API支持Agent SDK 可以加载 Skill 并交由模型调用是否支持批量任务可以Skill 内可包含批量处理脚本配合循环调用适合场景个人自动化、团队标准流程、测试脚本沉淀、文档批处理从能力边界来看Anthropic Skills 不是一个独立的推理模型也不是一个本地一键包。它更像是一个“标准协议 运行环境”你负责把流程结构化模型负责在合适的时机调用这个流程。所以它没有传统本地部署项目的那种“显存占用”概念你真正需要关注的资源是 API 额度、上下文长度以及技能文件本身的组织质量。2. 适用场景与使用边界Skills 适合解决的是“重复但非纯规则化”的任务。举例来说让 Claude 每次都用同一种风格写周报可以用一个weekly-reportSkill让 Claude 按固定规范做前端代码审查可以用一个frontend-reviewSkill让 Claude 读取 PDF 后按统一格式输出结构化笔记也可以做成一个 Skill。这类任务的特点是有明确流程、有固定输出格式、但输入内容每次不同正好是 Skills 的用武之地。从社区热词也能看出 Skills 的典型使用方向“superpower skills 安装”代表了用户想要直接使用现成技能包“前端开发 skills”和“opencode skills”代表了开发场景下的技能需求“academic research skills”、“ppt skills”、“nature skills”则说明知识工作场景同样热门。这里面既有官方能力也有第三方插件型项目比如superpowers这类 Claude Code 技能合集它们共享的都是 Anthropic 提出的 Skill 格式。但 Skills 也有明确的边界。第一它不擅长做“一次性的、没有明确规则”的探索性任务因为技能包本质上是把“已知的做事方法”固化下来。第二它不能完全替代代码库里的自动化流水线Skill 里的脚本通常比较轻量重计算、高并发的任务应该交给专业工程系统。第三Skill 的加载依赖 LLM 的判断偶尔会出现该触发时没触发、或者触发后输出不稳定的情况需要你在description里写清楚触发条件。第四合规方面要特别提醒如果 Skill 会处理人脸图片、人物声音、版权文本或内部敏感数据你必须确认素材来源合法、已获授权并在本地或受控环境中运行不能把未授权数据随意交给云端 API 处理。3. 环境准备与前置条件使用 Anthropic Skills 不需要 GPU也不需要特殊显卡核心依赖是 Anthropic 的 API 或 Claude Code 环境。下面是推荐的前置条件清单。操作系统Windows / macOS / Linux 均可Claude Code 官方支持主流平台 Node.js建议安装 LTS 版本用于运行 Claude Code 和部分 Skill 脚本 Python建议 3.10很多 Skill 的资源脚本用 Python 编写 Anthropic API Key用于 Claude API 或 Claude Code 登录 Claude Code安装并登录后会自动识别 skills 目录 网络需要能访问 Anthropic 服务按实际网络环境确认 磁盘空间Skill 文件一般只有几 KB 到几十 MB基本不需要额外预留大空间3.1 安装 Claude CodeClaude Code 是 Anthropic 官方的命令行编程助手也是运行 Skills 最直接的环境。安装方式很简单在终端执行npm install -g anthropic-ai/claude-code安装完成后先登录claude首次启动会引导你登录 Anthropic 账号并绑定 API Key。如果终端提示命令不存在通常是 Node.js 版本过低或 npm 全局目录不在 PATH 里升级 Node.js LTS 后重新安装即可。3.2 确认 Skills 目录Claude Code 会在项目或用户目录下自动查找技能文件夹。默认的全局 Skills 目录通常位于~/.claude/skills项目级 Skills 目录通常位于项目根目录下的.claude/skills如果你使用的是 Claude Agent SDK还可以在代码里动态注册 Skill 目录。具体目录路径可能会随 Claude Code 版本更新而调整以你本机claude --version显示的版本文档为准。最稳妥的验证方法是启动 Claude Code 后输入/help查看是否出现 Skills 相关选项。4. 安装部署与启动方式4.1 手动创建第一个 SkillSkills 的目录结构非常简单官方标准如下my-skill/ ├── SKILL.md └── resources/ ├── template.md └── script.py其中SKILL.md是技能的核心文件使用 Markdown 编写头部必须包含 YAML frontmatter至少声明name和description。description非常关键因为模型就是通过它来判断何时加载这个技能。下面是一个最简单的SKILL.md示例--- name: weekly-report description: 根据本周工作记录生成结构化周报适用于周报、月报、项目进展同步场景。当用户要求写周报或整理项目进展时使用。 --- # Weekly Report Skill 按照以下步骤生成周报 1. 阅读用户提供的工作记录或 git 提交记录。 2. 按「本周完成 / 下周计划 / 风险与问题」三个部分组织内容。 3. 每条内容控制在 50 字以内使用项目名称加结果描述的形式。 4. 输出 Markdown 格式标题为「项目周报 - 第X周」。把上面内容保存到~/.claude/skills/weekly-report/SKILL.md然后启动 Claude Code这个技能就会自动出现在可用技能列表里。4.2 安装社区 Skill社区里已经有不少现成的 Skill 合集和独立 Skill最典型的是superpowers它是一套 Claude Code Skills 插件集包含大量可用于编码、研究、内容创作的子技能。安装方式通常是直接把仓库克隆到 skills 目录或者通过 Claude Code 的安装命令加载。以通用安装流程为例# 将技能仓库克隆到 Claude Code 的 skills 目录 cd ~/.claude/skills git clone https://github.com/your-chosen-skill-repo.git不同项目的安装方式不完全一致有的会提供install.sh有的要求解压到指定目录。建议先看目标仓库的 README再决定是手动复制还是用安装脚本。像opencode skills、mattpocock skills这类社区项目大多遵循同一套SKILL.md格式所以安装原理是一样的。4.3 在 Claude Code 中启动一切就绪后在终端输入claude进入交互界面后你可以直接输入一段自然语言请求比如“帮我把这个项目的 commit 记录生成一份周报”。如果 Claude Code 正确加载了weekly-reportSkill它会在处理过程中自动参考技能内容并按你设定的格式输出。如果希望更加可控也可以在对话中显式指定技能例如请使用 weekly-report 技能整理本目录下的工作记录。Claude Code 会结合技能说明、当前对话上下文和工具调用能力来完成任务。5. 功能测试与效果验证安装 Skill 不等于技能已经生效关键要看模型是否真的在正确时机加载了它并且输出了符合预期的结果。下面给出一套可复用的验证流程。5.1 验证 Skill 是否被识别启动 Claude Code 后在交互界面输入你有什么技能列出现有的技能清单。如果安装成功你会看到技能名如weekly-report出现在回复中。如果技能名没有出现优先检查目录位置是否在 Claude Code 的搜索范围内以及SKILL.md的 frontmatter 是否完整。frontmatter 解析失败是技能无法被识别的最常见原因。5.2 验证 Skill 是否被自动触发用一段故意“贴近技能描述”但说法不同的请求来测试。例如技能描述里写的是“写周报”你可以问这周我做完了登录模块重构、性能优化和两个 bug 修复下周打算做订单导出和告警监控帮我生成一份项目进展同步文档。观察两个点模型是否“主动”按照SKILL.md里定义的结构输出本周完成 / 下周计划 / 风险与问题。输出中是否包含技能文件中的特殊要求比如“每条内容控制在 50 字以内”。只要这两点成立说明 Skill 已经被模型自动加载。如果模型输出了通用回复没有按照技能结构组织内容可能是description写得太窄导致模型没有把当前任务关联到技能。优化方向是扩大description的触发场景并增加更明确的关键词。5.3 验证 Skill 内脚本是否执行成功技能包的价值不仅在于“提示词模板”更在于可以携带可执行脚本。假设我们在weekly-reportSkill 里放了一个collect_git_log.py用来抓取 git 提交记录import subprocess import json def main(): result subprocess.run( [git, log, --oneline, -10], capture_outputTrue, textTrue ) print(result.stdout) if __name__ __main__: main()在有 git 仓库的目录下启动 Claude Code然后输入“使用 weekly-report 技能收集最近的 git 提交并生成周报”。如果技能正常执行模型会先调用 Python 脚本收集提交记录再基于脚本输出生成周报。这个过程中你可以直接在终端看到工具调用日志确认脚本运行成功。如果脚本报错排查依赖环境Python 版本、模块缺失或脚本路径是否写在了SKILL.md中。5.4 失败判定与降级策略一个常见的误区是只要模型回复了内容就觉得 Skill 生效了。实际上有几种情况需要警惕现象可能原因处理方式回复内容与技能结构完全无关技能未被加载检查目录和 frontmatter回复内容部分符合技能结构技能被加载但未严格遵循在SKILL.md中增加强制输出格式技能加载后脚本报错脚本路径或依赖问题查看日志手动运行脚本验证输入请求直接要求“用某技能”显式触发成功属于正常现象可以继续观察结果做功能测试时建议准备一组固定测试用例每次改动技能后都跑一遍避免凭感觉判断。测试用例应该包含正常输入、边界输入如空提交、以及与技能无关的干扰请求模型应当忽略该技能。6. 接口 API 与批量任务6.1 Claude Agent SDK 中加载 SkillClaude Code 是 Skills 最常见的运行环境但如果你在自己的应用里接入 Claude Agent SDK同样可以使用 Skills。SDK 通常允许在创建 Agent 时指定技能目录实际参数名以官方文档为准这里给一个通用示意from claude_agent_sdk import Agent agent Agent( api_keyyour-api-key, skills_paths[~/.claude/skills/weekly-report] ) response agent.run(生成本周项目周报) print(response.text)从设计上看Skills 与 Agent SDK 是天然搭配的Agent 负责拆解任务、调用工具Skill 负责提供特定领域的操作手册和脚本。团队开发时可以把技能包作为独立目录提交到代码仓库新成员 clone 后即可获得同一套技能。如果你对接的是原生 Anthropic API 而不是 Agent SDK那么更常见的做法是在 system prompt 中指定技能内容或者让应用先根据任务描述选取技能文件再把技能内容注入 prompt。这种方式的优点是完全可控缺点是失去了“模型自动判断是否加载”的能力需要自己在代码里实现技能路由。6.2 API 调用示例通用模板如果你希望把 Skill 内容注入到 API 请求中可以参考下面这个模板。它不是一个官方 SDK 的固定用法而是通用的“把技能文件读入 system prompt”示例import anthropic client anthropic.Anthropic(api_keyyour-api-key) with open(./skills/weekly-report/SKILL.md, r, encodingutf-8) as f: skill_content f.read() response client.messages.create( modelclaude-sonnet-4-5, max_tokens2000, systemf你是一个擅长生成周报的助手。请严格遵循以下技能说明\n\n{skill_content}, messages[ {role: user, content: 本周完成了登录重构和性能优化下周计划做订单导出请生成周报。} ] ) print(response.content[0].text)这种方式适合把 Skill 接入自定义业务系统、自动化流程或批处理脚本。核心思路是先把技能文件读取出来再把它放到 system prompt 里让模型严格按照技能逻辑执行。优点是不依赖 Claude Code 环境完全在自己的应用里闭环。6.3 批量任务设计Skills 很适合批量任务尤其是“同一套流程、大量不同输入”的场景。比如你有 50 篇技术文章想用统一结构生成摘要并输出 JSON可以设计一个article-summarizerSkill然后在 Python 脚本里循环调用import os import json import anthropic client anthropic.Anthropic(api_keyyour-api-key) def summarize_article(file_path: str) - dict: with open(file_path, r, encodingutf-8) as f: content f.read() # 读取技能文件 with open(./skills/article-summarizer/SKILL.md, r, encodingutf-8) as f: skill f.read() response client.messages.create( modelclaude-sonnet-4-5, max_tokens1000, systemf严格遵循以下技能说明处理任务\n\n{skill}, messages[{role: user, content: content}] ) return {file: os.path.basename(file_path), summary: response.content[0].text} # 批量处理 input 目录下的所有 .md 文件 input_dir ./articles results [] for filename in os.listdir(input_dir): if filename.endswith(.md): results.append(summarize_article(os.path.join(input_dir, filename))) with open(./outputs/summaries.json, w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2) print(批量处理完成共生成, len(results), 条结果)批量任务的关键是做好三件事一是输入输出目录分离不要在工作目录里混放中间文件二是为每一条任务增加日志方便在大量处理时定位失败项三是设置重试机制例如 API 返回超时或限流时等待后重试。如果你做的事情涉及批量识别图片、处理音视频、生成图表等同样可以在 Skill 里放对应的脚本让模型负责编排、脚本负责具体执行。前提是素材来源合规尤其不要批量处理未经授权的人脸照片、声音样本或受版权保护的文档。7. 资源占用与性能观察Skills 本身几乎不消耗 GPU 和系统内存因为它本质上是文本文件加轻量脚本。真正需要观察的性能指标有三个上下文长度、Token 消耗、API 响应时间。Skill 的核心文件SKILL.md写得越长模型每次加载技能时消耗的上下文就越多。几十行说明通常没问题但如果一个技能里塞了几百行参考资料即便不是每次任务都会用到也会显著占用上下文窗口。建议把真正需要模型“每次阅读”的内容放在SKILL.md正文里把大型参考资料放在resources目录中由模型按需读取。这样既能保证技能功能完整又能控制 Token 成本。观察 Token 消耗的方法有两种。第一种是在 Claude Code 中使用详细输出模式查看每次请求的 token 统计第二种是在 API 调用的返回结果里读取usage字段print(response.usage){ input_tokens: 1240, output_tokens: 520 }从实践中看技能文件本身带来的增量通常只在几百 token 量级但如果你在批量任务中反复调用同一个技能这部分开销会线性累积。因此批量任务建议复用同一个初始化的system内容而不是每次请求都重新读取技能文件。响应时间方面加载额外的技能文件会略微增加首 token 延时但影响通常不明显。更大的性能瓶颈出现在技能包含大量工具脚本、或者模型为了完成技能而连续调用多次脚本时。优化思路是让脚本尽量“一次调用输出完整结果”减少模型与工具之间的频繁往返。8. 常见问题与排查方法这里整理一份 Skills 使用过程中的高频问题排查表建议直接收藏。问题现象可能原因排查方式解决方案技能没有被模型识别Skills 目录不在默认搜索范围检查 skills 目录位置放到~/.claude/skills或项目.claude/skillsSKILL.md 无法解析frontmatter 格式错误打开文件检查 YAML 格式确认name和description完整缩进正确技能能识别但模型不自动触发description 太窄或描述不清测试不同表述的请求扩展触发场景加入关键词说明技能触发后输出不符合预期步骤太抽象模型自由发挥空间大检查 SKILL.md 步骤是否可执行增加强制格式、示例、检查清单技能脚本报错Python/Node 依赖缺失或路径问题在终端手动运行脚本安装依赖修正脚本路径Claude Code 命令找不到Node.js 版本问题或 npm 目录不在 PATH运行node -v和npm -v升级 Node.js LTS重新全局安装API 调用返回超时技能内容太长或模型推理步骤多查看 usage 和响应时间精简技能文件减少不必要轮次批量任务部分失败网络波动或 API 限流查看日志中的错误码增加重试和失败记录机制技能加载后上下文占用过高SKILL.md 塞入过多内容观察每次请求的 input_tokens把大内容移到 resources 中按需读取出现问题时最有效的定位方式不是反复试 prompt而是先确认“技能文件是否被加载了”。Claude Code 的详细输出模式会显示模型是否读取了某个 Skill 文件你把日志打开一眼就能看出是加载失败、触发失败还是执行失败然后按对应方向排查。9. 最佳实践与使用建议通过社区热词和实际使用经验可以沉淀出下面这些 Skills 开发与使用的最佳实践。第一description是技能的灵魂。它决定了模型在什么场景下会想到加载这个技能。建议在 description 里写清楚“做什么”和“什么时候用”例如“在用户提供 git 日志并要求生成周报时使用”。避免写过于宽泛的描述否则模型会在很多无关任务里错误触发。第二保持技能轻量。一个技能原则上只解决一类问题。如果你发现自己在一个SKILL.md里写了好几个互不相关的小功能建议拆成多个技能让模型在合适时机精确加载。第三把静态参考放进 resources。比如代码风格规范、PDF 模板、数据字典这类不要求模型“每次必读”的内容放在 resources 目录中。模型需要时会主动读取不需要时不会浪费上下文。第四用版本管理保存技能。把技能目录放到 Git 仓库里每次修改都能看到变更记录。团队协作时一个共享技能仓库可以让所有成员使用同一套工作流标准。第五批处理必须留日志。无论是批量跑文档、批量生成图片描述还是批量处理测试用例都要在输出目录里同时写一个result.log记录每条任务的输入文件、状态、耗时和错误信息。这样即使跑了几百条任务也能快速定位哪条失败、为什么失败。第六涉及人脸、声音、版权素材或公司内部敏感信息时一定先确认授权边界。Skill 只是工具它不能替代你对数据合规的判断。如果数据不能发送到云端处理就不要把相关技能配置为调用云端 API如果有本地模型可用可以考虑把本地方案接进技能脚本。一旦出现违规使用责任在使用者不在技能框架。10. 总结与下一步Anthropic Skills 的价值不在于它提供了多少现成功能而在于它定义了一种让模型按固定流程执行任务的标准化方法。你不需要再每次对话时把几十行提示词复制来复制去也不需要担心不同场景下模型输出风格飘忽不定。把流程写成SKILL.md放好资源文件模型就会在你需要的时候自动按套路办事。对于已经有 Claude Code 使用经验的人来说这是最值得立刻上手的进阶能力。如果你想验证这套机制我建议先做三件事第一手动创建上面那个weekly-report技能用 git 提交记录测试一次完整流程第二打开社区里的技能包仓库比如superpowers安装一个你实际用得上的技能感受一下现成技能包的结构第三把你日常重复度最高的那个工作流写成一个最小 Skill跑通之后再逐步丰富。最容易踩的坑是description写得不精确导致模型该触发时不触发解决方法是多测试几种问法持续调整描述。后续可以扩展的方向也很多把多个技能组合成一个完整工作流在 Agent SDK 里用代码管理技能加载或者做一个团队内部的技能仓库把项目规范、代码审查要点、发布检查清单全部固化下来。这个框架一旦跑顺你的 Claude 将从“对话助手”真正变成“能按手册干活的执行者”。建议先把今天这篇文章里的基础示例跑通再逐步扩展你的技能库。