第1课：项目概览与架构 Agency Agents

一、项目背景

Agency Agents 是 GitHub 上 125K+ stars 的开源项目，由 msitarzewski 创建。核心理念：

项目起源于一个 Reddit 帖子，经过数月迭代发展到 273 个 Agent 文件，支持 15 个 AI 工具平台。

二、项目目录全景

三、Agent 文件格式

每个 Agent 是一个 Markdown 文件，结构如下：

前端 YAML frontmatter 定义了 Agent 的元属性，正文是完整的系统提示词。

四、16 部门分布

五、工具支持体系

六、核心架构流程

七、divisions.json — 部门元数据

项目用 divisions.json 作为部门的"数据源："

每个部门有 label（显示名）、icon（Lucide 图标名）、color（品牌色）。被 app 和 CI 脚本消费。

八、关键设计决策

九、实战：安装 DevOps Agent 到 Claude Code

理论讲完了，接下来动手实战——从源码安装一个 DevOps Automator Agent 到 Claude Code，然后在命令行中使用它。

9.1 源文件概览

我们先看选中的 Agent 源文件：

这个 Agent 专注于：基础设施即代码（Terraform）、CI/CD 流水线（GitHub Actions）、容器编排（Kubernetes）、监控告警（Prometheus/Grafana）。

9.2 安装流程

Claude Code 的安装类型是 per-agent + identity 格式——意味着源文件直接复制到目标目录，无需任何格式转换。

# 完整安装（所有 Agent，所有已检测到的工具）
cd /root/agency-agents
./scripts/install.sh

# 只安装 Claude Code（最快）
./scripts/install.sh --tool claude-code

# 只安装 Engineering 部门的 Agent 到 Claude Code
./scripts/install.sh --tool claude-code --select engineering

# 干运行模式（不实际复制，只看会装什么）
./scripts/install.sh --tool claude-code --dry-run

执行 --tool claude-code 时，install.sh 内部做了这些事：

1. detect_claude_code()  ← 检测 ~/.claude/ 目录是否存在
2. 解析目标路径 → ~/.claude/agents/
3. 遍历所有部门目录中的 *.md 文件
4. 对每个文件：
   a. is_agent_file()  ← 校验是否以 YAML frontmatter 开头
   b. agent_slug()     ← 从 name 字段生成 slug
   c. slug_allowed()   ← 检查是否在白名单/黑名单中
   d. install_file()   ← 复制源文件到 ~/.claude/agents/{slug}.md
5. 输出统计："Claude Code: N agents -> ~/.claude/agents"

9.3 slug 的生成规则

slug 是安装过程中的关键中间值。它由 name 字段经过 agent_slug() 函数生成：

# agent_slug() 实现（简化）
agent_slug() {
  local name
  name="$(get_field name "$1")"    # 提取 YAML name 字段
  [[ -n "$name" ]] && slugify "$name"  # 转为 kebab-case
}

# slugify 将 "DevOps Automator" → "devops-automator"
# 规则：小写 + 空格变连字符 + 去除非字母数字

9.4 安装后的目录结构

安装完成后，~/.claude/agents/ 目录变成这样：

~/.claude/
├── agents/                     ← Agent 存放目录
│   ├── devops-automator.md     ← 我们刚装的 DevOps Automator
│   ├── systems-architect.md    ← 其他工程的 Agent
│   ├── lead-software-engineer.md
│   ├── penetration-tester.md   ← 安全部门的 Agent
│   ├── marketing-aeo.md        ← 营销部门的 Agent
│   └── ... (安装了多少就有多少)
├── projects/                   ← Claude 项目配置
└── CLAUDE.md                   ← 项目级指导文件

与源文件的对比：

# 源码目录（完整结构，含部门分类）
/root/agency-agents/
├── engineering/
│   ├── engineering-devops-automator.md    ← 原名
│   ├── engineering-systems-architect.md
│   └── ...
├── security/
├── marketing/
└── ...

# 安装后（扁平化，所有 Agent 在一个目录下，以 slug 命名）
~/.claude/agents/
├── devops-automator.md         ← slug 化后的文件名
├── systems-architect.md
├── penetration-tester.md
└── ...

9.5 在 Claude Code 中使用

安装完成后，在 Claude Code CLI 中有两种用法：

方式一：在对话中切换 Agent

# 启动 Claude Code
claude

# 在对话中切换到 DevOps Automator Agent
/agent devops-automator

# 效果：Claude 的角色立即变成 DevOps Automator
# 它会加载 engineering-devops-automator.md 中的系统提示词
# 以该 Agent 的身份和逻辑回答后续问题

方式二：启动时直接指定 Agent

# 一次性任务，以 DevOps Automator 的身份运行
claude --agent devops-automator "帮我设计一个 GitHub Actions CI/CD 流水线"

# 或者简写
claude -a devops-automator "分析我的 Terraform 配置"

使用场景示例

Agent 切换的效果

当你在 Claude Code 中使用 /agent devops-automator 后：

1. 系统提示词更新—Claude 的底层 prompt 被替换为该 Agent 的完整 Markdown 内容（Identity & Memory + Core Mission + Critical Rules + Deliverables）
2. 角色人格激活—回答风格从通用 Claude 变成"系统性、自动化优先、可靠性导向"的 DevOps 专家
3. 领域知识聚焦—会主动提出 Terraform/GitHub Actions/Docker/K8s 等技术方案，而不是泛泛而谈
4. 约束生效—Critical Rules 中的"自动化优先、安全合规嵌入流水线"等限制会约束 Agent 的行为

9.6 卸载与更新

# 卸载：直接删除文件即可
rm -i ~/.claude/agents/devops-automator.md

# 更新：重新运行 install.sh（覆盖旧文件）
./scripts/install.sh --tool claude-code

# 或者只更新特定部门
./scripts/install.sh --tool claude-code --select engineering

9.7 Agent vs Skill：人格 vs 工作流

学到这里，你可能会问：这个项目叫 Agency Agents，但我们 Hermes 里也有 Skills。它们到底有什么区别？什么时候该用 Agent，什么时候该用 Skill？

9.7.1 本质区别

9.7.2 使用场景对比

# ── Agent 场景：需要 AI「成为」某个角色 ──

# ✅ 适合 Agent
/agent devops-automator
"帮我审查这个 GitHub Actions 配置，看看安全问题"

→ Agent 以 DevOps 专家的身份深入分析，主动提出
  Terraform/K8s/监控等 DevOps 领域细节

# ❌ 不适合 Agent
/agent devops-automator
"教我安装 PostgreSQL"

→ Agent 可能给出冗长的 DevOps 视角回答，
  但缺少安装 Postgres 的标准化步骤

# ── Skill 场景：需要 AI「执行」标准化流程 ──

# ✅ 适合 Skill
skill_view('teach-course')
→ 加载完整教学课程创建流程：
  材料准备 → 目录结构 → 课程页 → Nginx → Git

# ❌ 不适合 Skill
skill_view('teach-course')
"帮我调试这个 Kubernetes Pod"

→ Skill 不包含 K8s 调试知识，无效加载

9.7.3 详细对比表

9.7.4 协作模式：Agent + Skill 组合

Agent 和 Skill 不是二选一，而是互补关系。最佳实践是两者搭配使用：

# 模式 1：Skill 提供流程 + Agent 提供角色
skill_view('teach-course')          ← 加载「教学课程」工作流
/agent devops-automator              ← 以 DevOps 专家身份执行
"帮我设计第3课中的 CI/CD 实战示例"

# 结果：既遵循了 teach-course 的标准化步骤，
# 又以 DevOps 专家的深度输出内容

# 模式 2：Agent 做深度诊断 + Skill 做标准化修复
/agent devops-automator              ← DevOps 专家诊断问题
"这个 K8s Pod 为什么 CrashLoopBackOff？"
→ 给出诊断结论
skill_view('systematic-debugging')  ← 调试 skill 引导修复
→ 按 4 阶段流程系统化修复

# 结果：Agent 发现病灶，Skill 提供手术流程

9.7.5 各自的优缺点

9.7.6 实际选择建议

十、课后小结

• ✅ 理解项目整体架构：273 Agent / 16 部门 / 15 工具
• ✅ 知道 Agent 文件由 YAML frontmatter + Markdown 系统提示词组成
• ✅ 理解 convert.sh → install.sh 的两步安装流水线
• ✅ 知道 Hermes 以 lazy-router 插件方式集成
• ✅ 实战：安装 DevOps Automator Agent 到 Claude Code 的完整流水线
• ✅ 理解 slug 机制：name 字段 → kebab-case → 目标文件名
• ✅ 掌握 /agent <slug> 在 Claude Code 中切换人格的方法
• ✅ 理解 Agent vs Skill 的区别：人格替换 vs 工作流手册
• ✅ 掌握 Agent + Skill 组合模式：专家拿着 SOP 干活
• ⏭ 下节课：深入 Agent 文件格式解剖