1. 项目概述构建你的AI Agent技能库如果你和我一样在日常开发中频繁地与Claude、Cursor、GitHub Copilot这类AI助手打交道那你一定遇到过这样的困扰每次开启一个新项目或者切换一个工作场景你都需要不厌其烦地向AI重复你的技术偏好、编码规范、项目结构要求。比如你总是习惯用pnpm而不是npm喜欢把组件放在src/components/ui目录下代码注释必须遵循特定的JSDoc格式。重复沟通不仅低效更关键的是AI助手缺乏“上下文记忆”它无法像人类搭档一样逐渐熟悉你的工作习惯。这正是alexleekt/agents这个项目试图解决的核心痛点。它不是一个复杂的AI框架而是一个轻量级、可移植的AI Agent配置与技能库。你可以把它理解为你个人或团队的“AI偏好说明书”和“技能工具包”。通过一套结构化的YAML配置文件和技能定义它能系统性地告诉不同的AI助手Claude、Cursor、Codex、Copilot、Gemini等“我是谁我习惯怎么工作我的项目通常长什么样。” 其核心价值在于将你碎片化的、存在于对话历史中的偏好和规则沉淀为可版本化、可共享、可迭代的资产从而实现与AI协作的“一次定义处处生效”。2. 项目架构与核心设计思路2.1 目录结构深度解析项目的目录结构非常清晰遵循了“配置、规则、技能”分离的设计哲学这背后体现了良好的工程化思维。agents/ ├── README.md # 项目总览与使用指南 ├── config.yaml # 核心配置文件Saddle配置 ├── rules/ # 按AI工具划分的同步规则 │ ├── claude.yaml │ ├── codex.yaml │ ├── copilot.yaml │ ├── cursor.yaml │ ├── gemini.yaml │ └── opencode.yaml └── skills/ # 可复用的Agent技能包 ├── my-agent-rules/ └── my-tech-stack/config.yaml(Saddle配置)这是整个系统的“大脑”。Saddle在这里可以理解为一个配置管理与分发的“引擎”或“适配器”。它的核心职责是读取skills/目录下定义的各种技能并根据rules/目录下针对不同AI工具的规则文件将技能“编译”或“适配”成对应AI工具能理解并接受的提示词Prompt或配置文件。例如它知道如何将你定义的“我的技术栈”技能转换成Claude可以接受的系统指令或者Cursor可以读取的.cursorrules文件内容。rules/目录这是“翻译官”或“适配层”。不同的AI工具有不同的交互方式和配置能力。Claude可能通过长篇的系统指令工作Cursor有自己的.cursorrules文件GitHub Copilot则可能依赖仓库中的copilot/目录下的提示词。rules/目录下的每个YAML文件都定义了一套如何将通用“技能”映射到特定工具的具体规则。这种设计保证了技能定义的通用性与工具适配的灵活性之间的平衡。skills/目录这是“知识库”或“技能包”。这里存放着你希望所有AI助手都掌握的、可复用的核心知识。my-tech-stack可能包含了你偏爱的前端框架如Next.js 14 App Router、UI库如shadcn/ui、状态管理Zustand、包管理器pnpm等。my-agent-rules则可能定义了AI在项目中应遵循的通用行为准则比如“永远先检查现有的AGENT.md文件”、“修改代码时必须同时更新对应的单元测试”等。技能是模块化的你可以随时新增例如my-api-conventions来定义你的REST API规范。设计心路为什么采用“技能(Skills)”和“规则(Rules)”分离早期我尝试过为每个工具写一份完整的提示词但维护成本极高。一旦我的技术栈从React换到Vue我需要修改claude.yaml、cursor.yaml、copilot.yaml等所有文件。分离后我只需更新skills/my-tech-stack这一个源头所有工具的规则文件通过引用这个技能就能自动获得更新。这本质上是“关注点分离”和“单一数据源”原则的实践。2.2 核心概念技能Skills与规则Rules的协同理解技能和规则的协同工作流是掌握这个项目的关键。我们可以通过一个具体的例子来串联整个流程技能定义Source of Truth你在skills/my-tech-stack/spec.yaml中定义name: my-tech-stack description: 我的个人前端技术栈偏好 content: | 前端框架Next.js 14 (使用App Router) UI组件库shadcn/ui Tailwind CSS 状态管理Zustand (用于客户端状态)React Query/TanStack Query (用于服务端状态) 包管理器pnpm (请优先使用pnpm install) 代码风格使用ESLint (配置为airbnb-base) 和 Prettier 进行格式化 提交规范遵循Conventional Commits规则适配Tool-Specific Adaptation在rules/claude.yaml中你编写规则告诉Saddle如何为Claude使用这个技能target: claude skills: - ref: my-tech-stack # 指示Saddle如何将这个技能插入到给Claude的提示词中 transform: | 你是一个精通以下技术栈的助手在提供建议或编写代码时请优先考虑和遵循这些选择 {{ skill.content }}而在rules/cursor.yaml中规则可能完全不同因为它需要生成一个.cursorrules文件target: cursor output: .cursorrules # 指定输出文件名 skills: - ref: my-tech-stack transform: | # 技术栈偏好 {{ skill.content | to_cursor_rules_format }} # 假设有一个格式转换函数配置驱动与生成Orchestrationconfig.yaml中的Saddle配置会指明如何处理这些规则。当你运行saddle sync或类似的命令时Saddle引擎会读取config.yaml。加载所有在rules/中定义的规则。对于每条规则找到其引用的技能如my-tech-stack。应用规则中定义的transform转换逻辑将技能内容适配成目标工具所需的格式。将最终内容输出到指定位置如直接注入Claude对话或生成.cursorrules文件到项目根目录。这个过程实现了“一处定义多处同步”极大降低了维护成本。3. 核心技能配置与实操要点3.1 技能Skills的创建与维护技能是项目的基石。创建技能不仅仅是罗列技术更是对你工作流和思维模式的抽象。技能内容的结构化建议 一个优秀的技能文件应该超越简单的列表提供上下文和优先级。例如my-tech-stack技能可以这样组织# skills/my-tech-stack/spec.yaml name: my-tech-stack description: 个人全栈开发技术栈与首选方案 content: | # 核心原则 - **优先级**稳定性 开发者体验 性能 新颖性。不盲目追求新技术。 - **一致性**在同一项目中保持技术选型一致。 # 前端层 (Primary) - **框架**: Next.js 14 (App Router)。除非项目极简否则不选用纯React Vite。 - **语言**: TypeScript (严格模式)。禁用any类型。 - **样式**: Tailwind CSS class-variance-authority 构建可复用组件变体。全局样式文件为app/globals.css。 - **组件**: 基于 shadcn/ui 进行二次封装。所有通用组件置于src/components/ui。 - **状态**: - 服务端状态: TanStack Query v5。查询键统一使用[resource, id]格式数组。 - 客户端状态: Zustand。Store文件置于src/stores。 - **HTTP客户端**: axios 配合自定义拦截器处理鉴权与错误。 # 后端层 (Node.js) - **运行时**: Node.js 18 (LTS版本)。 - **框架**: Express.js 或 Next.js API Routes (视项目而定)。 - **ORM**: Prisma。Schema文件必须位于prisma/schema.prisma。 - **认证**: NextAuth.js (用于Next.js项目) 或 JWT。 # 开发工具链 - **包管理器**: pnpm。请使用pnpm install并在建议命令时优先使用pnpm。 - **代码质量**: ESLint (配置扩展rocketseat/eslint-config)Prettier。 - **提交**: commitlint husky 强制 Conventional Commits。 - **容器化**: Docker Docker Compose。开发环境配置见docker-compose.dev.yml。 # 遇到以下场景的默认选择 - 需要图标库: lucide-react - 需要日期处理: date-fns - 需要表单处理: React Hook Form Zod (用于校验)my-agent-rules技能示例 这个技能定义了AI助手本身的行为准则是“元技能”。# skills/my-agent-rules/spec.yaml name: my-agent-rules description: 指导AI助手如何与我协作的规则 content: | # 项目初始探查 1. 开始工作前**必须**首先检查项目根目录是否存在以下文件并按优先级读取 a. AGENT.md - 项目级最高优先级指令。 b. .cursorrules - Cursor专用规则。 c. claude.md - Claude专用指令。 2. 如果存在package.json快速扫描dependencies和devDependencies以了解项目技术栈。 # 代码交互规范 3. 在修改任何现有文件前先理解其上下文和现有模式。保持代码风格一致。 4. 提供代码时**必须**同时提供清晰的解释说明“做了什么”和“为什么这么做”。 5. 如果被要求实现一个功能优先考虑使用项目中已存在的工具库或模式而不是引入新依赖。 6. 当建议添加新依赖时必须同时说明其大小、维护状态和替代方案。 # 文件与目录操作 7. 创建新组件时路径应为src/components/[category]/ComponentName.tsx。 8. 工具函数应放在src/lib/utils.ts或src/lib/[module]-utils.ts中。 # 沟通风格 9. 回答应直接、务实避免不必要的客套话。可以适当使用emoji如✅、⚠️提高可读性但非必须。实操心得技能的粒度把控技能不宜过大或过小。一个常见的错误是把所有东西塞进一个技能。我建议按领域划分frontend-stackbackend-stackdevops-practicescode-review-guidelines。这样更易于维护和组合。例如一个Node.js后端项目可能只需要引用backend-stack和devops-practices。3.2 规则Rules的编写与适配规则文件是连接通用技能和具体AI工具的桥梁。编写规则的关键在于深刻理解目标AI工具的工作机制。Claude规则 (rules/claude.yaml) 详解 Claude通常通过一个强大的“系统提示词”来设定角色和行为。我们的规则就是要生成或补充这个提示词。# rules/claude.yaml target: claude # 指定输出方式可能是注入到Claude的“自定义指令”或项目特定的claude.md文件 output_mode: append_to_system_prompt # 触发条件当在项目根目录或agents目录下工作时生效 trigger: - path_contains: /agents/ - file_exists: claude.md # 引入的技能 skills: - ref: my-tech-stack # transform字段定义了如何将技能内容嵌入到给Claude的指令中 transform: | ## 技术栈与开发规范 你是我的技术搭档熟悉并遵循我偏爱的技术栈和开发流程 {{ skill.content }} 在以下方面请特别注意 1. 当被问及技术选型建议时优先推荐上述技术栈中的工具。 2. 在编写代码示例时默认使用上述技术栈如用TypeScript而非JavaScript。 3. 如果我的请求与上述规范冲突例如要求用npm而你看到项目用的是pnpm请礼貌地提醒我。 - ref: my-agent-rules transform: | ## 协作与工作流程 此外请遵守以下协作规则 {{ skill.content }} # 特别强调 - 在开始回答任何编码问题前请先确认“我已阅读项目规范。当前项目技术栈是 [根据package.json推断]这与我的知识库 [一致/略有不同]我将以项目现有规范为准进行后续操作。”Cursor规则 (rules/cursor.yaml) 详解 Cursor通过项目根目录的.cursorrules文件来获得指导。这个文件是纯文本的规则需要生成符合其语法的内容。# rules/cursor.yaml target: cursor # 输出为项目根目录的 .cursorrules 文件 output: .cursorrules # 覆盖模式merge合并或 overwrite覆盖。通常merge更安全。 mode: merge skills: - ref: my-tech-stack transform: | # 技术栈偏好 (来自 my-tech-stack) {{ skill.content | indent: 6 }} # 假设indent过滤器用于格式对齐 - ref: my-agent-rules transform: | # 代理行为规则 (来自 my-agent-rules) {{ skill.content | indent: 6 }} # Cursor 特定规则 - 当使用引用文件时请确保路径正确。 - 生成代码后如果可能请自动运行相关的lint命令如pnpm lint并报告结果。GitHub Copilot规则 (rules/copilot.yaml) 思考 Copilot的配置更隐晦它可能通过仓库中的copilot/目录下的提示词文件或者通过注释来影响。规则可能需要生成类似copilot/README.md或特定代码片段中的提示注释。# rules/copilot.yaml target: copilot output_dir: .github/copilot # Copilot可能会读取这个目录 skills: - ref: my-tech-stack transform: | !-- 开发者技术栈偏好 -- !-- {{ skill.content | replace: \n, \n }} -- !-- 在建议代码补全时请优先考虑上述技术栈。 --注意事项规则的幂等性与安全性规则文件的transform操作和output模式必须谨慎设计。特别是mode: overwrite它可能会覆盖项目中已有的、有价值的自定义规则。最佳实践是优先使用merge将你的通用规则与项目已有规则合并。添加明显标记在生成的规则内容中用注释包裹标明“此部分由Saddle从my-tech-stack技能自动生成”便于识别和手动调整。版本控制将生成的规则文件如.cursorrules也纳入.gitignore这取决于团队策略。我个人倾向于不提交让每个开发者根据本地的agents配置自动生成这样可以保证个性化。4. 从零开始搭建与集成工作流4.1 初始化你的Agents配置库假设你已经在本地有一个agents目录可以从模板仓库克隆或自行创建以下是详细的初始化步骤创建核心目录结构mkdir -p ~/projects/my-agent-config cd ~/projects/my-agent-config mkdir -p skills/my-tech-stack skills/my-agent-rules rules touch config.yaml README.md编写基础config.yaml# config.yaml version: 1.0 name: 我的AI助手配置 # 指定技能和规则的根目录支持相对或绝对路径 skills_dir: ./skills rules_dir: ./rules # 输出配置定义规则应用后生成文件的位置和行为 outputs: # 对于Claude可能是在对话开始时手动粘贴的系统提示词片段 # 这里我们可以定义一个“预览”命令来查看生成的内容 claude: action: preview # 预览不直接写入文件 format: markdown # 对于Cursor生成项目本地的 .cursorrules 文件 cursor: action: write file: .cursorrules mode: merge # 合并模式 # 对于通用场景可以生成一个汇总的 AGENT.md 文件 default: action: write file: AGENT.md mode: overwrite填充你的第一个技能按照3.1节的示例创建skills/my-tech-stack/spec.yaml和skills/my-agent-rules/spec.yaml。编写工具规则按照3.2节的示例创建rules/claude.yaml和rules/cursor.yaml。4.2 与Saddle引擎或自定义脚本集成原项目提到了“Saddle configuration”但Saddle可能是一个特定工具或内部脚本。其核心功能是解析配置、加载技能、应用规则并输出。我们可以模拟其工作原理创建一个简单的Python脚本作为“引擎”# saddle_cli.py (简化示例) import os import yaml import glob def load_skill(skill_name, skills_dir): 从skills_dir加载指定名称的技能 skill_path os.path.join(skills_dir, skill_name, spec.yaml) if not os.path.exists(skill_path): raise FileNotFoundError(fSkill {skill_name} not found at {skill_path}) with open(skill_path, r, encodingutf-8) as f: return yaml.safe_load(f) def apply_rule(rule_config, skills_dir): 应用单个规则生成目标内容 target rule_config.get(target) output rule_config.get(output, AGENT.md) # 默认输出文件 mode rule_config.get(mode, overwrite) generated_content [] for skill_ref in rule_config.get(skills, []): skill_name skill_ref.get(ref) skill_data load_skill(skill_name, skills_dir) transform_template skill_ref.get(transform, {{ skill.content }}) # 简单的模板渲染实际可使用Jinja2 transformed transform_template.replace({{ skill.content }}, skill_data.get(content, )) generated_content.append(transformed) final_content \n\n.join(generated_content) # 处理输出写入文件或打印预览 if rule_config.get(action) preview: print(f\n--- 预览 for {target} ---\n) print(final_content) print(f\n--- 结束预览 ---\n) else: # write write_to_file(output, final_content, mode) return final_content def write_to_file(filename, content, mode): 根据模式写入文件 if mode overwrite or not os.path.exists(filename): with open(filename, w, encodingutf-8) as f: f.write(content) print(f[OK] 已写入文件: {filename}) elif mode merge: # 简单的合并逻辑读取原有内容追加新内容 existing if os.path.exists(filename): with open(filename, r, encodingutf-8) as f: existing f.read() # 避免重复合并相同来源的内容这里简化处理 marker f# --- 自动生成自 agents 配置 --- if marker in existing: # 找到标记并替换之后的内容 parts existing.split(marker) new_content parts[0].rstrip() \n\n marker \n content else: new_content existing \n\n marker \n content with open(filename, w, encodingutf-8) as f: f.write(new_content) print(f[OK] 已合并写入文件: {filename}) def main(): # 加载主配置 with open(config.yaml, r) as f: config yaml.safe_load(f) skills_dir config.get(skills_dir, ./skills) rules_dir config.get(rules_dir, ./rules) # 遍历所有规则文件 rule_files glob.glob(os.path.join(rules_dir, *.yaml)) for rule_file in rule_files: with open(rule_file, r) as f: rule_config yaml.safe_load(f) print(f处理规则: {rule_config.get(target)} from {os.path.basename(rule_file)}) apply_rule(rule_config, skills_dir) if __name__ __main__: main()你可以通过运行python saddle_cli.py来执行这个脚本它将会读取config.yaml和所有规则然后根据规则生成对应的文件如.cursorrules或打印预览内容。4.3 集成到日常开发工作流为了让配置生效你需要将其集成到你的工作流中作为全局配置将你的agents目录放在一个固定位置如~/.config/agents并修改config.yaml中的路径。在你任何项目的根目录运行一个命令如apply-agent-config来将全局配置应用到当前项目。作为项目模板的一部分如果你使用项目模板如create-next-app自定义模板可以将agents目录和生成脚本一起打包。新项目初始化时自动运行脚本生成对应的AI助手规则文件。IDE/编辑器插件理论上可以开发一个VS Code或Cursor插件监听agents目录下配置的更改并自动更新对应的规则文件。Git Hook在项目的.git/hooks/post-checkout或post-merge钩子中加入运行配置同步脚本的命令确保每次切换分支或拉取代码后本地的AI助手规则都是最新的。我的工作流我采用的是“全局配置项目覆盖”的模式。我有一个存放在私有Git仓库的全局agents配置。在我的Shell配置如.zshrc中我设置了一个别名alias agent-syncpython ~/.config/agents/saddle_cli.py。当我进入任何一个项目目录只需运行agent-sync它就会读取全局配置并在当前项目生成或更新.cursorrules和AGENT.md文件。如果某个项目有特殊要求我可以在项目内创建一个local.rules.yaml文件来覆盖或补充全局规则。5. 高级技巧、问题排查与未来演进5.1 技能的组合、继承与条件化当你的技能库变得庞大时你需要更精细的管理策略。技能组合一个规则可以引用多个技能。例如一个“全栈项目”规则可以同时引用frontend-stack、backend-stack和devops-practices。技能继承你可以创建基础技能和衍生技能。例如一个base-react-stack定义了通用的React规范而nextjs-stack继承它并添加Next.js特有的规则。这可以通过在技能YAML中使用extends字段来实现需要在Saddle引擎中支持此特性。条件化技能技能内容可以根据环境变量或项目特征动态变化。例如在my-tech-stack中你可以这样写content: | 包管理器: {{ env.PACKAGE_MANAGER | default: pnpm }} 如果项目包含 docker-compose.yml则默认服务已容器化。这需要Saddle引擎支持简单的模板条件判断。5.2 常见问题与排查清单在实际使用中你可能会遇到以下问题问题现象可能原因排查步骤与解决方案AI助手完全忽略生成的规则文件如.cursorrules。1. 文件位置错误。2. 文件格式或语法错误。3. AI工具未启用或未正确识别该文件。1.确认位置确保.cursorrules在项目根目录与.git同级。对于Claude的系统指令需在对话设置中手动粘贴。2.检查语法规则文件应是纯文本或Markdown避免特殊字符错误。3.重启工具关闭并重新打开Cursor或Claude对话确保其重新读取配置文件。规则合并(mode: merge)导致内容重复或冲突。合并逻辑有缺陷或多次运行脚本。1.检查合并逻辑确保你的saddle_cli.py脚本中的write_to_file函数能正确处理标记和去重。2.使用版本控制将生成的文件纳入.gitignore避免提交后合并冲突。或在生成内容顶部添加“此文件由工具生成请勿手动编辑”的警告并始终使用overwrite模式。技能更新后生成的规则文件未同步更新。1. 脚本未重新运行。2. 缓存问题。1.手动触发运行同步命令如agent-sync。2.考虑监听机制使用nodemon等工具监听skills/和rules/目录变化自动触发同步。3.清除缓存某些AI工具如Cursor可能会缓存规则尝试重启工具或清除其缓存目录。不同项目的技术栈差异巨大全局配置不适用。技能缺乏条件判断或项目特异性覆盖。1.创建项目级技能在项目内创建skills/project-specific目录并在项目级的config.yaml中优先引用它。2.使用条件技能如上文所述在技能内容中通过简单判断来适应不同项目需要引擎支持。3.最实用方案在项目根目录放置一个高优先级的AGENT.md其中明确说明本项目与全局规范的差异并指示AI优先遵循此文件。5.3 项目的潜在演进方向alexleekt/agents项目提供了一个优雅的范式但它的实现尤其是Saddle部分可能比较轻量。你可以基于这个思想进行扩展开发图形化配置界面一个本地Web应用通过UI来编辑技能和规则实时预览对不同AI工具生成的效果降低使用门槛。与更多工具集成除了已列出的还可以考虑JetBrains IDE AI Assistant、Windsurf、甚至是终端AI工具如Fig、Warp AI的配置生成。云端同步与团队共享将配置库放在私有Git仓库团队成员克隆后即可共享同一套AI协作规范确保代码风格和最佳实践的一致性。智能化技能推荐通过分析项目代码库如package.json,Dockerfile自动激活相关的技能包实现更精准的上下文注入。与AI助手API深度集成不满足于生成静态文件而是开发插件在启动AI助手会话时自动通过API将配置好的系统提示词发送过去实现真正的“开箱即用”。这个项目的精髓不在于它当前的代码量而在于它提出的“将AI助手协作标准化、资产化”的理念。通过花时间精心打磨你的skills你实际上是在投资一个能随着时间不断学习和进化的“数字搭档”它能让你的开发效率获得持久的、可累积的提升。我开始使用这套体系后最直观的感受是与AI沟通的摩擦减少了至少70%更多的时间被用于思考和创造而不是重复说明基础规则。