技能包架构与文件组织设计
技能包架构与文件组织设计
学习目标
- 理解 agent-skills 的三层架构职责分离
- 掌握文件命名规范和目录组织规则
- 学会应用组合规则（用户是编排者，Persona 不调用 Persona）
- 理解项目从单一 skill 到 23 个 skill 的组织策略
前置知识
本章涉及 Skill 渐进式知识管理的通用原理，建议先阅读：
下文直接聚焦 agent-skills 的具体文件组织实现。
项目实践
三层架构的职责分离
┌─────────────────────────────────────────┐│ SKILL.md ││ ││ ┌─ Frontmatter ─────────────────────┐ ││ │ name: lowercase-hyphen-name │ ││ │ description: 第三人称 + 触发条件 │ ││ └───────────────────────────────────┘ ││ Overview → 电梯演讲 ││ When to Use → 触发条件 ││ Process → 工作流步骤 ││ Rationalizations → 反合理化表 ││ Red Flags → 违反信号 ││ Verification → 退出标准 │└─────────────────────────────────────────┘agent-skills 的三层架构各有明确职责：
| 层级 | 是什么 | 示例 | 组合角色 |
|---|---|---|---|
| Skill | 带步骤和退出标准的工作流 | code-review-and-quality | how — 在 Persona 或命令内部调用 |
| Persona | 有视角和输出格式的角色 | code-reviewer | who — 采用视角，产出报告 |
| Command | 用户入口点 | /review、/ship | when — 编排层 |
组合规则：用户（或斜杠命令）是编排者。Persona 不调用其他 Persona。技能是 Persona 工作流中的强制跳转。
文件命名规范
| 元素 | 规范 | 示例 |
|---|---|---|
| 技能目录 | kebab-case | code-review-and-quality/ |
| 技能文件 | 始终大写 | SKILL.md |
| 脚本 | kebab-case.sh | deploy.sh |
| 支撑文件 | kebab-case.md | frameworks.md |
| Zip 包 | 匹配目录名 | code-review-and-quality.zip |
目录组织规则
agent-skills/├── skills/ # 23 个技能│ ├── interview-me/ # Define 阶段│ ├── idea-refine/ # ├── 含 3 个支撑文件│ │ ├── SKILL.md # └── 入口│ │ ├── frameworks.md # ├── 支撑文件│ │ ├── examples.md # └── 支撑文件│ ├── spec-driven-development/ # Define│ ├── planning-and-task-breakdown/ # Plan│ ├── incremental-implementation/ # Build│ ├── ... # Build / Verify / Review / Ship│ └── using-agent-skills/ # Meta：如何使用这个技能包├── agents/ # 3 个专业角色│ ├── code-reviewer.md│ ├── security-auditor.md│ ├── test-engineer.md│ └── README.md # 角色关系和决策矩阵├── references/ # 5 个补充参考│ ├── testing-patterns.md│ ├── security-checklist.md│ ├── performance-checklist.md│ ├── accessibility-checklist.md│ └── orchestration-patterns.md├── hooks/ # 会话生命周期钩子│ ├── hooks.json│ ├── session-start.sh│ ├── sdd-cache-pre.sh│ ├── sdd-cache-post.sh│ ├── simplify-ignore.sh│ └── ...├── .claude/commands/ # 7 个斜杠命令（Claude Code）│ ├── spec.md│ ├── plan.md│ ├── build.md│ ├── test.md│ ├── review.md│ ├── code-simplify.md│ └── ship.md├── .gemini/commands/ # 7 个等价命令（Gemini CLI）└── docs/ # 设置指南和文档从单一 Skill 到 23 个 Skill 的组织策略
agent-skills 不是从一开始就有 23 个技能。它的增长遵循以下策略：
- 核心技能优先：最初只有几个核心技能（如 spec-driven、incremental-implementation）
- 按阶段扩展：随着覆盖的开发阶段增多，添加对应技能
- 避免重复：新技能不重复已有技能的内容，而是引用
- Meta Skill 治理：
using-agent-skills作为元技能，定义所有技能的共享行为
关键设计决策：references/ 在项目根目录，不被任何技能独占。这避免了”参考文件属于哪个技能”的争议，同时确保所有技能都可以引用。
问题与规避
| 陷阱 | 表现 | 对策 |
|---|---|---|
空 scripts/ 目录 | 增加噪音不改变工作方式 | 不含 runnable helpers 时不创建 |
| 技能间内容重复 | Agent 收到矛盾指令 | 引用而非重复，建立优先级 |
| 支撑文件过深 | 按需加载时引用链太长 | 文件引用只深一层 |
| Persona 调用 Persona | 破坏单一视角 | 通过斜杠命令编排，不内部调用 |
设计取舍
为什么不支持嵌套子目录？
扁平的技能目录（skills/name/）简化了发现逻辑。如果支持嵌套（如 skills/frontend/ui-engineering/），发现逻辑需要递归搜索，增加了复杂度和出错可能。扁平结构也使得新增技能时不需要决定”属于哪个子目录”。
为什么 Zip 包必须匹配目录名？
Zip 是分发单位。名称匹配确保安装时可以预测解压后的目录结构，避免路径冲突和版本不一致。
参考来源
- 源码验证:
docs/skill-anatomy.md— 技能解剖学和文件组织规范 - 源码验证:
CLAUDE.md— 项目约定和边界 - 源码验证:
AGENTS.md— 三层架构的职责分离定义