1. 从零散笔记到可复用技能库我踩过的坑Agent Skills 是 Anthropic 推出的模块化指令标准用 SKILL.md 描述任务流程让 Claude 这类智能体按固定规范执行重复工作。它适合谁适合那些每周都在重复同一套提示词、每次都要重新解释工作流、被上下文窗口反复折磨的开发者。我学完吴恩达那门 DeepLearning.AI 与 Anthropic 合作的 Agent Skills 课程后最大的感受不是“技能很强大”而是“我之前那些散落在 Notion、备忘录、聊天记录里的提示词终于有地方安放了”。课程里 Elie Schoppik 讲得很清楚Skills 本质是一个文件夹核心是 SKILL.md里面用 YAML 前置元数据声明 name 和 description正文写任务流程、输入输出格式、公式示例。智能体启动时只加载元数据名称描述当用户请求匹配到描述时才加载完整指令需要脚本或模板时再按需读取资源文件——这就是渐进式披露。它解决的核心痛点是通用大模型没有领域知识、复杂任务容易偏离、长上下文容易迷失。把反复要解释的工作流打包成技能智能体自动知道该做什么。但光有 Skills 还不够。Skills 负责“怎么做”MCP 负责“从哪拿数据”。Skills MCP 的组合才是完整闭环MCP 从外部数据源拉取数据Skills 定义处理这些数据的标准流程。这篇笔记就是把我学完课程后自己动手搭建技能库的完整路径复盘出来包含可复制的 SKILL.md 骨架、MCP 配置片段、在 Claude 中加载验证的具体步骤以及我踩过的那些坑。2. 前置准备TaoToken 接入与 Skills 运行环境在开始写 SKILL.md 之前得先把运行环境跑通。Skills 要能执行智能体需要两样底层能力文件系统访问读写文件和 Bash 工具执行代码。Claude Desktop 和 Claude Code 内置了这些能力但如果你是通过 API 自研应用就需要自己提供代码执行沙箱。我自己的做法是用 TaoToken 作为统一接入层。它兼容 Anthropic 的 API 协议模型对话、Coding Plan、API Keys 管理都在一个控制台里完成省去了单独维护多个密钥的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。具体操作分三步。第一步在控制台创建 API Key地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。第二步如果你要跑 Claude Code 做长期编码任务建议开通 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它按周期计费比按 token 计费更适合高频编码场景。第三步把 API Key 配置到环境变量里export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的Key如果你用的是 Claude Code还需要在~/.claude/settings.json里确认 base URL 指向正确。配置完成后可以用一个最小请求验证连通性curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5-20250929, max_tokens: 128, messages: [{role: user, content: 回复 OK}] }返回里有content字段且文本为 OK说明接入层通了。这一步看起来简单但后面 Skills 加载失败时先回来确认这层是通的能省很多排查时间。3. 可复制的 SKILL.md 骨架与 MCP 配置片段3.1 SKILL.md 最小可用骨架课程里反复强调name 最多 64 字符只能小写字母、数字和连字符不能以连字符开头或结尾必须与父目录名匹配建议用动名词形式。description 最多 1024 字符要写清楚“做什么”和“什么时候用”包含帮助智能体识别任务的关键词。下面是我自己用的骨架你可以直接复制改--- name: analyzing-marketing-campaign description: 分析多渠道数字营销数据计算转化漏斗、效率指标并给出预算调整建议。当用户提供包含 Date、Campaign_Name、Channel、Impressions、Clicks、Conversions、Spend、Revenue 字段的 Excel 或 CSV 文件并要求做渠道效果分析或预算优化时使用。 inputs: - file: Excel/CSV包含 Date, Campaign_Name, Channel, Impressions, Clicks, Conversions, Spend, Revenue, Orders 等字段 outputs: - Markdown/Excel 表格含各项指标与建议 version: 1.0.0 --- ## 任务流程 1. 读取 Excel/CSV 数据校验字段完整性。 2. 计算各渠道 CTR点击率、CVR转化率。 3. 计算 ROAS广告回报率、CPA获客成本、净利润等效率指标。 4. 输出对比表格生成分析解读与预算建议。 ## 公式示例 - CTR% Clicks / Impressions * 100 - CVR% Conversions / Clicks * 100 - ROAS Revenue / Spend - CPA Spend / Conversions - Net Profit Revenue - (Spend 其它成本) ## 输出格式 | 渠道 | 展示量 | 点击量 | 转化率 | ROAS | CPA | |------|--------|--------|--------|------|-----| | SEO | | | | | | ## 预算重新分配 基于 ROAS 优化分配策略ROAS 低于 1.5 的渠道建议缩减预算。正文控制在 500 行以内复杂内容拆到外部文件。资源引用只允许一级目录禁止多层嵌套。可选目录有三个/scripts放运行脚本/references放参考文档/assets放模板和静态资源。脚本要写清楚依赖项和错误处理并在说明中明确 Claude 是执行脚本还是仅作为参考阅读。3.2 MCP 配置片段MCP 是模型上下文协议本质是一个安全的远程能力网关。它独立部署在远程服务器接收智能体的标准化请求按预设权限代理访问外部资源再把结果按协议格式返回。它不会把数据库账号密码暴露给智能体只开放你预先配置好的有限权限。在 Claude Desktop 中配置 MCP 服务编辑claude_desktop_config.json{ mcpServers: { notion: { command: npx, args: [-y, notionhq/notion-mcp-server], env: { NOTION_API_KEY: 你的Notion集成密钥 } }, filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/yourname/skills-workspace] } } }配置完成后重启 Claude Desktop在对话中如果 MCP 服务加载成功工具列表里会出现对应的工具名。这里有个关键点MCP 只负责“拿数据”Skills 负责“处理数据”。比如你用 Notion MCP 拉取会议纪要然后用一个自定义的“周报生成”Skill 来整理成标准格式两者配合才是完整工作流。4. 在 Claude 中加载验证与成功结果4.1 目录结构Skills 必须是一个完整文件夹不能只放单个文件。以营销分析技能为例analyzing-marketing-campaign/ ├── SKILL.md ├── scripts/ │ ├── process_data.py │ └── recalc.py └── references/ ├── example_input.xlsx ├── output_template.xlsx └── budget_relocation_rules.mdWindows 下技能目录必须是%APPDATA%\Anthropic\Claude\skillsmacOS 下是~/Library/Application Support/Claude/skills。放错位置是新手最常见的失败原因。4.2 开启 Skill Creator 开关打开 Claude Desktop进入 Settings → Capabilities开启 Skill Creator。不开这个开关本地 Skill 完全无法加载。开启后 Claude 才会监听指定目录、加载自定义 Skill、识别文件修改并实时更新。4.3 验证加载重启客户端后在对话中输入/skills查看已启用技能。如果列表里出现了你的技能名称说明加载成功。然后输入一个最小样例测试请用 analyzing-marketing-campaign 技能分析这份数据如果 Claude 回复中引用了技能里的公式和输出格式说明技能被正确触发。如果没触发先检查 description 是否包含了用户可能用的关键词。4.4 用 API 方式验证如果你是通过 API 调用需要用到代码执行工具和 Files API。代码执行工具让 Claude 在沙箱中运行 Bash 命令、读写文件沙箱没有互联网连接但预装了常用库。Files API 负责把本地文件上传到沙箱再把生成的文件传回来。from dotenv import load_dotenv import anthropic from anthropic.lib import files_from_dir _ load_dotenv() client anthropic.Anthropic() # 上传自定义技能 skill client.beta.skills.create( display_titlePractice Question Generator, filesfiles_from_dir(./custom_skills/generating-practice-questions), betas[skills-2025-10-02] ) print(fSkill ID: {skill.id}) # 上传要处理的讲义文件 file_object client.beta.files.upload( fileopen(./lecture_notes/notes04.tex, rb), ) # 发送请求执行技能 response client.beta.messages.create( modelclaude-sonnet-4-5-20250929, max_tokens4096, betas[code-execution-2025-08-25, skills-2025-10-02, files-api-2025-04-14], container{ skills: [{ type: custom, skill_id: skill.id, version: latest }] }, messages[{ role: user, content: [ {type: text, text: Generate practice questions in Markdown format from these lecture notes}, {type: container_upload, file_id: file_object.id} ] }], tools[{ type: code_execution_20250825, name: code_execution }] )三个 beta 头缺一不可code-execution-2025-08-25开启代码执行工具skills-2025-10-02开启技能系统files-api-2025-04-14开启文件上传下载。少任何一个都会报错。5. 本篇常见错误排查5.1 技能不触发最常见的原因是 description 写得太模糊。比如只写“分析数据”用户说“帮我看看这份表格”时可能匹配不上。改成“分析多渠道数字营销数据计算转化漏斗和效率指标”就具体多了。另一个原因是 name 与父目录名不匹配Claude 会直接忽略。5.2 脚本执行报错如果 SKILL.md 里引用了/scripts/process_data.py但脚本缺少依赖或没有异常处理Claude 执行时会中断。建议在脚本开头加依赖检查并在 SKILL.md 中明确写“执行该脚本”还是“阅读该脚本作为参考”。课程里特别提到openpyxl 只写入公式字符串不计算结果涉及公式重算需要用单独的 recalc.py 脚本处理。5.3 MCP 连接失败先确认 MCP 服务的 command 和 args 路径正确。npx方式需要本地有 Node.js 环境。如果 MCP 服务需要 API Key确认环境变量已传入。另外注意MCP 是远程能力网关如果只是读写本地文件用内置的文件系统工具就够了不需要额外配 MCP。5.4 上下文被占满Skills 的渐进式披露就是为了解决这个问题。但如果你的 SKILL.md 正文超过 500 行或者 references 里的文件没有目录Claude 加载时仍然会占用大量上下文。建议把长参考文档拆分超过 100 行的文件在顶部加内容目录。运行/context可以查看当前上下文占用情况。5.5 API 调用返回权限错误检查 beta 头是否齐全以及 API Key 是否有权限访问 skills 接口。如果你用的是 TaoToken 的接入层确认 Key 是在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建的并且账户余额充足。6. 把技能库用起来从单技能到组合工作流单个 Skill 能解决重复提示词的问题但真正的效率提升来自组合。课程里讲了两种组合方式Skills MCP 用于“MCP 拿数据、Skill 处理数据”Skills 子智能体用于“主智能体编排、子智能体执行”。我自己的做法是先跑通单技能确认加载和触发都正常再逐步加入 MCP 数据源。如果你主要做模型对话和技能验证可以在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接测试不同模型对同一 Skill 的触发效果。如果你要长期做编码和 Agent 开发Coding Plan 的入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的 API 参数说明和示例代码。最后说一个我踩过的坑Skills 不互通。你在 Claude Desktop 里创建的 Skill 不会自动同步到 Claude Code 或 API 环境。我的做法是把所有 Skill 文件夹放在一个 git 仓库里不同环境通过软链接或直接 clone 来部署。这样改一处所有环境都能拉到最新版本。技能库的价值不在于数量多而在于每个技能都经过验证、能稳定触发、输出格式一致。先把一个技能打磨到“每次都能按预期工作”再复制这个模式去扩展比一次性写十个半成品要靠谱得多。
