最近在给团队搭 Agent 工作流绕不开一个词Skills。无论你用的是 Claude Code还是各种支持 Agent 的编码工具Skills 都是把“模型会聊天”变成“模型会干活”的核心机制。很多朋友问我网上一堆“Skills 使用教程”要么只讲概念要么只给几个命令真正能从导入到评分讲完整的很少。这篇就是一次完整的实操记录我会从什么是 Skills 讲起给出一套标准技能包结构再用实际命令演示导入、触发和调用最后给出一个我自己常用的评分框架帮你判断一个技能到底值不值得留下来什么时候该删。对于刚接触的人这篇文章可以帮你建立完整的技能生命周期概念对于已经在写技能的人后半段的评分维度和避坑清单应该能让你少走不少弯路。1. Skills 到底是什么从一段工作流说起1.1 一个让我决定研究 Skills 的场景上周接了一个技术方案梳理的活客户丢过来一个老项目的源码要求我在半天内给出模块拆解、风险点和重构建议。这种活我以前的做法是开一个对话窗口贴上一堆文件路径然后不停地下指令“先看看这个目录”、“再读一下这个配置”、“能不能把依赖关系画出来”。结果就是上下文很快被各种碎片信息塞满模型经常做着做着就忘了前面看过什么要反复重复同一类问题。后来我换了一种方式提前写好一个“项目分析技能包”让模型按照固定流程走——先读 README 和项目配置再分析目录结构然后扫描核心模块的入口和依赖最后输出一份固定格式的报告。整个过程只花了一轮对话输出质量却稳定得多。这件事让我彻底明白Skills 的本质就是把“你希望 AI 怎么干活”这件事从临时口头指令变成可复用、可版本化、可分享的结构化配置。1.2 Skills 和 Prompt、MCP 的边界在哪很多人会把 Skills 和 Prompt、MCP 混在一起我一个个说清楚。Prompt 是口头交代你每次对话都要重新说一遍适合一次性任务。MCPModel Context Protocol是给模型接外部工具和数据的标准协议相当于给 AI 配了手和眼睛。Skills 则是介于两者之间的一套行为模板它告诉模型“遇到这类任务时按这个流程走用这些规则判断最后输出这种格式”。你可以这样理解Prompt 是任务描述MCP 是工具箱Skills 是老师傅写给新人的操作手册。操作手册里可以引用工具箱里的工具也可以包含具体的话术模板但它的核心价值是一致性和可复用性。好的 Skills 会让同一个任务在一百次执行中得到高度相似的结果这是单纯靠 Prompt 很难做到的。2. 动手之前先搞懂一个 Skill 的标准结构2.1 SKILL.md 就是那本操作手册不管哪种 Agent 实现目前主流技能格式基本都以 SKILL.md 文件为核心。这个文件可以放在项目目录下也可以放在 Agent 的全局技能目录里。它的作用就是让模型在读取技能时能快速知道三件事这个技能是干什么的、什么情况下触发、具体怎么执行。我见过很多人第一次写技能时直接在里面堆一大堆提示词这其实不太对。SKILL.md 更像是给模型的一份索引和约束重点不是把话说得多漂亮而是让模型在最短时间内理解任务的边界、流程和产出。冗长的描述反而会浪费上下文窗口还会让模型抓不住重点。2.2 元信息、触发条件和脚本怎么写SKILL.md 通常包含两部分YAML 格式的 frontmatter 和 Markdown 格式的正文。frontmatter 里面至少要写清两样name 和 description。description 特别关键因为 Agent 在对话中会通过语义匹配判断该不该启用这个技能。描述写得越具体触发就越准。比如“用于分析项目代码结构”就不如“当用户给出一个 Git 仓库或本地项目目录需要梳理模块划分、依赖关系和潜在风险时使用”来得准确。正文部分我建议按这种结构写先写背景说明再写操作步骤最后写输出格式和注意事项。脚本部分不是必须的但如果你希望技能能执行一些重复性操作可以在技能目录下放一个 scripts/ 文件夹里面放 Python、Shell 或其他语言的脚本然后让模型按需调用。2.3 一个可以直接抄的骨架代码下面这个是我常用的一套技能骨架你可以直接保存成 SKILL.md 开始改--- name: project-analyzer description: 当用户提供一个项目目录或 Git 仓库需要分析模块划分、核心依赖、潜在风险并输出结构化报告时使用。 --- # 项目分析技能 ## 目标 快速理解一个软件项目的整体结构与关键风险点。 ## 执行步骤 1. 先查看项目根目录读取 README、package.json、go.mod 等标识性文件确认技术栈。 2. 列出顶层目录和主要子目录判断模块边界。 3. 找到核心入口文件梳理主流程调用链。 4. 检查配置文件和凭据使用情况标记风险点。 5. 按固定格式输出报告。 ## 输出格式项目概览技术栈模块数量核心入口模块清单| 模块 | 职责 | 依赖 | 风险等级 |主要风险重构建议## 注意事项 - 不要在没有读文件的情况下根据文件名臆测模块逻辑。 - 风险点必须给出判断依据。这套骨架看着简单实际用起来非常顺。你可以在 scripts/ 里放一个脚本帮你自动拉取依赖树或统计代码行数模型会在需要时自己调用。3. 从导入到运行三种常见方式3.1 用 npx 命令安装社区现成技能现在很多 Agent 生态都支持通过命令行直接安装社区技能最典型的就是 npx 命令。比如在 Claude Code 里你可以运行类似这样的指令npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y这条命令的意思是从 GitHub 仓库拉取技能包指定给 Claude Code 使用-g 表示安装到全局技能目录-y 表示跳过交互确认。不同仓库的命令后缀会有差异但整体思路一致引入远程技能包让 Agent 能在后续对话中识别并使用。社区技能的质量参差不齐安装前最好看一眼仓库里的 SKILL.md 是否完整描述是否清晰。很多看起来功能很酷的技能装完发现触发词写得一塌糊涂模型根本不知道什么时候该用。我个人的习惯是先挑 star 数高、最近有更新的仓库再打开 SKILL.md 快速扫一遍确认结构规范才安装。3.2 手动导入本地或私有技能如果你不想依赖公共仓库或者技能涉及公司内部规范手动导入是更好的选择。最常见的做法是把技能文件夹放到 Agent 的全局技能目录里。以 Claude Code 为例技能目录一般在 ~/.claude/skills/ 下你只需要创建一个子目录把 SKILL.md 和辅助脚本放进去mkdir -p ~/.claude/skills/project-analyzer cp SKILL.md ~/.claude/skills/project-analyzer/如果希望技能只在某个项目里生效就把技能目录放到项目的 .claude/skills/ 目录下。这个机制非常像 npm 的全局依赖和本地依赖全局技能适合通用场景项目内技能适合团队规范。3.3 验证导入结果让 Agent 真正“看到”这个技能导入之后最关键的一步是验证。很多新手装完技能发现没用就是因为没有确认 Agent 是否真的扫描到了技能包。在 Claude Code 这类工具里你可以直接输入斜杠命令查看可用技能列表比如 /skills。如果列表里有你刚添加的技能名说明导入成功。另一种验证方式是开一个新对话把你的技能描述里的触发场景换个说法发给模型看它是否主动调用。比如技能里写的是“分析项目结构”你就可以说“帮我看下这个项目是怎么组织的”看看 Agent 会不会自动启用技能。如果发现没生效第一时间检查技能目录的层级。很多工具要求技能目录下直接就是 SKILL.md中间不能再套一层同名文件夹否则扫描不到。4. 完整演示把一个“项目分析技能”跑通4.1 需求拆解为什么选“项目分析”这个场景我决定用“项目分析”来做完整演示是因为这个场景几乎能满足你日常 80% 的代码理解需求。不管你是接手老项目、做技术调研还是 code review本质都是同一种行为快速理解一个陌生项目的边界和风险。设计技能之前我先明确了几个约束条件。第一技能必须在五分钟内能跑完一遍不能有太重的脚本逻辑。第二输出必须结构化方便直接贴到文档里。第三遇到无法读取的文件时要有明确的降级方案不能整段报错。基于这三个约束我写了后面这份 SKILL.md。4.2 编写技能包SKILL.md 和辅助脚本我先把技能目录准备好里面放了一个 SKILL.md 和一个 Python 辅助脚本脚本用来统计代码行数和依赖包数量。SKILL.md 内容大概长这样--- name: project-analyzer description: 当用户提供项目目录或代码仓库需要了解项目结构、模块边界、依赖关系与潜在风险时使用。 --- # 项目分析技能 ## 背景 用于快速摸清一个代码项目适用于接手老项目、代码评审、技术调研等场景。 ## 执行流程 1. 先看根目录标识文件判断技术栈。 2. 读取 README 或项目文档了解项目目标。 3. 用 scripts/stats.py 统计代码分布辅助判断模块规模。 4. 按模块维度逐个查看入口文件、路由和核心 service。 5. 标注配置项、鉴权逻辑、外部依赖等风险点。 6. 输出结构化报告。 ## 报告模板 按“项目概览”、“模块清单”、“风险点”三个部分输出。辅助脚本我就写了一个最简单的统计脚本放在 scripts/stats.py 里让模型需要时自己运行#!/usr/bin/env python3 import os, sys from collections import Counter root sys.argv[1] if len(sys.argv) 1 else . ext_counter Counter() line_counter 0 for dirpath, _, filenames in os.walk(root): if .git in dirpath or node_modules in dirpath: continue for f in filenames: ext os.path.splitext(f)[1] ext_counter[ext] 1 try: with open(os.path.join(dirpath, f), r, errorsignore) as fh: line_counter sum(1 for _ in fh) except Exception: pass print(扩展名分布:, dict(ext_counter.most_common(10))) print(总代码行数:, line_counter)写脚本时有个经验脚本输出越简单越好。模型处理长文本的能力虽然强但脚本输出太复杂会挤占上下文反而影响后续分析。我之前试过让脚本输出完整文件列表结果上下文很快就满了后面就改成了只输出统计摘要。4.3 从导入到调用全流程记录技能文件准备好后我直接把它放进了全局技能目录。然后开了一个新对话第一句话就说“帮我看下这个 Vue 项目的情况我在 /tmp/demo-project”。Agent 的动作分成这么几步先列出了根目录文件读取了 package.json 确认是 Vue 3 TypeScript接着运行了我写的 stats.py输出扩展名分布和总代码行数然后逐个打开了几个核心目录分析路由和 store最后按报告模板输出了一篇非常完整的项目分析。整个过程大概四十秒左右。最让我意外的是它自动跳过了 node_modules 目录没有像很多一次性 prompt 那样试图分析依赖包里的代码。这说明 SKILL.md 里的“前置检查”步骤起效了模型在执行时有了明确的“什么不该做”的边界。这就是技能和普通 prompt 的核心区别普通 prompt 是让模型自由发挥技能是给模型画好路线图。5. 怎么给 Skills 评分质量评估的几个维度5.1 可复现性换个项目还能不能用技能和普通脚本不一样它不能只在你精心挑选的例子上跑通。我给技能打分的第一个维度就是可复现性换一个项目、换一个数据源、甚至换一个模型版本这个技能还能不能稳定产出预期结果。测试可复现性的方法很简单不要只在一个项目里试找两三个不同技术栈、不同规模的项目轮着跑。如果技能里写了“先看 README”那遇到没有 README 的项目会不会卡住如果技能里写了“统计入口文件数量”那遇到单体大仓库和微服务多仓库时结论是否依然准确能应对变化的技能才是好技能。5.2 上下文占用会不会把对话窗口撑爆这个维度我吃过亏。早期我写技能时喜欢把需要的所有背景资料都写进 SKILL.md结果每次触发都要吃掉一大段上下文模型还没开始干活窗口已经用了三分之一。好的技能应该像一篇高质量文档该详则详该略则略。原则性内容写进 SKILL.md可变的细节放脚本让模型按需获取。比如“读取 package.json 判断技术栈”这句话就够了没必要把 package.json 的每一个字段都解释一遍。技能占用的上下文越少留给真正任务分析的上下文就越多。5.3 容错与降级遇到半路情况怎么办现实世界里的任务不会总按剧本走。技能执行到一半遇到文件缺失、权限不足、脚本报错模型是卡住还是继续降级执行直接决定这个技能能不能用。我给技能评分时会故意制造一些意外情况比如删掉某个关键文件、改错路径、输入空目录看看模型能不能在报错后切换到备用方案。一个合格的技能应该在 SKILL.md 里写明“遇到 XX 情况时采用 XX 替代方法”。没有降级方案就只能指望模型灵光乍现这不可靠。5.4 可维护性三个月后自己还改得动吗技能的维护成本往往被忽略。很多人写技能时只顾实现功能不考虑后续迭代结果三个月后想改一个步骤发现 SKILL.md 里全是过时信息根本无从下手。我建议每个技能都带上版本号并且在正文里标注最近一次修改时间。技能模块之间尽量解耦流程写在 SKILL.md 里操作逻辑尽量放在独立脚本里。这样改流程时不用动脚本改脚本时也不用重写整个文档。一个可维护的 Skill比一个功能强但没有人敢动的 Skill 有价值得多。下面是我常用的一套评分表模板5 分为满分任何一项低于 3 分我就不会在生产环境使用评分维度考察重点5 分标准可复现性跨项目、跨模型稳定性三个以上不同类型项目均稳定产出上下文占用SKILL.md 与提示词精简度不触发时几乎无感知触发后不挤占任务空间容错与降级异常路径处理能力所有识别到的异常都有降级方案可维护性版本、注释、模块拆分可以花十分钟快速定位并修改任意环节6. 常见问题与避坑实录6.1 技能没被触发先查这几处技能没触发是出现频率最高的问题。我排障的顺序是先确认技能目录位置是否正确再看 SKILL.md 的 frontmatter 有没有语法错误最后检查 description 描述是否和用户真实表达差异太大。这里要特别提醒description 不要写得太泛。比如“用于项目分析”这种描述模型确实有可能匹配不上改成“当用户需要分析项目结构、模块划分、依赖关系或风险点时使用”会大幅提高命中率。另外有些工具会缓存技能列表改了 SKILL.md 之后需要重启会话或执行刷新命令才能生效。6.2 导入命令报错或版本冲突用 npx 命令安装技能时最常见的报错是仓库地址写错或网络超时。GitHub 仓库地址必须带上用户名和仓库名不能只写仓库名。还有一类问题是技能包依赖特定 Agent 版本在旧版本工具上会提示不兼容。遇到这类问题我的建议是先确认 Agent 版本再查看技能仓库的 README 里的兼容性说明。很多优秀的技能包会同时支持多个 Agent但命令参数不同照抄别人的命令前一定要确认对方用的 Agent 类型和你一样。6.3 技能之间的互相干扰技能装多了以后一个新的坑会出现多个技能的描述相似模型不知道该用哪一个。比如你同时装了“前端代码审查”和“项目结构分析”分析一个 React 项目时模型可能两个技能都触发结果输出风格混乱。解决方法是给每个技能的 description 增加排他性关键词。比如“当前端项目需要检查组件拆分、状态管理和样式规范时使用”这样模型在做结构分析时就大概率不会误触。如果两个技能确实高度重合我的建议是合并而不是共存技能数量不是越多越好。6.4 有些场景真的不适合用 Skills最后我想说一个反直觉的点不是所有任务都适合写成技能。一次性调研、随手问个问题、临时写一小段脚本这些直接聊反而效率更高。技能适合的是那些你会反复执行、步骤清晰、输出格式固定的任务。判断标准很简单同一个任务你最近一个月内是否做过三次以上如果答案是肯定的才值得写成技能。如果只是一次性需求写成技能反而浪费时间。我在前端开发、数学建模报告、微信公众号文章排版这几个场景里各沉淀了一两个技能包基本覆盖了 90% 的重复劳动剩下的临时任务都用普通对话完成。写在最后关于技能设计的一点体会这篇教程从头到尾演示了一个技能从设计、编写、导入到运行评估的完整生命周期。我个人在写了很多个技能之后最大的体会是好技能的标准不是功能多而是“限制够清晰”。一个技能如果试图覆盖所有情况那它最后一定什么都做不好相反明确写清楚“什么时候不用这个技能”反而会让模型在正确的场景里更果断地调用它。最后分享一个实用的小技巧每次调整 SKILL.md 后我都会在同一组测试案例上重新跑一遍评分表里的四个维度然后记录分数变化。这样做几次之后你会慢慢形成一种直觉知道哪些描述会影响触发率哪些步骤会让模型跑偏这种手感不比任何现成的技能包差。技能是自己工作流的沉淀抄来的虽然快但真正顺手的一定是你自己反复调出来的那一个。 AI Agent技能实战：从SKILL.md到评分避坑完整指南
最近在给团队搭 Agent 工作流绕不开一个词Skills。无论你用的是 Claude Code还是各种支持 Agent 的编码工具Skills 都是把“模型会聊天”变成“模型会干活”的核心机制。很多朋友问我网上一堆“Skills 使用教程”要么只讲概念要么只给几个命令真正能从导入到评分讲完整的很少。这篇就是一次完整的实操记录我会从什么是 Skills 讲起给出一套标准技能包结构再用实际命令演示导入、触发和调用最后给出一个我自己常用的评分框架帮你判断一个技能到底值不值得留下来什么时候该删。对于刚接触的人这篇文章可以帮你建立完整的技能生命周期概念对于已经在写技能的人后半段的评分维度和避坑清单应该能让你少走不少弯路。1. Skills 到底是什么从一段工作流说起1.1 一个让我决定研究 Skills 的场景上周接了一个技术方案梳理的活客户丢过来一个老项目的源码要求我在半天内给出模块拆解、风险点和重构建议。这种活我以前的做法是开一个对话窗口贴上一堆文件路径然后不停地下指令“先看看这个目录”、“再读一下这个配置”、“能不能把依赖关系画出来”。结果就是上下文很快被各种碎片信息塞满模型经常做着做着就忘了前面看过什么要反复重复同一类问题。后来我换了一种方式提前写好一个“项目分析技能包”让模型按照固定流程走——先读 README 和项目配置再分析目录结构然后扫描核心模块的入口和依赖最后输出一份固定格式的报告。整个过程只花了一轮对话输出质量却稳定得多。这件事让我彻底明白Skills 的本质就是把“你希望 AI 怎么干活”这件事从临时口头指令变成可复用、可版本化、可分享的结构化配置。1.2 Skills 和 Prompt、MCP 的边界在哪很多人会把 Skills 和 Prompt、MCP 混在一起我一个个说清楚。Prompt 是口头交代你每次对话都要重新说一遍适合一次性任务。MCPModel Context Protocol是给模型接外部工具和数据的标准协议相当于给 AI 配了手和眼睛。Skills 则是介于两者之间的一套行为模板它告诉模型“遇到这类任务时按这个流程走用这些规则判断最后输出这种格式”。你可以这样理解Prompt 是任务描述MCP 是工具箱Skills 是老师傅写给新人的操作手册。操作手册里可以引用工具箱里的工具也可以包含具体的话术模板但它的核心价值是一致性和可复用性。好的 Skills 会让同一个任务在一百次执行中得到高度相似的结果这是单纯靠 Prompt 很难做到的。2. 动手之前先搞懂一个 Skill 的标准结构2.1 SKILL.md 就是那本操作手册不管哪种 Agent 实现目前主流技能格式基本都以 SKILL.md 文件为核心。这个文件可以放在项目目录下也可以放在 Agent 的全局技能目录里。它的作用就是让模型在读取技能时能快速知道三件事这个技能是干什么的、什么情况下触发、具体怎么执行。我见过很多人第一次写技能时直接在里面堆一大堆提示词这其实不太对。SKILL.md 更像是给模型的一份索引和约束重点不是把话说得多漂亮而是让模型在最短时间内理解任务的边界、流程和产出。冗长的描述反而会浪费上下文窗口还会让模型抓不住重点。2.2 元信息、触发条件和脚本怎么写SKILL.md 通常包含两部分YAML 格式的 frontmatter 和 Markdown 格式的正文。frontmatter 里面至少要写清两样name 和 description。description 特别关键因为 Agent 在对话中会通过语义匹配判断该不该启用这个技能。描述写得越具体触发就越准。比如“用于分析项目代码结构”就不如“当用户给出一个 Git 仓库或本地项目目录需要梳理模块划分、依赖关系和潜在风险时使用”来得准确。正文部分我建议按这种结构写先写背景说明再写操作步骤最后写输出格式和注意事项。脚本部分不是必须的但如果你希望技能能执行一些重复性操作可以在技能目录下放一个 scripts/ 文件夹里面放 Python、Shell 或其他语言的脚本然后让模型按需调用。2.3 一个可以直接抄的骨架代码下面这个是我常用的一套技能骨架你可以直接保存成 SKILL.md 开始改--- name: project-analyzer description: 当用户提供一个项目目录或 Git 仓库需要分析模块划分、核心依赖、潜在风险并输出结构化报告时使用。 --- # 项目分析技能 ## 目标 快速理解一个软件项目的整体结构与关键风险点。 ## 执行步骤 1. 先查看项目根目录读取 README、package.json、go.mod 等标识性文件确认技术栈。 2. 列出顶层目录和主要子目录判断模块边界。 3. 找到核心入口文件梳理主流程调用链。 4. 检查配置文件和凭据使用情况标记风险点。 5. 按固定格式输出报告。 ## 输出格式项目概览技术栈模块数量核心入口模块清单| 模块 | 职责 | 依赖 | 风险等级 |主要风险重构建议## 注意事项 - 不要在没有读文件的情况下根据文件名臆测模块逻辑。 - 风险点必须给出判断依据。这套骨架看着简单实际用起来非常顺。你可以在 scripts/ 里放一个脚本帮你自动拉取依赖树或统计代码行数模型会在需要时自己调用。3. 从导入到运行三种常见方式3.1 用 npx 命令安装社区现成技能现在很多 Agent 生态都支持通过命令行直接安装社区技能最典型的就是 npx 命令。比如在 Claude Code 里你可以运行类似这样的指令npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y这条命令的意思是从 GitHub 仓库拉取技能包指定给 Claude Code 使用-g 表示安装到全局技能目录-y 表示跳过交互确认。不同仓库的命令后缀会有差异但整体思路一致引入远程技能包让 Agent 能在后续对话中识别并使用。社区技能的质量参差不齐安装前最好看一眼仓库里的 SKILL.md 是否完整描述是否清晰。很多看起来功能很酷的技能装完发现触发词写得一塌糊涂模型根本不知道什么时候该用。我个人的习惯是先挑 star 数高、最近有更新的仓库再打开 SKILL.md 快速扫一遍确认结构规范才安装。3.2 手动导入本地或私有技能如果你不想依赖公共仓库或者技能涉及公司内部规范手动导入是更好的选择。最常见的做法是把技能文件夹放到 Agent 的全局技能目录里。以 Claude Code 为例技能目录一般在 ~/.claude/skills/ 下你只需要创建一个子目录把 SKILL.md 和辅助脚本放进去mkdir -p ~/.claude/skills/project-analyzer cp SKILL.md ~/.claude/skills/project-analyzer/如果希望技能只在某个项目里生效就把技能目录放到项目的 .claude/skills/ 目录下。这个机制非常像 npm 的全局依赖和本地依赖全局技能适合通用场景项目内技能适合团队规范。3.3 验证导入结果让 Agent 真正“看到”这个技能导入之后最关键的一步是验证。很多新手装完技能发现没用就是因为没有确认 Agent 是否真的扫描到了技能包。在 Claude Code 这类工具里你可以直接输入斜杠命令查看可用技能列表比如 /skills。如果列表里有你刚添加的技能名说明导入成功。另一种验证方式是开一个新对话把你的技能描述里的触发场景换个说法发给模型看它是否主动调用。比如技能里写的是“分析项目结构”你就可以说“帮我看下这个项目是怎么组织的”看看 Agent 会不会自动启用技能。如果发现没生效第一时间检查技能目录的层级。很多工具要求技能目录下直接就是 SKILL.md中间不能再套一层同名文件夹否则扫描不到。4. 完整演示把一个“项目分析技能”跑通4.1 需求拆解为什么选“项目分析”这个场景我决定用“项目分析”来做完整演示是因为这个场景几乎能满足你日常 80% 的代码理解需求。不管你是接手老项目、做技术调研还是 code review本质都是同一种行为快速理解一个陌生项目的边界和风险。设计技能之前我先明确了几个约束条件。第一技能必须在五分钟内能跑完一遍不能有太重的脚本逻辑。第二输出必须结构化方便直接贴到文档里。第三遇到无法读取的文件时要有明确的降级方案不能整段报错。基于这三个约束我写了后面这份 SKILL.md。4.2 编写技能包SKILL.md 和辅助脚本我先把技能目录准备好里面放了一个 SKILL.md 和一个 Python 辅助脚本脚本用来统计代码行数和依赖包数量。SKILL.md 内容大概长这样--- name: project-analyzer description: 当用户提供项目目录或代码仓库需要了解项目结构、模块边界、依赖关系与潜在风险时使用。 --- # 项目分析技能 ## 背景 用于快速摸清一个代码项目适用于接手老项目、代码评审、技术调研等场景。 ## 执行流程 1. 先看根目录标识文件判断技术栈。 2. 读取 README 或项目文档了解项目目标。 3. 用 scripts/stats.py 统计代码分布辅助判断模块规模。 4. 按模块维度逐个查看入口文件、路由和核心 service。 5. 标注配置项、鉴权逻辑、外部依赖等风险点。 6. 输出结构化报告。 ## 报告模板 按“项目概览”、“模块清单”、“风险点”三个部分输出。辅助脚本我就写了一个最简单的统计脚本放在 scripts/stats.py 里让模型需要时自己运行#!/usr/bin/env python3 import os, sys from collections import Counter root sys.argv[1] if len(sys.argv) 1 else . ext_counter Counter() line_counter 0 for dirpath, _, filenames in os.walk(root): if .git in dirpath or node_modules in dirpath: continue for f in filenames: ext os.path.splitext(f)[1] ext_counter[ext] 1 try: with open(os.path.join(dirpath, f), r, errorsignore) as fh: line_counter sum(1 for _ in fh) except Exception: pass print(扩展名分布:, dict(ext_counter.most_common(10))) print(总代码行数:, line_counter)写脚本时有个经验脚本输出越简单越好。模型处理长文本的能力虽然强但脚本输出太复杂会挤占上下文反而影响后续分析。我之前试过让脚本输出完整文件列表结果上下文很快就满了后面就改成了只输出统计摘要。4.3 从导入到调用全流程记录技能文件准备好后我直接把它放进了全局技能目录。然后开了一个新对话第一句话就说“帮我看下这个 Vue 项目的情况我在 /tmp/demo-project”。Agent 的动作分成这么几步先列出了根目录文件读取了 package.json 确认是 Vue 3 TypeScript接着运行了我写的 stats.py输出扩展名分布和总代码行数然后逐个打开了几个核心目录分析路由和 store最后按报告模板输出了一篇非常完整的项目分析。整个过程大概四十秒左右。最让我意外的是它自动跳过了 node_modules 目录没有像很多一次性 prompt 那样试图分析依赖包里的代码。这说明 SKILL.md 里的“前置检查”步骤起效了模型在执行时有了明确的“什么不该做”的边界。这就是技能和普通 prompt 的核心区别普通 prompt 是让模型自由发挥技能是给模型画好路线图。5. 怎么给 Skills 评分质量评估的几个维度5.1 可复现性换个项目还能不能用技能和普通脚本不一样它不能只在你精心挑选的例子上跑通。我给技能打分的第一个维度就是可复现性换一个项目、换一个数据源、甚至换一个模型版本这个技能还能不能稳定产出预期结果。测试可复现性的方法很简单不要只在一个项目里试找两三个不同技术栈、不同规模的项目轮着跑。如果技能里写了“先看 README”那遇到没有 README 的项目会不会卡住如果技能里写了“统计入口文件数量”那遇到单体大仓库和微服务多仓库时结论是否依然准确能应对变化的技能才是好技能。5.2 上下文占用会不会把对话窗口撑爆这个维度我吃过亏。早期我写技能时喜欢把需要的所有背景资料都写进 SKILL.md结果每次触发都要吃掉一大段上下文模型还没开始干活窗口已经用了三分之一。好的技能应该像一篇高质量文档该详则详该略则略。原则性内容写进 SKILL.md可变的细节放脚本让模型按需获取。比如“读取 package.json 判断技术栈”这句话就够了没必要把 package.json 的每一个字段都解释一遍。技能占用的上下文越少留给真正任务分析的上下文就越多。5.3 容错与降级遇到半路情况怎么办现实世界里的任务不会总按剧本走。技能执行到一半遇到文件缺失、权限不足、脚本报错模型是卡住还是继续降级执行直接决定这个技能能不能用。我给技能评分时会故意制造一些意外情况比如删掉某个关键文件、改错路径、输入空目录看看模型能不能在报错后切换到备用方案。一个合格的技能应该在 SKILL.md 里写明“遇到 XX 情况时采用 XX 替代方法”。没有降级方案就只能指望模型灵光乍现这不可靠。5.4 可维护性三个月后自己还改得动吗技能的维护成本往往被忽略。很多人写技能时只顾实现功能不考虑后续迭代结果三个月后想改一个步骤发现 SKILL.md 里全是过时信息根本无从下手。我建议每个技能都带上版本号并且在正文里标注最近一次修改时间。技能模块之间尽量解耦流程写在 SKILL.md 里操作逻辑尽量放在独立脚本里。这样改流程时不用动脚本改脚本时也不用重写整个文档。一个可维护的 Skill比一个功能强但没有人敢动的 Skill 有价值得多。下面是我常用的一套评分表模板5 分为满分任何一项低于 3 分我就不会在生产环境使用评分维度考察重点5 分标准可复现性跨项目、跨模型稳定性三个以上不同类型项目均稳定产出上下文占用SKILL.md 与提示词精简度不触发时几乎无感知触发后不挤占任务空间容错与降级异常路径处理能力所有识别到的异常都有降级方案可维护性版本、注释、模块拆分可以花十分钟快速定位并修改任意环节6. 常见问题与避坑实录6.1 技能没被触发先查这几处技能没触发是出现频率最高的问题。我排障的顺序是先确认技能目录位置是否正确再看 SKILL.md 的 frontmatter 有没有语法错误最后检查 description 描述是否和用户真实表达差异太大。这里要特别提醒description 不要写得太泛。比如“用于项目分析”这种描述模型确实有可能匹配不上改成“当用户需要分析项目结构、模块划分、依赖关系或风险点时使用”会大幅提高命中率。另外有些工具会缓存技能列表改了 SKILL.md 之后需要重启会话或执行刷新命令才能生效。6.2 导入命令报错或版本冲突用 npx 命令安装技能时最常见的报错是仓库地址写错或网络超时。GitHub 仓库地址必须带上用户名和仓库名不能只写仓库名。还有一类问题是技能包依赖特定 Agent 版本在旧版本工具上会提示不兼容。遇到这类问题我的建议是先确认 Agent 版本再查看技能仓库的 README 里的兼容性说明。很多优秀的技能包会同时支持多个 Agent但命令参数不同照抄别人的命令前一定要确认对方用的 Agent 类型和你一样。6.3 技能之间的互相干扰技能装多了以后一个新的坑会出现多个技能的描述相似模型不知道该用哪一个。比如你同时装了“前端代码审查”和“项目结构分析”分析一个 React 项目时模型可能两个技能都触发结果输出风格混乱。解决方法是给每个技能的 description 增加排他性关键词。比如“当前端项目需要检查组件拆分、状态管理和样式规范时使用”这样模型在做结构分析时就大概率不会误触。如果两个技能确实高度重合我的建议是合并而不是共存技能数量不是越多越好。6.4 有些场景真的不适合用 Skills最后我想说一个反直觉的点不是所有任务都适合写成技能。一次性调研、随手问个问题、临时写一小段脚本这些直接聊反而效率更高。技能适合的是那些你会反复执行、步骤清晰、输出格式固定的任务。判断标准很简单同一个任务你最近一个月内是否做过三次以上如果答案是肯定的才值得写成技能。如果只是一次性需求写成技能反而浪费时间。我在前端开发、数学建模报告、微信公众号文章排版这几个场景里各沉淀了一两个技能包基本覆盖了 90% 的重复劳动剩下的临时任务都用普通对话完成。写在最后关于技能设计的一点体会这篇教程从头到尾演示了一个技能从设计、编写、导入到运行评估的完整生命周期。我个人在写了很多个技能之后最大的体会是好技能的标准不是功能多而是“限制够清晰”。一个技能如果试图覆盖所有情况那它最后一定什么都做不好相反明确写清楚“什么时候不用这个技能”反而会让模型在正确的场景里更果断地调用它。最后分享一个实用的小技巧每次调整 SKILL.md 后我都会在同一组测试案例上重新跑一遍评分表里的四个维度然后记录分数变化。这样做几次之后你会慢慢形成一种直觉知道哪些描述会影响触发率哪些步骤会让模型跑偏这种手感不比任何现成的技能包差。技能是自己工作流的沉淀抄来的虽然快但真正顺手的一定是你自己反复调出来的那一个。