1. 从 Plugin 到 Agent Skills为什么值得折腾这一趟如果你最近在 Claude Code 里写过 Plugin大概率会有一种感觉能跑但不够“稳”。Plugin 更像是一个挂在编辑器边上的外挂命令集合触发靠人记、参数靠人填、流程靠人串。而 Agent Skills 想解决的是另一件事——把“这类任务该怎么做”写成模型自己能读懂、能判断、能按步骤执行的技能包。它不是一个新名词而是大模型能力从“会聊天”走向“会干活”的系统化封装。Agent Skills 是什么简单说它是以文件夹为单位的技能单元核心是SKILL.md里面用 YAML frontmatter 描述技能名称、适用场景、允许调用的工具下面用 Markdown 写清楚执行流程和约束。模型在任务初始化时只加载每个技能的名称和描述判断相关后才把完整SKILL.md读进上下文执行阶段再按需加载脚本或素材。这套“渐进式披露”机制让上下文不被一次性塞爆也让技能调用比纯 Prompt 更可控。它适合谁适合已经在用 Claude Code 写代码、跑 Agent 流程但被 Plugin 的触发不稳定、参数散落、复用困难折磨过的开发者。这篇不聊概念演进史直接交付可复制的SKILL.md模板、目录结构、加载验证步骤以及从 Plugin 迁移到 Agent Skills 时最容易踩的坑。你跟着做能在一个下午把第一个可用 Skill 跑通。2. 前置准备TaoToken 接入与 Claude Code 环境Claude Code 本身是终端里的编码 Agent要让它稳定跑起来需要一个可用的模型 API 入口。我这边用的是 TaoToken 做统一接入好处是模型对话、API Key 管理、Coding Plan 都在一个控制台里不用在多个平台之间来回切配置。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时别多贴。第一步去控制台创建 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后在 API Keys 页面新建一个 Key复制出来先存到本地环境变量里。如果你还没决定用哪个模型可以先去模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 试一下不同模型的响应风格再决定 Skill 里默认写哪个模型。第二步配置 Claude Code 的环境变量。在~/.zshrc或~/.bashrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你刚才复制的Key保存后执行source ~/.zshrc再在终端输入claude能正常进入交互界面就说明接入通了。如果你打算长期跑编码任务或 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 遇到环境变量不生效、返回 401 之类的问题先翻文档里的排障章节。3. 可复制配置SKILL.md 骨架与目录结构Agent Skills 的目录结构不复杂但每个位置放什么有讲究。一个最小可用 Skill 长这样.claude/skills/ └── article-polish/ ├── SKILL.md ├── scripts/ │ └── check_length.py ├── assets/ │ └── style-guide.md └── examples/ └── before-after.mdSKILL.md是必须的其余三个目录按需添加。scripts/放执行时可能调用的脚本assets/放模板或配置examples/放背景知识和示例。下面是一个可直接复制的SKILL.md模板我拿“文章润色”这个场景做例子--- name: article-polish description: 当用户要求润色、改写或优化中文技术文章时使用。适用于段落重组、语气调整、术语统一不适用于从零撰写新文章。 allowed-tools: - Read - Write - Bash model: claude-sonnet context: subagent --- # 文章润色技能 ## 触发条件 用户输入包含“润色”“改写”“优化表达”“调整语气”等意图且提供了待处理文本或文件路径。 ## 执行流程 1. 读取目标文件或用户粘贴的文本确认字数与段落数。 2. 检查是否提供了风格指南assets/style-guide.md有则按指南执行。 3. 逐段处理保留原意调整句式统一术语删除冗余副词。 4. 运行 scripts/check_length.py 校验改写后字数变化不超过原字数 15%。 5. 输出改写结果并附一段简短说明列出主要修改点。 ## 约束 - 不改变原文的技术事实和代码片段。 - 不添加原文没有的观点。 - 遇到不确定的术语保留原词并在说明中标注。frontmatter 里的字段不是全部必填但name和description是必要的。description写得越具体模型判断“这个任务该不该触发这个 Skill”就越准。allowed-tools限制这个 Skill 能自动调用哪些工具避免它越权去跑不该跑的命令。context: subagent表示在独立子 Agent 上下文里运行适合流程较长的技能。如果你是从 Plugin 迁移过来原来的 Plugin 命令逻辑可以拆成两部分触发判断写进description执行步骤写进 Markdown 正文。Plugin 里硬编码的参数改成在SKILL.md里声明输入形式让模型根据用户输入动态填充。4. 加载与验证让 Skill 真正生效文件写好了不代表生效。Claude Code 加载 Skill 的路径默认是项目根目录下的.claude/skills/如果你放在用户级目录则是~/.claude/skills/。放好之后重启 Claude Code 会话输入/skills或直接问“当前有哪些可用技能”看它能不能列出你刚建的article-polish。验证分三步。第一步确认加载在 Claude Code 里输入“列出当前可用的 Skills”正常会返回技能名称和描述列表。如果没出现检查目录层级是不是多了一层比如.claude/skills/article-polish/SKILL.md是对的.claude/skills/SKILL.md就错了。第二步触发测试粘贴一段需要润色的文字前面加上“帮我润色这段”。观察 Claude Code 是否弹出提示询问是否启用article-polish技能。如果它直接开始改而不询问说明description写得不够有区分度模型没把它当成一个独立技能来匹配。第三步执行验证确认启用后看它是否按SKILL.md里的流程走——先读文件、再检查风格指南、再逐段处理、最后跑脚本校验。我试过在scripts/check_length.py里故意写一个会报错的逻辑结果 Skill 执行到那一步时确实停下来报错了说明脚本调用链是通的。一个成功的返回结果大概长这样[Skill: article-polish] 已加载风格指南 assets/style-guide.md [Skill: article-polish] 处理段落 1/6 ... 完成 [Skill: article-polish] 运行 scripts/check_length.py 字数变化原 1240 字 → 改后 1187 字变化 4.3%通过校验 [Skill: article-polish] 输出改写结果看到这种分步输出说明 Skill 不是被当成一段普通 Prompt 塞进去的而是真的按技能流程在执行。5. 本篇常见错排查错误一Skill 不触发模型直接回答。最常见的原因是description写得太泛比如只写“用于处理文章”。模型无法判断什么时候该用它。改成“当用户要求润色、改写或优化中文技术文章时使用不适用于从零撰写新文章”触发率会明显上升。错误二SKILL.md解析失败frontmatter 报错。YAML 对缩进和冒号后面的空格很敏感。name: article-polish冒号后必须有一个空格allowed-tools下面的列表项要用两个空格缩进加短横线。如果你从网页复制模板注意别把全角冒号带进去。错误三脚本调用被拒绝。如果allowed-tools里没写BashSkill 执行到运行脚本那一步会被拦下来。检查 frontmatter 里的工具列表需要什么加什么但别图省事把全部工具都开上权限收窄一点更安全。错误四从 Plugin 迁移后参数丢失。Plugin 时代你可能在命令里写死了文件路径或模型名迁移到 Skill 后这些应该变成动态输入。如果 Skill 执行时提示“缺少必要参数”回到SKILL.md正文里把输入形式写清楚比如“用户需提供待处理文件路径或直接粘贴文本”。错误五多个 Skill 同时触发流程打架。如果你装了润色 Skill 又装了翻译 Skill用户说“把这段英文润色一下并翻译成中文”两个 Skill 可能都想接管。解决办法是在description里划清边界润色 Skill 写明“仅处理中文文本”翻译 Skill 写明“仅处理跨语言转换”。遇到接入层面的报错比如 API 返回 401 或模型不可用先去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认 Key 状态再对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 检查环境变量。如果是 Claude Code 本身的 Skill 加载问题检查目录权限和文件编码SKILL.md用 UTF-8 保存别用 GBK。6. 迁移路径与长期维护建议从 Plugin 到 Agent Skills 的迁移本质上不是换一套 API而是换一种组织任务知识的方式。Plugin 把逻辑写在代码里Agent Skills 把逻辑写在模型能读的文档里。这意味着你的SKILL.md本身就是一个需要维护的“活文档”——任务流程变了改 Markdown 就行不用重新编译打包。如果你手上已经有几个跑得不错的 Plugin迁移时可以按这个顺序来先挑一个触发条件最明确、步骤最固定的 Plugin把它的判断逻辑提炼成description把执行步骤拆成编号列表写进正文把硬编码参数改成动态输入。跑通一个之后剩下的就是复制目录结构、替换内容。长期来看建议把 Skill 当成项目资产来管理。.claude/skills/目录跟着代码仓库走团队成员拉下来就能用同一套技能。examples/里放一些典型输入输出对照新成员看一遍就知道这个 Skill 大概干什么。scripts/里的脚本加上注释和错误处理别让一个脚本报错把整个 Skill 流程卡死。如果你还在选模型或调 API 参数阶段可以先去模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 对比一下不同模型在长流程任务里的表现再决定SKILL.md里默认写哪个。需要长期跑编码 Agent 的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 比按次调用更适合高频场景。ClaudeCodeAnthropic 相关配置可以参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 里面有针对 Claude Code 的接入说明。最后说一个我踩过的坑别在SKILL.md里写太长的背景介绍。模型加载技能时读的是执行指令不是科普文章。把“为什么这么做”压缩到一两句把“怎么做”写清楚技能的执行稳定性会高很多。