dotclaude：基于Agent Skills标准的AI编码代理技能库实战指南

1. 项目概述：dotclaude，一个极致的AI编码代理技能库

如果你和我一样，每天都在和Claude Code、Cursor或者GitHub Copilot这类AI编码工具打交道，那你肯定也经历过那种“工具很聪明，但工作流很笨拙”的瞬间。比如，想让AI帮你做一个完整的代码审查，它可能只会泛泛而谈；想让它规划一个复杂功能，它给出的步骤又过于笼统。我们缺的不是一个聪明的AI，而是一套能让这个聪明AI按照我们——资深开发者——的思维方式和质量标准去工作的“操作系统”。这就是我最近深度使用并贡献的dotclaude项目试图解决的问题。

简单说，dotclaude 是一个开源的、高度“固执己见”的Claude Code技能集合。它不是一个普通的插件仓库，而是一套完整的、覆盖从需求拆解到代码上线的全生命周期自动化工作流。它把那些我们手动操作时脑子里过的 checklist、最佳实践、设计模式，都封装成了一个个可复用的“技能”。这些技能遵循 Agent Skills 开放标准，这意味着它们不仅能在 Claude Code 里用，在微软的 Copilot、OpenAI 的 Codex CLI、Cursor 等任何支持该标准的工具里都能无缝运行。

我最初是被它的plan和code技能吸引的。plan技能不是简单地生成一个任务列表，而是要求AI输出一个可执行的实施计划，包含验证标准、潜在风险和模块分解。而code技能会严格遵循这个计划，在实现每个步骤时自动运行质量门禁（比如格式检查、类型检查、单元测试）。这就像给AI配了一个严格的Tech Lead，确保它写的代码不是“能跑就行”，而是“符合生产标准”。在用了几个月后，我逐渐把整个开发循环都迁移到了这套体系里：用worktree创建隔离的开发分支，用orch在复杂任务上启动多代理并行编码，用qual和judge进行多角度、专家级的代码审查，最后用commit和pr自动生成符合规范的提交信息和Pull Request。整个过程丝滑得让人上瘾。

2. 核心设计哲学：为何“固执己见”是最高效的

dotclaude 在简介里就自称“extremely opinionated”（极其固执己见）。这绝不是贬义词，而是其核心价值所在。在AI辅助编码的语境下，“灵活”往往意味着“低效”和“不一致”。每个人对AI的提示词（prompt）理解不同，给出的指令千差万别，导致输出质量波动巨大。dotclaude 的做法是，将经过大量实践验证的最佳工作流“固化”成技能，强制AI（以及使用AI的你）遵循一套高标准、可重复的流程。

2.1 从“对话式辅助”到“流程化驱动”的范式转变

传统使用AI编码的方式是对话式的：你描述需求，AI生成代码，你提出修改，AI调整。这种方式在简单任务上尚可，但面对复杂项目时，上下文容易丢失，决策过程不可追溯，质量完全依赖你每次提问的水平。dotclaude 引入的是一种流程化驱动的范式。每个技能都是一个封装好的微型工作流。例如，当你键入/pr-review，激活的不是一个简单的“请审查这段代码”的请求，而是一套完整的审查流程：

1. 上下文重建：技能会自动收集当前文件的变更、相关的依赖文件、甚至git历史，为AI构建完整的审查上下文。
2. 多维度分析：按照预设的检查清单（正确性、安全性、性能、可维护性、API设计）进行系统性扫描。
3. 结构化输出：不是生成一大段文字，而是按类别（Critical, Warning, Suggestion）列出问题，并附上具体的代码行引用和修改建议。
4. 可操作项：甚至会生成一个包含所有建议修复的代码补丁（patch），你可以直接应用。

这种转变的关键在于，将人的智慧从重复性的“流程管理”中解放出来，聚焦于“决策”本身。你不需要每次都苦思冥想审查要点，技能已经内置了资深工程师的审查框架。

2.2 技能即合约：明确输入、输出与边界

每个dotclaude技能都是一个自包含的目录，其核心是一个SKILL.md文件。这个文件采用YAML frontmatter定义技能的“合约”：

--- name: pr-review description: Multi-dimensional code review — correctness, security, quality. restrictions: - require_context: [file, diff, git_log] - max_tokens: 8000 - temperature: 0.1 ---

这个“合约”明确了：

• 功能：做什么（多维度代码审查）。
• 输入：需要什么上下文（文件、差异、git日志）。
• 约束：在什么条件下运行（最大token数、低随机性以保证确定性）。

这种设计带来了两个巨大好处：

1. 可预测性：只要输入符合要求，技能的输出质量和格式是高度可预测的。这非常适合集成到CI/CD流水线中。
2. 可组合性：技能可以像乐高积木一样组合。plan->code->qg(质量门禁) ->pr-review就是一个完整的开发子流水线。

注意：技能的“固执己见”也体现在其严格的约束上。例如，code技能会强制在实现过程中运行测试，如果测试失败，它会尝试修复，而不是忽略。这强制养成了测试驱动开发（TDD）的习惯，哪怕你最初并没有写测试的意识。

3. 核心技能组深度解析与实战配置

dotclaude的技能库按功能域组织得非常清晰。我们挑几个最能体现其设计深度的技能组，拆开看看里面到底是怎么工作的。

3.1 构建流水线：plan,code,orch—— 从想法到成品的流水线

这是最核心的一组技能，模拟了一个严谨的开发者从接到需求到产出代码的完整心智过程。

plan(规划技能)：不只是任务列表/plan激活后，AI会要求你描述功能或修复。它不会直接开始写代码，而是输出一个结构化文档，通常包含：

• 目标与范围：清晰定义做什么、不做什么。
• 架构影响：分析需要修改的模块、数据库变更、API变动。
• 实施步骤：分解为原子任务，每个任务都有明确的输入、操作和验证标准。
• 依赖与风险：识别外部依赖、潜在的性能瓶颈、向后兼容性问题。
• 回滚方案：如果出现问题，如何安全地撤销更改。

实战心得：我习惯在开始任何超过50行代码的修改前都先跑一遍/plan。它逼你在写第一行代码前就把问题想透彻，经常能提前发现设计缺陷。AI生成的计划也成为了极好的技术设计文档，可以直接粘贴到项目Wiki或PR描述里。

code(编码技能)：有纪律的执行者/code必须接收一个来自/plan的输出作为输入。它会严格按计划执行，并在每个步骤后执行“质量门禁”检查。它的内部逻辑大致是：

1. 读取计划，定位当前要实施的步骤。
2. 生成或修改代码。
3. 自动运行相关单元测试（如果存在）。
4. 如果测试失败，进入“诊断-修复”循环，而不是继续下一步。
5. 步骤完成后，自动格式化代码，并运行基础的lint检查。
6. 更新计划，标记当前步骤为完成，并高亮显示下一步。

踩过的坑：初期我试图绕过/plan直接使用/code，结果发现它效率很低，因为它缺乏全局上下文。后来我明白了，/plan和/code是一个不可分割的闭环。/plan是大脑，负责战略；/code是双手，负责战术。两者结合，才能保证代码的实现不偏离初衷。

orch(编排技能)：多代理并行攻坚当某个任务（比如“重写整个用户认证模块”）过于庞大，超出了单个AI代理的上下文窗口或处理能力时，/orch就登场了。它的工作原理是：

1. 任务分解：将宏观任务分解成多个独立或弱相关的子任务。
2. 代理孵化：为每个子任务启动一个独立的Claude Code会话（即一个“代理”），并注入具体的子任务指令和共享上下文（如项目结构、API文档）。
3. 并行执行：所有代理同时开始工作，分别调用/plan和/code。
4. 结果汇总：所有代理完成后，orch会收集输出，解决可能的冲突（如两个代理修改了同一个文件的非重叠部分），并生成一份整合报告。

配置要点：要使用orch、qual、judge等多代理技能，必须在你的 Claude Code 设置文件 (settings.json)中显式启用实验性团队功能：

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

没有这个设置，这些技能会回退到单代理顺序执行模式，无法发挥其威力。

3.2 质量保障体系：pr-review,qual,judge,razor—— 你的私人质量委员会

代码写完了，但远未到可以提交的时候。dotclaude的质量技能组构建了一个多层次、多视角的审查网络。

pr-review(代码审查)：基础安检这是最常用的审查技能。它像一个严格的自动化CR工具，检查点包括：

• 正确性：逻辑错误、边界条件、错误处理。
• 安全性：SQL注入、XSS、敏感信息泄露、依赖漏洞（通过检查package.json/requirements.txt）。
• 代码质量：代码异味、重复代码、复杂度、注释质量。
• 一致性：是否符合项目编码规范、命名约定。

qual(质量分析) 与judge(法官评审)：专家会诊/qual技能更进了一步。它不会只用一个AI代理来看代码，而是会同时启动多个具有不同“专长”的代理。比如，一个代理专注于性能，一个专注于API设计，一个专注于可维护性。每个代理从自己的专业角度出具报告，最后qual技能会综合所有报告，给你一份加权了不同风险维度的最终评估。/judge则是在qual或pr-review之后使用。它模拟一个独立、资深的专家，对前面的审查结论进行“二审”。它会质疑之前的判断，寻找盲点，特别是在架构决策和长期维护成本上提供更高阶的建议。我通常用在重大重构或核心模块修改后，作为上线的最后一道人工（AI）关卡。

razor(奥卡姆剃刀)：对代码存在的灵魂拷问这是我最欣赏的技能之一，它体现了极高的工程哲学。/razor不关心代码写得好不好，它关心这段代码有没有必要存在。它会问：

• 这个功能是否有真实的用户需求？还是“可能有用的”镀金功能？
• 同样的目标，能否通过更简单、现有的代码实现？
• 这段代码未来五年的维护成本是多少？它引入了多少新的依赖和复杂度？
• 如果删掉它，最坏的情况是什么？是否可控？

实操心得：在项目中期引入/razor，经常能帮你砍掉30%以上的“僵尸代码”或“过度设计”的代码。它特别适用于审查那些历史遗留的、没人敢动的“祖传代码”。很多时候，我们不是缺少删除代码的勇气，而是缺少一个帮我们理性分析删除后果的“伙伴”。

3.3 Git工作流自动化：从worktree到timesheet的无缝体验

对于频繁使用Git分支进行功能开发的团队，这一组技能能极大提升效率。

worktree(工作树) 与worktree-clean(清理)：隔离开发的利器传统的git checkout -b feature是在同一个工作目录切换分支，混用状态容易出错。/worktree技能利用Git的worktree功能，为你的新功能在一个全新的目录中创建一个关联的分支。这样，你的主目录永远保持在main或develop分支，功能开发在完全隔离的环境中进行，互不干扰。 开发完成后，/worktree-clean会自动删除这个临时工作目录并清理分支，保持仓库整洁。

commit(提交) 与pr(拉取请求)：规范化推动/commit技能会分析你的暂存区（staged）更改，然后根据 约定式提交 规范（如feat:,fix:,docs:,style:）自动生成提交信息。它还会检查是否有未解决的合并冲突或调试代码，避免错误提交。/pr技能则更进一步，基于当前分支自动在GitHub/GitLab上创建Pull Request。它会用提交历史来填充PR描述，并尝试关联相关的Issue编号。这几乎实现了从本地代码到可评审PR的“一键发布”。

timesheet(工时表)：基于Git的自动化报告这个技能非常巧妙。它分析指定时间段内（默认是上月）你的Git提交记录，然后按项目、按类型（功能、修复、文档等）生成一份工作时间报告。虽然不能替代精确的时间追踪，但对于个人复盘或向团队做粗略的工作汇报，它提供了一个完全基于客观数据（你的提交）的视角。

4. 高级技能与生态集成：让AI成为领域专家

除了通用开发流程，dotclaude还包含了一些针对特定领域的深度技能，展示了如何将领域知识深度集成到AI工作流中。

4.1design(设计探索)：对抗AI的“群体思维”

一个常见的痛点是，当你让AI生成一个设计方案时，它倾向于给出一个“最标准”、“最普遍”的答案，缺乏真正的创新和多样性。/design技能就是为了解决这个问题而生的。它的核心是发散性探索。

它通过启动多个具有“干净上下文”的独立代理来实现这一点，并为每个代理赋予不同的推理方法：

• 形态学分析：将问题分解为多个维度，并系统地组合不同维度的解决方案。
• TRIZ（发明问题解决理论）：应用经典的创新原则来寻找突破性方案。
• 约束放松：暂时忽略一两个关键约束（如成本、时间），看看能产生什么疯狂的想法，再往回拉。
• 仿生学：从自然界中寻找类似问题的解决方案。

每个代理独立工作，产生一套设计方案。最后，/design技能会汇总所有方案，并附上每个方案的优缺点分析。你得到的不是一个答案，而是一个设计空间的地图。这对于产品原型设计、架构选型、解决复杂技术难题特别有用。

4.2seo-geo(搜索引擎与生成式引擎优化)：面向未来的SEO

这是技能库中的一个瑰宝，它不仅仅是一个SEO检查工具，而是完整的工作流。它区分了传统SEO（针对Google、Bing）和GEO（Generative Engine Optimization，针对ChatGPT、Claude、Perplexity等AI搜索）。

核心组件：

1. 免费技术SEO审计脚本：无需任何API密钥，本地运行，分析网站的爬取能力、渲染速度、元标签、结构化数据等。
2. DataForSEO API集成（需自备API Key）：包含9个Python脚本，用于：
   • 关键词研究与规划
   • 相关关键词与搜索意图分析
   • 搜索引擎结果页（SERP）深度分析
   • 竞品反向链接分析
   • 域名权威性概览
3. 参考指南：包含了普林斯顿大学关于GEO的研究方法总结、各AI搜索平台（ChatGPT, Perplexity, Gemini等）的排名算法特点、以及现成的JSON-LD结构化数据模板。

实战应用：当我需要为一篇技术博客或开源项目README做优化时，我会：

1. 运行/seo-geo，选择“技术审计”，快速得到基础问题列表（如缺失alt标签、标题过长）。
2. 使用其关键词脚本，找到核心话题相关的、搜索量适中、竞争度较低的长尾关键词。
3. 参考其提供的JSON-LD模板，为我的内容添加Article,HowTo或SoftwareSourceCode结构化数据，这能极大提高在AI搜索中被理解和引用的概率。
4. 根据GEO指南，调整内容结构，比如增加清晰的摘要、分步骤的解决方案、对比表格，这些格式更受AI搜索的青睐。

4.3 实验性技能：与Pencil的设计-代码双向桥梁

对于使用 Pencil 进行产品原型设计的团队，pen-design和pen-code技能堪称神器。它们通过Pencil的MCP服务器，在视觉设计和实际代码之间建立了双向通道。

• pen-design：你可以用自然语言描述一个UI需求（如“设计一个包含用户头像、姓名、邮箱和编辑按钮的个人资料卡片”），技能会在Pencil中生成对应的.pen设计文件，并应用一套设计系统（间距、颜色、字体层级）。
• pen-code：当你修改了设计文件，/pen-code可以将其转换为React/Tailwind代码。反之，如果你修改了代码，它也可以尝试将更改同步回设计文件，保持设计与代码的同步。

这实现了从“产品想法”到“高保真设计”再到“生产级代码”的快速闭环，特别适合在敏捷团队中快速验证UI概念。

5. 安装、配置与自定义指南

5.1 基础安装：两种推荐方式

dotclaude的安装极其简单，因为它本质是一堆文本文件（技能定义）。

方式一：克隆并符号链接（推荐，便于更新）

# 克隆仓库到你的用户目录下 git clone git@github.com:JHostalek/dotclaude.git ~/dotclaude # 为所有技能创建符号链接到Claude Code的技能目录 ln -s ~/dotclaude/skills/* ~/.claude/skills/

这种方式的好处是，你只需要进入~/dotclaude目录执行git pull，就能更新所有技能。符号链接保证了你的~/.claude/skills/目录下永远是最新版本。

方式二：按需复制如果你只想尝试其中一两个技能，可以直接复制对应的目录。

# 创建技能目录（如果不存在） mkdir -p ~/.claude/skills # 复制你需要的技能，例如代码审查 cp -r ~/dotclaude/skills/pr-review ~/.claude/skills/

5.2 关键配置：启用多代理与共享技能

要使所有功能生效，可能需要调整Claude Code的settings.json文件。这个文件通常位于~/.config/Claude Code/settings.json或类似路径。

启用多代理团队（必须）： 如前所述，对于orch,qual,judge,refactor,intern,design这些技能，必须设置环境变量。

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

配置技能目录权限（可选）： 如果你在团队环境中，并且通过符号链接共享了~/.claude/skills/目录，需要让Claude Code有读取权限。

{ "permissions": { "additionalDirectories": ["~/.claude/skills"] } }

配置钩子（Hooks）： dotclaude提供了一些实用的钩子脚本，位于hooks/目录。例如，approve-piped-bash钩子可以自动批准管道命令（如果每个部分都在允许列表中）。要启用它们，需要在settings.json中注册：

{ "hooks": { "approve-piped-bash": "~/.claude/hooks/approve-piped-bash.js" // 假设你把钩子脚本复制到了这里 } }

具体的钩子安装方法，请参考项目hooks/目录下的说明和 Claude Code官方文档 。

5.3 技能的自定义与进阶：使用skill-creator和intern

dotclaude的强大之处在于它不仅能用，还能自己改、自己创。

skill-creator(技能创造器)： 这是一个元技能，用于创建和修改其他技能。你可以通过/skill-creator启动一个交互式流程：

1. 描述：用自然语言描述你想要的新技能（例如：“一个能帮我将Python类转换成TypeScript接口的技能”）。
2. 生成：AI会生成一个包含SKILL.md和可能的相关脚本、参考文件的技能目录结构。
3. 测试与基准测试：技能创建器会运行一系列测试，并可能与其他类似技能进行基准比较，评估其有效性和独特性。
4. 优化：你可以根据反馈，指示AI修改技能的定义、提示词或逻辑。

intern(实习生技能)：让配置自我进化这是最让我惊艳的技能。/intern会分析你最近的Claude Code会话历史，寻找模式。

• 重复性操作：你是否经常手动执行一系列相同的命令？intern可能会建议你创建一个新的技能或快捷方式来自动化它。
• 低效交互：你是否经常需要纠正AI对某个特定库的误解？intern可能会建议你更新或创建一个references/文档，为该库提供更准确的上下文。
• 技能使用模式：它还能分析哪些技能最常用，哪些很少用，并提出优化建议。

本质上，intern是一个基于你个人使用习惯的、自动化的技能优化师。运行它几次，你可能会发现你的技能库变得越来越贴合你的个人工作流。

6. 常见问题与故障排查实录

在实际使用中，我遇到并解决了一些典型问题，这里分享给大家。

6.1 技能不生效或无法识别

症状：在Claude Code中输入/后，没有出现dotclaude的技能列表。排查步骤：

1. 确认安装路径：首先检查技能是否被放到了正确的位置。Claude Code默认在~/.claude/skills/目录下查找技能。确保技能目录（如pr-review）直接位于此目录下，而不是嵌套在子目录里。
2. 检查目录结构：进入一个技能目录，确认里面存在SKILL.md文件。这是技能的入口文件，没有它技能不会被加载。
3. 重启Claude Code：技能列表在Claude Code启动时加载。安装新技能后，需要完全退出并重新启动Claude Code桌面应用或CLI会话。
4. 查看日志：Claude Code有时会在控制台或日志文件中输出技能加载错误。检查这些信息有助于定位问题（如YAML语法错误）。

6.2 多代理技能（如orch）运行失败

症状：使用/orch时，提示需要启用实验性功能，或者只有一个代理在工作。解决方案：

1. 确认设置：百分之百确认你的settings.json文件中已经正确设置了"env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"。注意JSON格式，不要缺少引号或逗号。
2. 版本兼容：确保你使用的Claude Code版本支持多代理功能。通常需要较新的版本。查看官方更新日志。
3. 资源限制：启动多个代理会消耗更多的API调用和Token。如果你的Anthropic API套餐有速率限制或配额较低，可能会失败。检查API控制台。

6.3plan和code技能循环依赖或上下文丢失

症状：/code说找不到计划，或者执行几步后忘记了整体目标。最佳实践：

• 明确传递：在使用/code时，最可靠的方式是将/plan的完整输出作为上下文的一部分提供给/code。你可以直接复制粘贴，或者利用编辑器的“追加到上下文”功能。
• 分步执行：对于非常庞大的计划，不要试图让/code一次性完成所有步骤。可以手动将计划分成几个阶段，分阶段执行/code，每完成一个阶段，将更新后的计划作为下一阶段的输入。
• 使用项目级指令：在项目根目录创建CLAUDE.md或TOOLS.md文件，定义项目特定的技术栈、架构约定和常用命令。这些文件会被Claude Code自动加载，为所有技能（包括plan和code）提供稳定的背景知识，减少上下文丢失。

6.4 技能执行速度慢或Token消耗大

症状：尤其是qual,judge,refactor等多代理或深度分析技能，运行时间较长。优化策略：

1. 缩小范围：不要一次性对整个代码库运行refactor。先通过plan或手动分析，将重构范围限定在几个关键模块或文件上，然后针对这些范围运行技能。
2. 调整技能内部设置：有些技能的SKILL.md文件中定义了max_tokens等参数。如果你是高级用户，可以尝试适当调低这些值，但要注意这可能影响输出质量。更好的方法是提供更精确的指令，限定分析焦点。
3. 使用更快的模型：在Claude Code设置中，你可以选择默认使用的模型（如Claude 3.5 Sonnet vs. Haiku）。对于不需要极高推理深度的任务（如简单的commit信息生成），可以尝试使用更快、更便宜的模型。

6.5 与现有项目工作流的整合问题

症状：dotclaude的技能（如qg质量门禁）希望运行特定的命令（如npm test），但你的项目使用yarn或pnpm，或者测试命令不同。解决方案：

• 项目级配置：这是最优雅的解决方案。在你的项目根目录创建一个.claude目录，并在里面放置项目特定的技能覆盖或配置文件。dotclaude的全局技能会优先读取项目本地配置。
• 修改技能：对于团队共享的流程，你可以直接fork dotclaude的某个技能，修改其内部的脚本或命令引用（例如，将npm run lint改为yarn lint），然后将修改后的技能放在项目本地或团队的共享位置。skill-creator技能可以帮助你安全地修改现有技能。

几个月用下来，dotclaude已经从我的一个“新奇玩具”变成了日常开发中不可或缺的“副驾驶操作系统”。它最大的价值不是替代思考，而是将那些琐碎的、重复的、但至关重要的工程实践固化下来，让我能更专注地解决真正复杂的问题。从生疏到熟练需要一个过程，特别是适应它那种“固执”的工作流，但一旦习惯，你会发现你的代码产出质量和开发节奏都有了肉眼可见的提升。如果你也受困于如何让AI编码助手更稳定、更可靠地工作，强烈建议你从plan和code这两个核心技能开始，亲自体验一下这种流程化驱动的AI协作模式。