目录从零理解 AI Skill不只是Markdown这么简单先说我最开始的误解Skill 到底是什么Prompt 和 Skill 的区别不在长度Skill 和 Agent、Memory、Workflow、MCP 的关系Skill 和 MCP一个管工艺一个管机器Codex、Claude Code、Cursor 为什么都在“技能化”一个 Skill 是怎么被选中的写一个接入 LLM 的迷你 Skill RunnerSkill 真正提效的地方团队里怎么管理 Skill安全问题不能跳过更大的图Skill Workflow Memory MCP Multi-Agent我现在会怎么写第一个 Skill最后聊聊Skill 的价值其实不在“炫”参考资料从零理解 AI Skill不只是Markdown这么简单我第一次看到 AI Skill 这个词的时候非常疑惑这不就是把 Prompt 写进一个 Markdown 文件吗后来我把 Codex、Claude Code、Cursor 这些工具放进日常开发里用了几轮才发现这个理解太浅了。Prompt 解决的是“这一次怎么问”。Skill 解决的是“以后这类事怎么稳定做”。这两件事看起来都在写自然语言但工程意义完全不一样。我真正意识到这一点是在反复让 AI 做代码 Review、整理接口文档、检查发布清单的时候。每次我都要重新提醒它先看已有实现。 不要上来就重构。 别动无关文件。 先报风险再讲建议。 日志里不要打敏感字段。 跑不了测试要说明原因。这些话单次看没什么一周说十几遍之后就很烦。更要命的是只要漏说一次AI 就可能按自己的默认习惯来。这就是 Skill 出现的背景。这篇文章不是官方文档翻译。我更想按自己理解这件事的过程把 AI Skill 讲清楚它到底比 Prompt 多了什么。为什么 Codex、Claude Code、Cursor 都在往“技能化”方向走。我们自己要怎么写一个真正能落地的 Skill。先说我最开始的误解我以前以为 Prompt 的问题只是“不够长”。比如我要让 AI Review 一段 Go 后端代码通常会这样写帮我按我们团队规范 Review 这段 Go 代码重点关注接口边界、错误处理、并发安全、日志和测试。这条 Prompt 当然能用。但用着用着我又会补充handler 不直接写业务逻辑。 error 要保留上下文不能只返回 err。 goroutine 启动后要有退出条件。 context 不能随便用 context.Background()。 数据库查询不要 select *。 不要只说代码风格先找真实风险。再后来我发现不只是代码 Review。每个项目、每类任务都有一堆这种“隐形规则”。接口文档有接口文档的规则。Review 有 Review 的规则。排查线上日志有排查线上日志的规则。做发布检查也有发布检查的规则。如果这些规则都靠聊天时临时补充AI Coding 的体验会很不稳定问题实际表现记不住上下文今天按规范写明天又忘了难复用每次开新对话都要重新解释难协作团队其他人不知道你平时怎么教 AI难演进好用的经验散落在聊天记录里后来我看了一些有关的科普才把它想明白Prompt 更像临时沟通。 Skill 更像可以版本管理的岗位 SOP。在真实工程里我们不会指望每个新人都靠口头提醒记住所有规范。我们会写文档、脚本、模板、检查清单。Skill 做的事情也类似只不过它的读者从人变成了 Agent。Skill 到底是什么我现在会这样定义它AI Skill 触发条件 操作流程 行为约束 参考资料 可复用脚本/模板它不是“更长的 Prompt”。一个典型 Skill 目录大概长这样my-skill/ SKILL.md references/ api-style-guide.md database-schema.md scripts/ check_structure.py assets/ template.md核心是SKILL.md但真正让它有工程价值的经常是旁边的references/、scripts/和assets/。一个最小的 Skill 可以这么写--- name: go-service-review description: 用于 Review Go 后端服务代码重点关注接口边界、错误处理、并发安全、context 传递、数据库访问、日志和测试覆盖。 --- # Go 服务代码 Review 按下面的顺序 Review Go 后端改动 1. 先看业务行为是否正确接口边界是否清晰。 2. 检查错误处理错误是否保留上下文是否避免吞错和重复包装。 3. 检查并发安全goroutine 是否可退出channel 是否可能阻塞是否存在 data race。 4. 检查 context 传递不要随意使用 context.Background()超时和取消要能向下传递。 5. 检查数据库访问不要 select *避免 N1 查询新增查询条件要考虑索引。 6. 检查日志和测试日志不能包含敏感信息测试要覆盖成功路径、失败路径和边界场景。 报告问题时先说具体风险和文件位置。除非会影响正确性或维护成本否则不要把重点放在纯代码风格建议上。这里有两个细节很重要。第一个是description。很多人写 Skill 时会把“什么时候使用”写在正文里。但 Agent 只有先决定加载这个 Skill才会看到正文。所以触发条件最好写进description而且要具体。这里也顺便解释一下name保留英文短标识更多是工程习惯方便目录、脚本和工具识别description、流程、约束、检查清单都可以写中文。只要你的团队主要用中文协作中文反而更容易维护。第二个是流程顺序。我以前写 Review Prompt经常只写“关注事务、日志、异常”。结果 AI 会按自己的习惯输出一堆建议。后来我把顺序固定成“业务正确性优先其次数据一致性再看日志和测试”输出质量明显稳定了很多。不是模型突然变聪明了而是它的工作路径的输出被收窄了。Prompt 和 Skill 的区别不在长度一开始我把 Skill 当成“长的 Prompt”。后来做了几个小 Skill 才发现真正的区别不是长度而是生命周期。对比PromptSkill生命周期一次对话长期存在复用方式复制粘贴自动发现或显式调用内容形态一段文本文件夹、说明、脚本、参考资料、模板团队协作难共享可以放进 Git稳定性依赖当次表达依赖固定流程和约束演进方式聊天记录里改像代码一样迭代比如这个 Prompt帮我检查一下这次数据库变更重点看字段设计、索引、兼容性和回滚方案。能不能用能。但它太依赖当次表达。下次你要检查订单表、用户表、账单表又要重新强调哪些字段不能改、哪些索引要看、哪些兼容性风险要提前说明。Skill 化之后可以变成这样--- name: db-migration-review description: 用于 Review 数据库表结构和数据迁移变更重点关注兼容性、索引、数据一致性、回滚方案和上线风险。 --- # 数据库变更 Review Review 数据库变更时先判断这次改动会不会影响线上读写路径。 检查顺序 1. 先确认变更目的和影响范围。 2. 检查是否兼容老版本代码和灰度发布过程。 3. 检查新增索引是否匹配真实查询条件避免无效索引和锁表风险。 4. 检查字段默认值、空值约束、枚举值扩展是否会影响历史数据。 5. 检查数据迁移脚本是否可重复执行失败后是否可恢复。 6. 检查回滚方案和监控指标是否清楚。 安全边界 - 不要直接执行生产写操作。 - 不要假设业务含义拿不准时要标出问题。 - 不要只看 SQL 能不能跑还要看上线时机、数据量和锁影响。之后你只需要说帮我看一下这次订单表结构变更有没有风险。Agent 就有机会按这套数据库变更 Review 的习惯来而不是每次重新猜。这里的关键不是“少打几个字”而是把协作方式固定下来。Skill 和 Agent、Memory、Workflow、MCP 的关系这几个词特别容易混。我之前看 Agent 架构文章时经常看到一堆概念堆在一起Agent Memory Workflow MCP Skill Tool刚开始看会觉得它们都像是在“给 AI 增强能力”。但实际做下来它们管的层不一样。简单总结来说Agent真正执行任务的运行体 Workflow规定任务步骤怎么流转 Memory长期记住偏好、事实和项目约定 MCP / Tools连接外部系统比如文件、GitHub、数据库、浏览器 Skill告诉 Agent 遇到某类任务时应该怎么专业地做Skill 不是工具也不是记忆。它更像“专业行为层”。举个更具体的例子。用户说帮我看一下这次订单模块改动有没有问题。没有 Skill 时Agent 可能会泛泛地说代码整体结构清晰建议增加测试。加载go-service-reviewSkill 后它更可能按后端 Reviewer 的思路看1. handler 是否只处理 HTTP 入参和响应而不是直接写业务逻辑 2. 下单流程里的 context 超时和取消是否能传到库存、支付、数据库层 3. 支付回调是否幂等 4. 新增 goroutine 是否有退出条件是否可能泄漏 5. 失败日志是否带 orderId 和 traceId同时不包含敏感字段 6. 测试是否覆盖重复回调、库存不足和并发下单这就是差别。Skill 没有让 Agent 多一个 shell 工具也没有让它记住新事实。它改变的是 Agent 做这类任务时的判断顺序和关注点。Skill 和 MCP一个管工艺一个管机器MCP 是 Model Context Protocol。简单说它让 AI 应用可以用统一方式连接外部工具。比如Filesystem MCP Server读写文件 GitHub MCP Server查 issue、PR、CI Docs/Search MCP Server查文档或知识库 Database MCP Server查结构或执行受控查询但工具只是工具。有 GitHub 工具不代表 Agent 就知道修 issue 前应该先看哪些上下文。有数据库工具也不代表它知道什么时候不能直接执行写操作。所以我现在更喜欢这个类比MCP 像车间里的机器。 Skill 像工艺流程。 Agent 像操作员。只有机器没有流程很容易乱用。只有流程没有机器又只能纸上谈兵。一个规定 MCP 使用方式的 Skill 可能长这样--- name: github-issue-fixer description: 用于在具备 GitHub 和文件系统工具的代码库中修复 GitHub issue。 --- # GitHub Issue 修复助手 工作流程 1. 先阅读 issue 标题、正文、标签和评论。 2. 在代码库里搜索相关模块。 3. 如果条件允许查看最近相关 commit 或 PR。 4. 编辑文件前先写一个简短修复计划。 5. 实现最小可行改动。 6. 运行有针对性的测试。 7. 总结修改文件、测试结果和剩余风险。 工具使用建议 - 用 GitHub 工具读取 issue 和 PR 上下文。 - 用文件系统工具检查和修改代码。 - 用 shell 命令运行测试、lint 和安全的只读检查。 安全边界 - 不要自动关闭 issue。 - 除非用户明确要求不要推送分支。 - 不要修改无关文件。这段内容本身不提供 GitHub API。它只是告诉 Agent有了工具以后应该按什么顺序用哪些动作不能擅自做。这个边界很重要。尤其在真实项目里AI 不是不能调用工具而是不能乱调用工具。Codex、Claude Code、Cursor 为什么都在“技能化”不同产品叫法不一样但方向确实很像。工具常见形态更适合沉淀什么CodexSKILL.md、skills 目录、插件/资源专项工作流、脚本、项目能力包Claude CodeAgent Skills、CLAUDE.md、slash commands、hooks团队技能、记忆、命令、自动化检查CursorProject Rules、User Rules、Memories项目规范、编码风格、持久上下文它们不一定是完全相同的功能但都在解决同一个工程问题怎么让 AI 的行为从临时对话变成可复用的协作模式。我自己使用时会粗略这样区分机制更像什么适合场景Skill能力包某类任务的流程、规则、工具策略Slash Command按钮/review、/commit这种固定入口Memory / Rules长期说明项目规范、个人偏好Hooks自动守门工具调用前后的校验、阻断、审计比如 Claude Code 里可以有一个项目 Skill.claude/ skills/ go-service-review/ SKILL.md内容可能是--- name: go-service-review description: 用于 Review 或修改 Go 后端服务代码重点关注 handler、service、repository、context、错误处理、日志和测试。 --- # Go 服务代码 Review 编辑前先做三件事 1. 分清 handler、service、repository 和 DTO 的边界。 2. 搜索项目里是否已经有类似实现。 3. 优先做符合本地约定的小改动。 Review 检查清单 - handler 只处理 HTTP 入参、鉴权结果和响应组装。 - service 承载业务规则、事务边界和核心流程。 - repository 不要把存储细节泄漏到上层。 - 参数校验要在业务状态变更前完成。 - error 要保留上下文但不要重复包装到难以阅读。 - goroutine、channel、mutex 的使用要检查退出、阻塞和 data race 风险。 - 日志要包含业务标识但不能包含密钥、token、手机号等敏感信息。 - 测试要覆盖成功、失败、边界和并发场景。Cursor 里不一定叫 Skill但你用 Rules、Memories 做的很多事本质上也在沉淀“AI 应该怎么参与这个项目”。名字不同不影响背后的趋势AI Coding 正在从“提示词技巧”走向“能力工程”。一个 Skill 是怎么被选中的最简化的版本其实就四步扫描可用 Skill 读取 name description 根据用户任务选择匹配项 加载完整 SKILL.md并把 instructions 注入上下文真实系统肯定会更复杂可能会有语义检索、排序、项目作用域、上下文预算、权限策略。但理解原理时先把它想成“按任务选择操作手册”就够了。这里有个容易踩的坑不要把所有 Skill 一次性塞进上下文。Skill 多了以后如果全部加载成本高不说还会互相干扰。一个数据库变更 Review Skill、一个代码 Review Skill、一个安全审计 Skill 同时进上下文模型很容易不知道到底该听谁的。更合理的方式是先读取 metadata 命中后再读取正文 正文不够再读取 references 确定性任务交给 scripts这也是为什么description要写清楚。写一个接入 LLM 的迷你 Skill Runner为了搞明白 Skill 到底怎么影响 Agent 行为最直接的办法不是只打印上下文而是接一个真实 LLM 跑一遍。这个教学版 Runner 只做四件事扫描skills/*/SKILL.md读取 Skill 的name和description选择一个匹配的 Skill把完整 Skill 正文和用户任务一起发给 LLM项目结构mini-skill-runner/ run_skill_with_llm.py skills/ python-review/ SKILL.mdskills/python-review/SKILL.md--- name: python-review description: 用于 Review Python 代码重点关注正确性、可读性、类型标注、错误处理、测试和可维护性。 --- # Python 代码 Review Review Python 代码时 1. 先找正确性问题。 2. 再看边界条件和错误处理。 3. 检查类型标注和数据结构是否合适。 4. 检查测试是否覆盖了本次改动行为。 5. 输出时先列问题再写总结。run_skill_with_llm.pyfromdataclassesimportdataclassfrompathlibimportPathfromopenaiimportOpenAIimportosimportreimportsys DEMO_CODE def average_price(items): total 0 for item in items: total item[price] / item[count] return total / len(items) dataclassclassSkill:name:strdescription:strbody:strpath:Pathdefparse_skill(path:Path)-Skill:textpath.read_text(encodingutf-8)matchre.match(r---\r?\n(.*?)\r?\n---\r?\n(.*),text,re.S)ifnotmatch:raiseValueError(fInvalid skill file:{path})frontmatter,bodymatch.groups()data{}forlineinfrontmatter.splitlines():if:inline:key,valueline.split(:,1)data[key.strip()]value.strip()returnSkill(namedata[name],descriptiondata[description],bodybody.strip(),pathpath,)defload_skills(root:Path)-list[Skill]:return[parse_skill(path)forpathinroot.glob(*/SKILL.md)]defscore(task:str,skill:Skill)-int:textf{skill.name}{skill.description}.lower()wordsre.findall(r[a-zA-Z][a-zA-Z0-9_-],task.lower())returnsum(1forwordinwordsifwordintext)defselect_skill(task:str,skills:list[Skill])-Skill|None:rankedsorted(skills,keylambdaskill:score(task,skill),reverseTrue)ifnotrankedorscore(task,ranked[0])0:returnNonereturnranked[0]defbuild_input(task:str,skill:Skill)-str:returnf 你是一个谨慎的代码审查 Agent。 下面是本次任务加载的 Skill请按它的流程和约束工作{skill.body}用户任务{task}待 Review 代码 python{DEMO_CODE.strip()} defmain()-int:iflen(sys.argv)2:print(Usage: python run_skill_with_llm.py task)return2modelos.getenv(OPENAI_MODEL)ifnotmodel:print(Please set OPENAI_MODEL, for example: $env:OPENAI_MODELgpt-5.6)return2task .join(sys.argv[1:])skillsload_skills(Path(skills))skillselect_skill(task,skills)ifskillisNone:print(No matching skill. Use general agent behavior.)return0print(fSelected skill:{skill.name})print()print(LLM response:)print(*40)clientOpenAI()responseclient.responses.create(modelmodel,inputbuild_input(task,skill),)print(response.output_text)print(*40)return0if__name____main__:raiseSystemExit(main())运行pip install openai$env:OPENAI_API_KEY你的 API Key$env:OPENAI_MODELgpt-5.6python run_skill_with_llm.pyreview this Python code for bugs and tests输出会类似Selected skill: python-review LLM response: 问题 1. items 为空时会触发除零错误。 2. item[count] 为 0 时会触发除零错误。 3. price 或 count 缺失时会抛出 KeyError错误信息对调用方不友好。 建议 - 先校验输入列表不能为空。 - 校验每个元素是否包含必要字段。 - 对 count 0 的数据给出明确错误。 - 为正常、空列表、缺失字段、count 为 0 的场景补测试。 这个 Demo 比单纯打印上下文更直观因为你能看到同一段代码在加载 Skill 后输出会更接近 Skill 里规定的 Review 顺序。当然它仍然很简陋Skill 选择还只是英文关键词匹配。中文任务要做得更好需要分词、向量检索或语义匹配。真实系统还要考虑文件类型、目录、历史使用、用户显式指定和工具权限。调用真实 LLM 会产生 API 成本所以不要把 API Key 写进代码或仓库。但它已经能把 Skill 系统的骨架说明白Skill 不是黑科技。 它就是先被发现再被选择最后作为上下文影响 Agent 行为。Skill 真正提效的地方我一开始以为 Skill 最大收益是“少写 Prompt”。后来发现这只是最浅的一层。更有价值的是后面几层少解释项目背景 少纠正输出风格 少出现流程漂移 少改无关文件 团队经验可以沉淀进 Git比如团队共享一个代码审查 Skill# Service Review 按下面的优先级找问题 1. 行为回归。 2. 数据一致性。 3. 安全和权限校验。 4. 可观测性和错误处理。 5. 测试覆盖。 除非影响可维护性或正确性否则不要把时间花在纯格式、命名这类表层风格问题上。这几行规则看起来朴素但很管用。因为很多 AI Review 的问题不是“看不懂代码”而是“优先级不对”。它可能花很多篇幅讲命名、空行、注释却漏掉事务边界、幂等、权限校验这种真正会出事的东西。Skill 的作用就是把优先级固定住。还有一个点Skill 可以减少幻觉空间但不能消灭幻觉。比如在 API 文档生成 Skill 里写不要编造 API 字段。写接口文档前先读取 OpenAPI schema 或 controller 定义。这句话不能保证模型永远不编字段但会改变它的行为倾向。更稳的做法是配脚本从 OpenAPI JSON 自动抽取 endpoint 再让模型只负责解释和组织文字能确定的部分交给程序需要表达的部分交给模型。这才是我觉得 Skill 工程化里最重要的思路。团队里怎么管理 Skill如果 Skill 只是你本地的几个 Markdown 文件它更多是个人效率工具。如果它进了团队仓库就变成团队资产。这时就不能随便写了。至少要像代码一样管理有目录规范。有 owner。有 Review。有版本。有测试样例。有安全边界。一个比较舒服的目录可以这样设计ai-skills/ skills/ service-review/ SKILL.md references/ backend-style.md error-code.md scripts/ check_structure.py api-doc-writer/ SKILL.md references/ doc-style.md adapters/ cursor/ claude/ codex/为什么要有adapters/因为不同工具的格式不完全一样。团队可以维护一份标准 Skill 源再生成不同工具需要的格式Claude Code: .claude/skills/... Codex: .agents/skills/... Cursor: .cursor/rules/...我不建议一开始就做得特别复杂。比较现实的做法是先从一个高频任务开始比如service-review api-doc-writer db-migration-review incident-analysis release-note每个 Skill 只解决一类任务。别把所有团队规范塞进一个 “super-skill”最后谁也不敢改Agent 也抓不住重点。安全问题不能跳过Skill 本身也可能成为风险源。因为它会影响 Agent 行为而且里面可能带脚本。常见风险有这些恶意 Skill 在说明里诱导 Agent 泄露数据。Skill 里的脚本执行危险命令。Skill 要求读取过多敏感文件。Skill 给工具过宽权限。description写得太宽导致误触发。所以团队共享 Skill 至少要做几件事只安装可信来源的 Skill。ReviewSKILL.md和scripts/。不把密钥写进 Skill。高危写操作、发布、删除必须有人确认。对 Skill 的变更走代码审查。这部分听起来没那么有趣但在真实项目里很关键。AI Coding 的问题从来不是“能不能自动化”而是“自动化以后出了事谁兜底”。Skill 越强这个问题越要提前想清楚。更大的图Skill Workflow Memory MCP Multi-Agent如果只看单个 Skill它就是一个能力包。但放到更大的 AI Coding 系统里它的位置会更清楚用户任务 ↓ Workflow 拆步骤 ↓ 不同 Agent 执行不同节点 ↓ Skill 提供专业行为 ↓ Memory 补充长期上下文 ↓ MCP / Tools 连接真实系统 ↓ 测试、审计、人类确认形成闭环Multi-Agent 如果没有 Skill很容易变成角色扮演你是架构师。 你是开发者。 你是测试。听起来分工明确实际输出经常还是泛泛而谈。更有用的做法是架构师 Agent 有 architecture-review Skill。 开发者 Agent 有 implementation Skill。 测试 Agent 有 test-design Skill。 发布 Agent 有 release-checklist Skill。角色名只是标签。Skill 才是能力。我现在会怎么写第一个 Skill如果让我从零开始我不会先写一个很大的 Skill 系统。我会找一个每周都在重复做的任务比如代码 Review。然后只写这几个部分--- name: service-review description: 用于 Review 后端服务代码改动重点关注正确性、数据一致性、安全、可观测性和测试覆盖。 --- # 服务代码 Review Review 前 1. 先阅读变更文件。 2. 梳理请求流和数据变更路径。 3. 搜索项目里是否已有类似实现。 Review 优先级 1. 行为回归。 2. 数据一致性和事务边界。 3. 权限和安全检查。 4. 日志、指标和排障上下文。 5. 测试覆盖。 报告格式 - 先列问题按严重程度排序。 - 尽量附上文件和行号。 - 除非影响可维护性否则跳过纯风格建议。 边界 - Review 过程中不要修改文件。 - 不要编造业务规则。 - 如果测试无法运行要说明原因。先让它在真实任务里跑几次。跑完再改。不要一开始就追求完美。Skill 跟代码一样只有进入真实使用场景问题才会暴露出来。我自己踩过的一个坑是Skill 写得太“全面”反而不好用。比如一个 Skill 同时要求检查安全 检查性能 检查命名 检查架构 补测试 写文档 生成总结看起来很强实际执行时容易发散。后来我更倾向把它拆成几个小 Skill让每个 Skill 只解决一类问题。最后聊聊Skill 的价值其实不在“炫”Skill 这东西看起来没有 Agent 框架、MCP Server、向量数据库那么热闹。但我越用越觉得它很接近 AI 工程化的基础设施。因为真正重要的不是“让 AI 会写一段代码”而是把团队里的隐性经验沉淀下来业务规则架构约定发布流程故障处理经验数据口径安全红线Review 偏好这些东西不会自动存在于模型里。你不写Agent 就只能猜。Skill 的意义就是把这些“以前靠人记住、靠口头传递、靠踩坑积累”的东西变成 AI 可以读取、可以执行、可以迭代的能力资产。我现在对 Skill 的理解很简单Prompt 是一次性交互。 Skill 是长期协作方式。Codex、Claude Code、Cursor 的实现方式会继续变化目录名、触发方式、产品入口也可能变。但这个方向大概率不会变AI Coding 会从临时聊天走向可复用、可审查、可演进的工程协作。如果你还没写过 Skill可以先从一个最小版本开始选一个每周重复做的任务。 写清楚什么时候用。 写清楚先做什么、后做什么。 写清楚不能做什么。 配一个必要的参考文件或脚本。 拿真实任务跑几次再迭代。当第一个 Skill 真正跑顺以后你会发现自己和 AI 的关系会有点变化。它不再只是一个“问答工具”。它开始像一个可以被训练、被约束、被复盘的工程协作者。参考资料OpenAI Codex: SkillsOpenAI Skills Catalog for CodexOpenAI Codex Skill CreatorClaude Code: Agent SkillsCursor Docs: Rules一文读懂Skill从基础到实操保姆级喂饭教程什么是Skills如何用SkillsSkill详解2万字详细教程Skills是什么如何安装并使用Skills一文搞懂 Skill这玩意儿到底是啥为啥大家都在用