如果你最近在折腾 AI Agent 编程一定遇到过这样的场景同一个项目里让 AI 改代码时它总是“忘记”你的代码规范“提交前”让它自动检查测试它又得重新解释一遍规则团队里每个人都在各自的对话窗口里调教 AI但换个人、换个会话一切又从零开始。问题的本质不在于提示词写得不够好而在于你的 AI 使用经验没有被沉淀成可复用的工程资产。你缺的并不是一个更强的模型而是一套能把“高频指令、团队规范、私有工具”结构化组织起来的技能体系。这也是“garden-skills”这类项目值得关注的原因。从命名看它把 AI 技能组织成一个“花园”有分类、有土壤、有生长边界而不是把一堆 Prompt 随手堆在收藏夹里。如果你正在搭建团队级 AI 工作流或者想把手头的 AI 助手从“偶尔可用”提升到“稳定可用”这篇文章会给你一套可落地的思路以及可以直接上手的 Skill 编写方法。文章会从真实痛点出发先讲清楚 Agent Skills 的核心概念再用一个完整示例带你从零创建一个可复用的“代码规范检查”技能并把它接入常见 Agent 工作流。最后补充排错清单和工程化建议。即使你不打算原样使用某个仓库这套方法论也能直接迁移到你的项目中。1. 为什么你的 Agent 总是“不听话”先看一个普遍现象。很多人用 AI 编程助手时第一步是在对话里输入一大段“角色设定”比如你是一位资深 Java 工程师请遵循阿里巴巴开发规范修改代码前先输出影响面分析不要改变原有接口签名最后必须补充单元测试。这段话可能很有用但问题也很明显它只存在于当前会话中。下一次开会话你需要重新粘贴换一个同事他得自己写一遍甚至同一个任务只要换一个 AI 工具这套规则就彻底失效。从工程视角看这叫“上下文无法复用”。我们把大量时间花在重复解释规则上而不是解决真正的业务问题。更严重的是当规则越攒越多它们会变得相互矛盾、无法维护。一个典型的例子某个团队要求 AI“代码变更尽量小”同时又在另一个提示词里要求“统一重构所有使用旧 API 的地方”。两条规则冲突时AI 只能靠猜输出自然不稳定。与其说是 AI 不听话不如说我们从来没有给 AI 一套清晰、稳定、可检索的“操作手册”。而技能Skill体系本质上就是给 AI 写操作手册。1.1 从“提示词”到“技能”的转变传统的提示词是“一次性文本”输入给模型后就不再变动。技能则是一个“可复用的模块”它通常包含一段放在文件头部的说明Skill 名称、用途、适用场景一段指导模型如何执行的正文规则、步骤、示例可能还有配套脚本、模板、参考文档。garden-skills 这一系列仓库带来的启示是技能应该像代码一样管理。它们放在 Git 仓库里可以提交、评审、版本化、复用。你不需要把规则背下来而是把规则写进文件让 Agent 在需要时自动读取。这种转变的价值非常直接当技能文件被 AI 自动加载后你只需要说“按团队规范检查这次改动”AI 就会主动去读规范文件而不是靠你复制粘贴。团队里每个人使用同一套技能库输出口径自然一致。2. garden-skills 到底解决什么问题先做个简单的定位判断。如果你只是偶尔让 AI 写两段代码garden-skills 这类技能库对你可能有些“重”如果你的目标是把 AI 接入日常开发、Code Review、文档生成、测试补充等流程那它解决的是三个层次的问题。2.1 解决技能“放哪里”的问题在没有技能库之前大家的 Prompt 散落在聊天记录的置顶消息里个人笔记软件的收藏夹里公司 Wiki 的“AI 使用经验”页面里某个同事的电脑桌面上。这些位置有两个共同特点不可自动读取、不可版本管理。garden-skills 这类项目给出的答案是把所有技能放在一个固定目录结构中并用统一格式描述。Agent 在任务启动前可以“扫描”技能目录自动匹配最合适的技能。而不是靠用户手动在输入框里粘贴。2.2 解决技能“怎么用”的问题一个技能如果只写“请遵守编码规范”Agent 仍然不知道该做什么。garden-skills 所代表的技能格式要求你写清楚技能触发条件什么任务情况下使用执行步骤先做什么再做什么输入输出需要用户提供什么最终交付什么参考示例给 Agent 一段“标准答案”退出条件什么时候算完成。这其实就是把“经验”编码成“流程”。表面看是在给 AI 写文档实际上是在倒逼团队把隐性知识显性化。2.3 解决技能“怎么长”的问题花园的另一个特点是“可持续生长”。你可以先种下三五个核心技能之后再不断补充。随着新工具、新规范出现技能库可以迭代更新。如果只看表面你可能会把 garden-skills 当成一个“提示词模板合集”。但它的关键点在于“工程化组织”目录是分类的、文件是自描述的、技能是版本化的。这种设计让技能库可以像开源项目一样被协作维护。这也是它区别于普通收藏夹的核心。3. Agent Skills 的核心概念Skill、SKILL.md、技能编排在开始动手之前需要先统一几个概念。现在各家 Agent 产品对“技能”的实现不完全一致但绝大多数都遵循一个共同模式用文件描述技能按目录组织技能在运行时动态加载技能。3.1 Skill技能一个 Skill 是最小的可复用单元可以理解为“给 Agent 的一份能力说明书”。它可以是纯文本的指导也可以附带脚本和数据文件。例如一个“单元测试生成 Skill”可能包含说明文档告诉 Agent 什么时候生成测试、用什么测试框架、覆盖率要求是什么模板文件一个标准的测试文件模板辅助脚本解析当前项目测试配置的脚本。从工程角度说Skill 就是一个“带元数据的文件夹”。3.2 SKILL.md很多 Agent 技能体系中核心文件叫SKILL.md。这个文件是技能的入口通常采用 Markdown 格式头部带 YAML 或 TOML 元信息。下面的示例展示了常见结构--- name: code-style-review description: 用于检查代码是否符合项目编码规范适合在提交前或 Code Review 时使用。 version: 1.0.0 command: skill_check tags: [code-review, lint, quality] --- # 代码规范检查技能 当收到代码变更时按以下步骤执行 1. 读取项目根目录下的 .style-guide.md 文件 2. 检查变更文件是否违反规范 3. 输出问题清单按严重程度分组 4. 如果存在安全隐患额外标记 HIGHRISK。SKILL.md 的作用就是让 Agent “一眼看懂”这个技能什么时候用、怎么用。description字段尤其重要因为 Agent 通常靠它来判断当前任务要不要调用这个技能。3.3 技能编排Skill Orchestration技能编排是指 Agent 在响应任务时如何选择和组织多个技能。最简单的编排方式是“用户显式指定”比如你直接说“使用代码规范检查技能”。更高级的编排方式是“自动匹配”Agent 根据用户任务描述检索技能仓库中最合适的技能并加载。注意一个常见误区技能编排不是把所有技能一股脑塞进上下文。这样做会迅速耗尽上下文窗口还会让模型纠结到底该听谁的。好的编排是“按需加载”让 Agent 先识别任务类型再读取少量技能文件。表格普通 Prompt 与 Skill 的差异维度普通 PromptSkill 技能存储位置聊天记录、个人笔记统一目录、Git 仓库是否可版本管理通常不可可与代码一起管理自动加载不支持可被 Agent 自动识别团队共享靠复制粘贴靠仓库协作维护方式容易过期可持续迭代触发方式每次手动输入按任务自动或手动触发4. 环境准备与前置条件现在进入实操环节。我们不需要依赖某个特定平台的付费功能核心方法论可以在任何支持“自定义技能”或“工具调用”的 Agent 上落地。你只需要准备一个普通的开发环境。4.1 基础环境本文示例使用 Python 和 Shell涉及目录操作和文本处理。你不需要安装额外依赖只需要一个支持运行 Python 3 的终端环境Git可选用于版本管理技能库一个支持读取本地文件并调用脚本的 AI 客户端如 Claude Code、Cursor 等或任何支持 Skills 机制的工具。版本方面不做死板要求重点是思路。如果你使用的 Agent 工具暂不支持自定义技能目录也可以用“手动路径 CLI”的方式先跑通流程。4.2 准备技能目录建议先把技能放在独立目录中不要和业务代码混在一起。目录结构可以这样规划garden-skills/ ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── skill_check.py │ ├── commit-message/ │ │ ├── SKILL.md │ │ └── templates/ │ └── document-generator/ │ ├── SKILL.md │ └── reference/ └── README.md如果你已经克隆了某个开源技能库通常会看到类似结构。如果没有可以按上面的结构新建。创建目录mkdir -p ~/garden-skills/skills/code-review cd ~/garden-skills4.3 环境检查命令启动终端后先确认基本工具就绪python3 --version git --version如果这步失败说明你的机器缺少 Python 或 Git。考虑到后续脚本运行需要 Python建议先安装好对应版本。安全起见不要在技能脚本里使用 root 权限也不要让技能执行未经确认的危险命令。5. 从零构建一个 Skill代码规范检查下面我们用一个真实高频场景——代码规范检查——来演示完整流程。这个技能的目标是当开发者在提交前对 AI 说“检查这次改动”AI 能主动读取项目规范文件并输出问题清单。5.1 编写 SKILL.md在skills/code-review/下创建SKILL.md--- name: code-review description: 用于检查代码变更是否违反项目编码规范适合在提交前、Code Review 前使用。 version: 1.0.0 command: python3 skill_check.py tags: [code-review, quality, lint] --- # 代码规范检查技能 ## 触发时机 当用户要求“检查代码规范”、“Review 一下改动”、“提交前检查”时激活本技能。 ## 执行步骤 1. 检查当前目录下是否存在 .style-guide.md - 如果存在读取该文件作为检查依据 - 如果不存在提示用户补充规范文件路径。 2. 收集本次变更涉及的文件列表 3. 对每个文件执行 python3 skill_check.py file 4. 汇总输出格式如下问题清单文件src/main.py 问题未使用类型注解 严重级别P2 建议添加参数和返回值类型注解## 退出条件 完成输出后结束不要修改代码不执行 git commit。这个文件的重点是降低 Agent 的理解成本。description要写清触发条件正文要给出明确步骤和输出格式。AI 读到这里就不再需要你每次在对话框里重复规则。5.2 编写辅助脚本SKILL.md 负责“指挥”脚本负责“执行”。创建一个简单的 Python 脚本用于检查文件是否包含 TODO、是否使用了print()调试、是否缺少类型注解#!/usr/bin/env python3 # 文件路径garden-skills/skills/code-review/skill_check.py import re import sys from pathlib import Path def load_style_guide(project_root: Path) - list[str]: guide project_root / .style-guide.md if guide.exists(): return [line.strip() for line in guide.read_text(encodingutf-8).splitlines() if line.strip()] return [] def check_file(file_path: str) - list[dict]: issues [] path Path(file_path) if not path.exists(): issues.append({file: str(path), level: P0, message: 文件不存在}) return issues text path.read_text(encodingutf-8, errorsignore) if TODO in text: issues.append({file: str(path), level: P3, message: 存在 TODO请在合入前处理}) if print( in text: issues.append({file: str(path), level: P2, message: 疑似调试 print请使用日志}) if path.suffix .py: # 简单检查函数定义后面是否缺少类型注解 for match in re.finditer(r^def (\w)\(([^)]*)\):, text, re.MULTILINE): args match.group(2) if args and : not in args: issues.append({file: str(path), level: P2, message: f函数 {match.group(1)} 参数缺少类型注解}) return issues def main() - None: files sys.argv[1:] if not files: print(Usage: python3 skill_check.py file [file...]) sys.exit(1) all_issues [] for f in files: all_issues.extend(check_file(f)) if not all_issues: print(检查通过未发现问题。) return print(问题清单) for issue in all_issues: print(f- 文件{issue[file]}) print(f 问题{issue[message]}) print(f 严重级别{issue[level]}) if __name__ __main__: main()脚本逻辑并不复杂但它体现了技能的一个关键特点把容易遗漏的检查项变成自动化规则。后续团队可以持续往脚本里加规则比如限制函数长度、检查敏感信息、强制使用Optional等。5.3 准备一个测试用例为了验证技能能否正常工作我们创建一个待检查的 Python 文件# 文件路径~/garden-skills/example/main.py def add(a, b): # TODO: 后续需要对 a 和 b 做类型校验 print(result:, a b) return a b然后运行脚本cd ~/garden-skills python3 skills/code-review/skill_check.py example/main.py预期输出类似问题清单 - 文件example/main.py 问题存在 TODO请在合入前处理 严重级别P3 - 文件example/main.py 问题疑似调试 print请使用日志 严重级别P2 - 文件example/main.py 问题函数 add 参数缺少类型注解 严重级别P2到这里我们已经拥有了一个可以“被 Agent 调用”的最小技能。6. 把 Skills 接入 Agent 工作流写好 SKILL.md 之后关键在于怎么让 AI 在真实开发中使用它。不同工具接入方式不同但整体思路一致告诉 Agent 技能目录在哪里或者把技能目录配置成自动加载路径。6.1 方式一使用支持 Skills 的 Agent 客户端如果你使用的 Agent 客户端支持技能目录例如较新的 Claude Code、Cursor Rules、以及各类 Agent 框架通常只需要在配置文件中声明技能路径。假设配置文件为.agent/config.yaml示例配置如下skills: enabled: true paths: - ~/garden-skills/skills配置完成后Agent 会在任务开始时扫描该目录读取所有SKILL.md然后根据description字段决定是否调用。6.2 方式二通过项目内规则引用很多场景下你并不需要“全自动加载”只要在项目仓库中保留一份技能说明让 Agent 在回答问题时读取即可。例如在项目根目录添加一个.agent/skills.md文件里面引用技能# 本项目可用的 Agent 技能 ## code-review 使用方式向 Agent 发送“检查代码规范”。 Agent 请在收到指令后读取以下文件并执行 - 技能说明~/garden-skills/skills/code-review/SKILL.md - 辅助脚本~/garden-skills/skills/code-review/skill_check.py 执行时请遵循技能说明中的步骤。这种方式适合暂时不想配置自动加载的团队。你把规则写在仓库里Agent 只要读取到该文件就知道该调用哪个技能。6.3 方式三自定义 CLI 包装如果不想依赖 Agent 的自动技能机制也可以直接把技能实现为一个命令行工具。例如在.bashrc或.zshrc中添加alias skill-reviewpython3 ~/garden-skills/skills/code-review/skill_check.py然后在开发流程中直接使用skill-review example/main.py这种方式的好处是不依赖任何特定 Agent开发者自己也能使用脚本检查。它为团队提供了一个最底层的保障——即使 AI 调用失败人工依然可以通过命令行执行检查。7. 运行结果与效果验证技能接入后需要一套验证方法避免“看起来能用实际上不可靠”。7.1 验证维度建议从四个维度验证可发现性Agent 能否在技能目录中找到 code-review 技能如果找不到大概率是description写得太模糊或者目录路径配置错误。可理解性Agent 读取 SKILL.md 后是否能按步骤执行你可以故意问一句“怎么检查代码规范”观察 Agent 是否引用了技能内容。可执行性技能脚本是否能在目标文件上运行重点排查绝对路径、解释器路径、权限问题。可回归性同一份代码运行两次结果是否一致技能输出应该稳定不能每次推理出不同结论。7.2 模拟一次 Agent 对话假设你已经在客户端中配置好技能目录可以这样测试用户输入帮我检查一下 example/main.py 的代码规范如果技能生效Agent 会输出类似根据 code-review 技能的检查结果发现以下问题 1. 函数 add 参数缺少类型注解。 2. 存在调试用的 print建议替换为日志。 3. 存在 TODO 标记请在合入前处理。这个输出的关键是Agent 明确提到了技能名称且各项检查结果和脚本输出一致。这说明技能链路是通的。7.3 失败时如何定位如果 Agent 回复“我没有权限读取该文件”或者“找不到技能”第一步不是改提示词而是检查以下内容ls -l ~/garden-skills/skills/code-review/SKILL.md cat ~/garden-skills/skills/code-review/SKILL.md确认文件存在、内容完整、路径没有拼写错误。然后再看客户端配置里的技能路径是否使用了绝对路径。很多时候问题出在“相对路径的当前目录”和你预期的不一致。8. 常见问题与排查思路下面是实践中最高频的几类问题。建议先收藏这张表遇到问题时按顺序排查。问题现象可能原因排查方式解决方案Agent 找不到技能技能目录路径配置错误或未配置检查配置文件与实际目录路径是否一致使用绝对路径确认目录存在技能不自动触发description表述与用户任务不匹配查看 SKILL.md 顶部描述把触发条件写具体写入常见说法脚本执行失败Python 环境缺少依赖或解释器不存在运行python3 --version和脚本语法检查安装依赖或改用系统解释器技能输出不稳定SKILL.md 步骤不明确对照步骤逐步执行看哪一步有歧义补充退出条件、输入输出示例多个技能互相矛盾技能目录中存在重复或冲突规则列出所有 SKILL.md检查规则重叠合并同类技能明确优先级权限过于宽松技能脚本可操作敏感文件检查脚本读取路径和命令白名单限制脚本仅读取指定目录禁止执行任意命令上下文占用过高Agent 把所有技能都读进上下文查看日志中加载的 SKILL.md 列表启用按需加载只让 Agent 读取匹配技能团队共享困难技能放在个人目录未进入 Git检查项目仓库中是否有 skills 目录将技能库纳入统一仓库通过 MR/PR 协作每个问题背后其实都指向一个核心原则技能不是写完就结束而是要像代码一样持续维护。如果遇到“Agent 用了技能但效果不对”最有效的手段是给 SKILL.md 补充一个“典型错误输出”的示例告诉 Agent 什么样的情况不算完成。这一招比反复调整语气词有效得多。9. 最佳实践让技能花园持续生长技能库的成长需要规则。一个没有规范的技能库几个月后就会变成新的“提示词垃圾场”。下面这五条建议来自真实项目中的经验总结。9.1 用 Git 管理技能库把garden-skills目录放进 Git 仓库跟随项目一起版本管理。每次修改技能文件都走提交、评审流程。这样你就能看到一次技能修正确实改善了 AI 输出。Commit message 建议写清楚变更目标例如feat(code-review): 增加函数长度检查规则 fix(code-review): 修复 Windows 路径兼容问题9.2 文件名和技能名称要可检索技能名称不要叫my-skill、test这类无意义的名字。建议用“动作域”命名例如code-reviewcommit-messagetest-generationapi-docsecurity-audit命名之后在SKILL.md的description中再补充同义词和场景方便 Agent 检索。9.3 给技能写“反例”很多人写 SKILL.md 只写“做什么”不写“不做什么”。但 AI 恰恰需要反例来收敛行为。比如在 code-review 技能里明确写## 禁止事项 - 不要直接修改源代码 - 不要在问题清单中省略严重级别 - 如果规范文件不存在不要猜测规则必须提示用户补充。这会大幅减少 Agent 的“自由发挥”。9.4 定期清理合并技能技能库会不断膨胀。同一个“检查代码质量”的需求可能演化出三个技能。建议每季度做一次审计打开技能目录看看有没有重复、冲突、长期没人用的技能。删除不是浪费而是让剩余技能更突出。9.5 遵守最小权限原则技能脚本是运行在开发机上的代码安全边界一定要收紧。建议技能只读取必要目录不扫描整个文件系统不在技能脚本中硬编码任何密钥或 token涉及删除、移动、批量修改文件时先输出 dry-run 结果等待用户确认涉及生产环境操作时必须强制二次确认并保留变更日志。安全不是可有可无的附加项。一旦技能库被引入恶意技能文件Agent 就可能帮你执行危险命令。10. 总结与下一步garden-skills 带来的核心启示不是某个文件格式或者某个工具而是“把 AI 技能当作工程资产来经营”的思路。你可以没有漂亮的花园但不能不划好田地、不选择种子、不清理杂草。技能库的工程化水平最终决定 AI 在团队里的稳定性和可复制性。下一步建议你先不要追求大而全。从自己工作中最高频的三个场景入手比如代码审查、Commit Message 规范、接口文档生成。挑一个场景按文中步骤写出第一个 SKILL.md把它接入你的 Agent跑通一遍再邀请同事一起评审。当你发现 AI 的输出第一次稳定到不需要反复纠正时就会明白技能工程的价值。如果条件允许也可以把技能库打造成团队内部的开源项目。给技能写注释、写示例、写测试用例并保持仓库持续更新。这不仅是沉淀 AI 使用经验也是在把一个“个人技巧”变成“组织能力”的过程。祝你的技能花园越种越茂盛。 
长河君 · 2026/8/30 7:48:12 · 阅读 1.2k 从提示词到技能工程：用garden-skills构建可复用的AI Agent技能库
如果你最近在折腾 AI Agent 编程一定遇到过这样的场景同一个项目里让 AI 改代码时它总是“忘记”你的代码规范“提交前”让它自动检查测试它又得重新解释一遍规则团队里每个人都在各自的对话窗口里调教 AI但换个人、换个会话一切又从零开始。问题的本质不在于提示词写得不够好而在于你的 AI 使用经验没有被沉淀成可复用的工程资产。你缺的并不是一个更强的模型而是一套能把“高频指令、团队规范、私有工具”结构化组织起来的技能体系。这也是“garden-skills”这类项目值得关注的原因。从命名看它把 AI 技能组织成一个“花园”有分类、有土壤、有生长边界而不是把一堆 Prompt 随手堆在收藏夹里。如果你正在搭建团队级 AI 工作流或者想把手头的 AI 助手从“偶尔可用”提升到“稳定可用”这篇文章会给你一套可落地的思路以及可以直接上手的 Skill 编写方法。文章会从真实痛点出发先讲清楚 Agent Skills 的核心概念再用一个完整示例带你从零创建一个可复用的“代码规范检查”技能并把它接入常见 Agent 工作流。最后补充排错清单和工程化建议。即使你不打算原样使用某个仓库这套方法论也能直接迁移到你的项目中。1. 为什么你的 Agent 总是“不听话”先看一个普遍现象。很多人用 AI 编程助手时第一步是在对话里输入一大段“角色设定”比如你是一位资深 Java 工程师请遵循阿里巴巴开发规范修改代码前先输出影响面分析不要改变原有接口签名最后必须补充单元测试。这段话可能很有用但问题也很明显它只存在于当前会话中。下一次开会话你需要重新粘贴换一个同事他得自己写一遍甚至同一个任务只要换一个 AI 工具这套规则就彻底失效。从工程视角看这叫“上下文无法复用”。我们把大量时间花在重复解释规则上而不是解决真正的业务问题。更严重的是当规则越攒越多它们会变得相互矛盾、无法维护。一个典型的例子某个团队要求 AI“代码变更尽量小”同时又在另一个提示词里要求“统一重构所有使用旧 API 的地方”。两条规则冲突时AI 只能靠猜输出自然不稳定。与其说是 AI 不听话不如说我们从来没有给 AI 一套清晰、稳定、可检索的“操作手册”。而技能Skill体系本质上就是给 AI 写操作手册。1.1 从“提示词”到“技能”的转变传统的提示词是“一次性文本”输入给模型后就不再变动。技能则是一个“可复用的模块”它通常包含一段放在文件头部的说明Skill 名称、用途、适用场景一段指导模型如何执行的正文规则、步骤、示例可能还有配套脚本、模板、参考文档。garden-skills 这一系列仓库带来的启示是技能应该像代码一样管理。它们放在 Git 仓库里可以提交、评审、版本化、复用。你不需要把规则背下来而是把规则写进文件让 Agent 在需要时自动读取。这种转变的价值非常直接当技能文件被 AI 自动加载后你只需要说“按团队规范检查这次改动”AI 就会主动去读规范文件而不是靠你复制粘贴。团队里每个人使用同一套技能库输出口径自然一致。2. garden-skills 到底解决什么问题先做个简单的定位判断。如果你只是偶尔让 AI 写两段代码garden-skills 这类技能库对你可能有些“重”如果你的目标是把 AI 接入日常开发、Code Review、文档生成、测试补充等流程那它解决的是三个层次的问题。2.1 解决技能“放哪里”的问题在没有技能库之前大家的 Prompt 散落在聊天记录的置顶消息里个人笔记软件的收藏夹里公司 Wiki 的“AI 使用经验”页面里某个同事的电脑桌面上。这些位置有两个共同特点不可自动读取、不可版本管理。garden-skills 这类项目给出的答案是把所有技能放在一个固定目录结构中并用统一格式描述。Agent 在任务启动前可以“扫描”技能目录自动匹配最合适的技能。而不是靠用户手动在输入框里粘贴。2.2 解决技能“怎么用”的问题一个技能如果只写“请遵守编码规范”Agent 仍然不知道该做什么。garden-skills 所代表的技能格式要求你写清楚技能触发条件什么任务情况下使用执行步骤先做什么再做什么输入输出需要用户提供什么最终交付什么参考示例给 Agent 一段“标准答案”退出条件什么时候算完成。这其实就是把“经验”编码成“流程”。表面看是在给 AI 写文档实际上是在倒逼团队把隐性知识显性化。2.3 解决技能“怎么长”的问题花园的另一个特点是“可持续生长”。你可以先种下三五个核心技能之后再不断补充。随着新工具、新规范出现技能库可以迭代更新。如果只看表面你可能会把 garden-skills 当成一个“提示词模板合集”。但它的关键点在于“工程化组织”目录是分类的、文件是自描述的、技能是版本化的。这种设计让技能库可以像开源项目一样被协作维护。这也是它区别于普通收藏夹的核心。3. Agent Skills 的核心概念Skill、SKILL.md、技能编排在开始动手之前需要先统一几个概念。现在各家 Agent 产品对“技能”的实现不完全一致但绝大多数都遵循一个共同模式用文件描述技能按目录组织技能在运行时动态加载技能。3.1 Skill技能一个 Skill 是最小的可复用单元可以理解为“给 Agent 的一份能力说明书”。它可以是纯文本的指导也可以附带脚本和数据文件。例如一个“单元测试生成 Skill”可能包含说明文档告诉 Agent 什么时候生成测试、用什么测试框架、覆盖率要求是什么模板文件一个标准的测试文件模板辅助脚本解析当前项目测试配置的脚本。从工程角度说Skill 就是一个“带元数据的文件夹”。3.2 SKILL.md很多 Agent 技能体系中核心文件叫SKILL.md。这个文件是技能的入口通常采用 Markdown 格式头部带 YAML 或 TOML 元信息。下面的示例展示了常见结构--- name: code-style-review description: 用于检查代码是否符合项目编码规范适合在提交前或 Code Review 时使用。 version: 1.0.0 command: skill_check tags: [code-review, lint, quality] --- # 代码规范检查技能 当收到代码变更时按以下步骤执行 1. 读取项目根目录下的 .style-guide.md 文件 2. 检查变更文件是否违反规范 3. 输出问题清单按严重程度分组 4. 如果存在安全隐患额外标记 HIGHRISK。SKILL.md 的作用就是让 Agent “一眼看懂”这个技能什么时候用、怎么用。description字段尤其重要因为 Agent 通常靠它来判断当前任务要不要调用这个技能。3.3 技能编排Skill Orchestration技能编排是指 Agent 在响应任务时如何选择和组织多个技能。最简单的编排方式是“用户显式指定”比如你直接说“使用代码规范检查技能”。更高级的编排方式是“自动匹配”Agent 根据用户任务描述检索技能仓库中最合适的技能并加载。注意一个常见误区技能编排不是把所有技能一股脑塞进上下文。这样做会迅速耗尽上下文窗口还会让模型纠结到底该听谁的。好的编排是“按需加载”让 Agent 先识别任务类型再读取少量技能文件。表格普通 Prompt 与 Skill 的差异维度普通 PromptSkill 技能存储位置聊天记录、个人笔记统一目录、Git 仓库是否可版本管理通常不可可与代码一起管理自动加载不支持可被 Agent 自动识别团队共享靠复制粘贴靠仓库协作维护方式容易过期可持续迭代触发方式每次手动输入按任务自动或手动触发4. 环境准备与前置条件现在进入实操环节。我们不需要依赖某个特定平台的付费功能核心方法论可以在任何支持“自定义技能”或“工具调用”的 Agent 上落地。你只需要准备一个普通的开发环境。4.1 基础环境本文示例使用 Python 和 Shell涉及目录操作和文本处理。你不需要安装额外依赖只需要一个支持运行 Python 3 的终端环境Git可选用于版本管理技能库一个支持读取本地文件并调用脚本的 AI 客户端如 Claude Code、Cursor 等或任何支持 Skills 机制的工具。版本方面不做死板要求重点是思路。如果你使用的 Agent 工具暂不支持自定义技能目录也可以用“手动路径 CLI”的方式先跑通流程。4.2 准备技能目录建议先把技能放在独立目录中不要和业务代码混在一起。目录结构可以这样规划garden-skills/ ├── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── skill_check.py │ ├── commit-message/ │ │ ├── SKILL.md │ │ └── templates/ │ └── document-generator/ │ ├── SKILL.md │ └── reference/ └── README.md如果你已经克隆了某个开源技能库通常会看到类似结构。如果没有可以按上面的结构新建。创建目录mkdir -p ~/garden-skills/skills/code-review cd ~/garden-skills4.3 环境检查命令启动终端后先确认基本工具就绪python3 --version git --version如果这步失败说明你的机器缺少 Python 或 Git。考虑到后续脚本运行需要 Python建议先安装好对应版本。安全起见不要在技能脚本里使用 root 权限也不要让技能执行未经确认的危险命令。5. 从零构建一个 Skill代码规范检查下面我们用一个真实高频场景——代码规范检查——来演示完整流程。这个技能的目标是当开发者在提交前对 AI 说“检查这次改动”AI 能主动读取项目规范文件并输出问题清单。5.1 编写 SKILL.md在skills/code-review/下创建SKILL.md--- name: code-review description: 用于检查代码变更是否违反项目编码规范适合在提交前、Code Review 前使用。 version: 1.0.0 command: python3 skill_check.py tags: [code-review, quality, lint] --- # 代码规范检查技能 ## 触发时机 当用户要求“检查代码规范”、“Review 一下改动”、“提交前检查”时激活本技能。 ## 执行步骤 1. 检查当前目录下是否存在 .style-guide.md - 如果存在读取该文件作为检查依据 - 如果不存在提示用户补充规范文件路径。 2. 收集本次变更涉及的文件列表 3. 对每个文件执行 python3 skill_check.py file 4. 汇总输出格式如下问题清单文件src/main.py 问题未使用类型注解 严重级别P2 建议添加参数和返回值类型注解## 退出条件 完成输出后结束不要修改代码不执行 git commit。这个文件的重点是降低 Agent 的理解成本。description要写清触发条件正文要给出明确步骤和输出格式。AI 读到这里就不再需要你每次在对话框里重复规则。5.2 编写辅助脚本SKILL.md 负责“指挥”脚本负责“执行”。创建一个简单的 Python 脚本用于检查文件是否包含 TODO、是否使用了print()调试、是否缺少类型注解#!/usr/bin/env python3 # 文件路径garden-skills/skills/code-review/skill_check.py import re import sys from pathlib import Path def load_style_guide(project_root: Path) - list[str]: guide project_root / .style-guide.md if guide.exists(): return [line.strip() for line in guide.read_text(encodingutf-8).splitlines() if line.strip()] return [] def check_file(file_path: str) - list[dict]: issues [] path Path(file_path) if not path.exists(): issues.append({file: str(path), level: P0, message: 文件不存在}) return issues text path.read_text(encodingutf-8, errorsignore) if TODO in text: issues.append({file: str(path), level: P3, message: 存在 TODO请在合入前处理}) if print( in text: issues.append({file: str(path), level: P2, message: 疑似调试 print请使用日志}) if path.suffix .py: # 简单检查函数定义后面是否缺少类型注解 for match in re.finditer(r^def (\w)\(([^)]*)\):, text, re.MULTILINE): args match.group(2) if args and : not in args: issues.append({file: str(path), level: P2, message: f函数 {match.group(1)} 参数缺少类型注解}) return issues def main() - None: files sys.argv[1:] if not files: print(Usage: python3 skill_check.py file [file...]) sys.exit(1) all_issues [] for f in files: all_issues.extend(check_file(f)) if not all_issues: print(检查通过未发现问题。) return print(问题清单) for issue in all_issues: print(f- 文件{issue[file]}) print(f 问题{issue[message]}) print(f 严重级别{issue[level]}) if __name__ __main__: main()脚本逻辑并不复杂但它体现了技能的一个关键特点把容易遗漏的检查项变成自动化规则。后续团队可以持续往脚本里加规则比如限制函数长度、检查敏感信息、强制使用Optional等。5.3 准备一个测试用例为了验证技能能否正常工作我们创建一个待检查的 Python 文件# 文件路径~/garden-skills/example/main.py def add(a, b): # TODO: 后续需要对 a 和 b 做类型校验 print(result:, a b) return a b然后运行脚本cd ~/garden-skills python3 skills/code-review/skill_check.py example/main.py预期输出类似问题清单 - 文件example/main.py 问题存在 TODO请在合入前处理 严重级别P3 - 文件example/main.py 问题疑似调试 print请使用日志 严重级别P2 - 文件example/main.py 问题函数 add 参数缺少类型注解 严重级别P2到这里我们已经拥有了一个可以“被 Agent 调用”的最小技能。6. 把 Skills 接入 Agent 工作流写好 SKILL.md 之后关键在于怎么让 AI 在真实开发中使用它。不同工具接入方式不同但整体思路一致告诉 Agent 技能目录在哪里或者把技能目录配置成自动加载路径。6.1 方式一使用支持 Skills 的 Agent 客户端如果你使用的 Agent 客户端支持技能目录例如较新的 Claude Code、Cursor Rules、以及各类 Agent 框架通常只需要在配置文件中声明技能路径。假设配置文件为.agent/config.yaml示例配置如下skills: enabled: true paths: - ~/garden-skills/skills配置完成后Agent 会在任务开始时扫描该目录读取所有SKILL.md然后根据description字段决定是否调用。6.2 方式二通过项目内规则引用很多场景下你并不需要“全自动加载”只要在项目仓库中保留一份技能说明让 Agent 在回答问题时读取即可。例如在项目根目录添加一个.agent/skills.md文件里面引用技能# 本项目可用的 Agent 技能 ## code-review 使用方式向 Agent 发送“检查代码规范”。 Agent 请在收到指令后读取以下文件并执行 - 技能说明~/garden-skills/skills/code-review/SKILL.md - 辅助脚本~/garden-skills/skills/code-review/skill_check.py 执行时请遵循技能说明中的步骤。这种方式适合暂时不想配置自动加载的团队。你把规则写在仓库里Agent 只要读取到该文件就知道该调用哪个技能。6.3 方式三自定义 CLI 包装如果不想依赖 Agent 的自动技能机制也可以直接把技能实现为一个命令行工具。例如在.bashrc或.zshrc中添加alias skill-reviewpython3 ~/garden-skills/skills/code-review/skill_check.py然后在开发流程中直接使用skill-review example/main.py这种方式的好处是不依赖任何特定 Agent开发者自己也能使用脚本检查。它为团队提供了一个最底层的保障——即使 AI 调用失败人工依然可以通过命令行执行检查。7. 运行结果与效果验证技能接入后需要一套验证方法避免“看起来能用实际上不可靠”。7.1 验证维度建议从四个维度验证可发现性Agent 能否在技能目录中找到 code-review 技能如果找不到大概率是description写得太模糊或者目录路径配置错误。可理解性Agent 读取 SKILL.md 后是否能按步骤执行你可以故意问一句“怎么检查代码规范”观察 Agent 是否引用了技能内容。可执行性技能脚本是否能在目标文件上运行重点排查绝对路径、解释器路径、权限问题。可回归性同一份代码运行两次结果是否一致技能输出应该稳定不能每次推理出不同结论。7.2 模拟一次 Agent 对话假设你已经在客户端中配置好技能目录可以这样测试用户输入帮我检查一下 example/main.py 的代码规范如果技能生效Agent 会输出类似根据 code-review 技能的检查结果发现以下问题 1. 函数 add 参数缺少类型注解。 2. 存在调试用的 print建议替换为日志。 3. 存在 TODO 标记请在合入前处理。这个输出的关键是Agent 明确提到了技能名称且各项检查结果和脚本输出一致。这说明技能链路是通的。7.3 失败时如何定位如果 Agent 回复“我没有权限读取该文件”或者“找不到技能”第一步不是改提示词而是检查以下内容ls -l ~/garden-skills/skills/code-review/SKILL.md cat ~/garden-skills/skills/code-review/SKILL.md确认文件存在、内容完整、路径没有拼写错误。然后再看客户端配置里的技能路径是否使用了绝对路径。很多时候问题出在“相对路径的当前目录”和你预期的不一致。8. 常见问题与排查思路下面是实践中最高频的几类问题。建议先收藏这张表遇到问题时按顺序排查。问题现象可能原因排查方式解决方案Agent 找不到技能技能目录路径配置错误或未配置检查配置文件与实际目录路径是否一致使用绝对路径确认目录存在技能不自动触发description表述与用户任务不匹配查看 SKILL.md 顶部描述把触发条件写具体写入常见说法脚本执行失败Python 环境缺少依赖或解释器不存在运行python3 --version和脚本语法检查安装依赖或改用系统解释器技能输出不稳定SKILL.md 步骤不明确对照步骤逐步执行看哪一步有歧义补充退出条件、输入输出示例多个技能互相矛盾技能目录中存在重复或冲突规则列出所有 SKILL.md检查规则重叠合并同类技能明确优先级权限过于宽松技能脚本可操作敏感文件检查脚本读取路径和命令白名单限制脚本仅读取指定目录禁止执行任意命令上下文占用过高Agent 把所有技能都读进上下文查看日志中加载的 SKILL.md 列表启用按需加载只让 Agent 读取匹配技能团队共享困难技能放在个人目录未进入 Git检查项目仓库中是否有 skills 目录将技能库纳入统一仓库通过 MR/PR 协作每个问题背后其实都指向一个核心原则技能不是写完就结束而是要像代码一样持续维护。如果遇到“Agent 用了技能但效果不对”最有效的手段是给 SKILL.md 补充一个“典型错误输出”的示例告诉 Agent 什么样的情况不算完成。这一招比反复调整语气词有效得多。9. 最佳实践让技能花园持续生长技能库的成长需要规则。一个没有规范的技能库几个月后就会变成新的“提示词垃圾场”。下面这五条建议来自真实项目中的经验总结。9.1 用 Git 管理技能库把garden-skills目录放进 Git 仓库跟随项目一起版本管理。每次修改技能文件都走提交、评审流程。这样你就能看到一次技能修正确实改善了 AI 输出。Commit message 建议写清楚变更目标例如feat(code-review): 增加函数长度检查规则 fix(code-review): 修复 Windows 路径兼容问题9.2 文件名和技能名称要可检索技能名称不要叫my-skill、test这类无意义的名字。建议用“动作域”命名例如code-reviewcommit-messagetest-generationapi-docsecurity-audit命名之后在SKILL.md的description中再补充同义词和场景方便 Agent 检索。9.3 给技能写“反例”很多人写 SKILL.md 只写“做什么”不写“不做什么”。但 AI 恰恰需要反例来收敛行为。比如在 code-review 技能里明确写## 禁止事项 - 不要直接修改源代码 - 不要在问题清单中省略严重级别 - 如果规范文件不存在不要猜测规则必须提示用户补充。这会大幅减少 Agent 的“自由发挥”。9.4 定期清理合并技能技能库会不断膨胀。同一个“检查代码质量”的需求可能演化出三个技能。建议每季度做一次审计打开技能目录看看有没有重复、冲突、长期没人用的技能。删除不是浪费而是让剩余技能更突出。9.5 遵守最小权限原则技能脚本是运行在开发机上的代码安全边界一定要收紧。建议技能只读取必要目录不扫描整个文件系统不在技能脚本中硬编码任何密钥或 token涉及删除、移动、批量修改文件时先输出 dry-run 结果等待用户确认涉及生产环境操作时必须强制二次确认并保留变更日志。安全不是可有可无的附加项。一旦技能库被引入恶意技能文件Agent 就可能帮你执行危险命令。10. 总结与下一步garden-skills 带来的核心启示不是某个文件格式或者某个工具而是“把 AI 技能当作工程资产来经营”的思路。你可以没有漂亮的花园但不能不划好田地、不选择种子、不清理杂草。技能库的工程化水平最终决定 AI 在团队里的稳定性和可复制性。下一步建议你先不要追求大而全。从自己工作中最高频的三个场景入手比如代码审查、Commit Message 规范、接口文档生成。挑一个场景按文中步骤写出第一个 SKILL.md把它接入你的 Agent跑通一遍再邀请同事一起评审。当你发现 AI 的输出第一次稳定到不需要反复纠正时就会明白技能工程的价值。如果条件允许也可以把技能库打造成团队内部的开源项目。给技能写注释、写示例、写测试用例并保持仓库持续更新。这不仅是沉淀 AI 使用经验也是在把一个“个人技巧”变成“组织能力”的过程。祝你的技能花园越种越茂盛。