技能指南

详细介绍 MoAI-ADK 的技能系统。技能是智能体 Harness 的知识层，也是"只在需要的时刻加载需要的知识"这一代币经济学最具体的落地之处。

平台基础

平台层的背景说明见 技能。本页是 MoAI-ADK 视角的说明。

信息

什么是技能？

还记得 1999 年电影 黑客帝国 中的直升机驾驶场景吗？Neo 问 Trinity 会不会开直升机，Trinity 打电话给总部报出直升机型号，请求传送操作手册。

Claude Code 的技能 正是那份 操作手册。在需要的时刻只加载需要的知识，让 AI 立刻表现得像专家。

技能是向 Claude Code 提供特定领域专业知识的 知识模块。

用学校来类比，Claude Code 是学生，技能是教科书。就像数学课翻开数学课本、科学课翻开科学课本一样，Claude Code 写 Python 代码时加载 Python 技能，做 React UI 时加载 Frontend 技能。

flowchart TD
    USER[用户请求] --> DETECT[关键字检测]
    DETECT --> TRIGGER{触发匹配}
    TRIGGER -->|Python 相关| PY["moai-domain-backend
后端专业知识"]
    TRIGGER -->|React 相关| FE["moai-domain-frontend
前端专业知识"]
    TRIGGER -->|安全相关| SEC["moai-foundation-core
TRUST 5 安全原则"]
    TRIGGER -->|DB 相关| DB["moai-domain-database
数据库专业知识"]

    PY --> AGENT[向智能体注入知识]
    FE --> AGENT
    SEC --> AGENT
    DB --> AGENT

没有技能时：Claude Code 只能凭一般性知识作答。有技能时：应用 MoAI-ADK 的规则、模式与最佳实践作答。

MoAI-ADK 模板共提供 34 个技能。目录按安装范围分为随每个项目部署的 核心技能 21 个，以及按需部署的 可选包技能 13 个（backend 3 · design 1 · devops 5 · frontend 4）。按功能归类为 Foundation 4 + Workflow 8 + Domain 7 + Reference 11 + Meta/Harness 3 = 专业技能 33 个，再加上 1 个把请求路由到专业技能的 moai umbrella 技能，合计 34 个。在用户项目中还可以额外编写 hns-* 用户自定义 harness 技能。编程语言支持由 rules/moai/languages/ 下的规则提供，不是独立技能。

这个数字也是瘦身的结果 — 技能目录在 v3 期间从 48 → 38 个精炼，包含可选包在内的当前数量为 34 个。

moai-domain-svg-infographic 技能能生成哪些图表，不是推测而是实测确认的。把外部目录（SkillStead TypePack）的 9 种形态当作同样的生成任务运行，并测量是否通过技能自身的质量门（确定性源码 lint、带尺寸校验的 2 倍分辨率 PNG 渲染），结果 9 种形态全部可以复现。

每种形态都在四种基本布局（堆叠、从左到右的流程、并排比较、层级树）之上以保留信息结构的方式表达。分形态判定表和门禁日志见 .moai/reports/t272/verdict.md。

34 个技能包含在 MoAI-ADK 模板中（核心 21 个立即可用，13 个经由可选包），每个技能独立加载以节省代币。用户还可以额外编写按项目的 hns-* 用户自定义 harness 技能。

MoAI-ADK 的技能使用 3 级渐进式披露 (Progressive Disclosure) 系统。一次加载所有技能会浪费代币，因此按需分级加载。可以把它理解为上下文瘦身在技能层的实现。

flowchart TD
    subgraph L1["Level 1: 元数据 (~100 代币)"]
        M1["名称、说明、触发关键字"]
        M2["始终加载"]
    end

    subgraph L2["Level 2: 正文 (~5,000 代币)"]
        B1["完整技能文档"]
        B2["代码示例、模式"]
    end

    subgraph L3["Level 3: 附加包 (无限制)"]
        R1["modules/ 目录"]
        R2["reference.md, examples.md"]
    end

    L1 -->|"触发匹配时"| L2
    L2 -->|"需要深入信息时"| L3

• 传统方式：加载全部 34 个技能 = 约 170,000 代币（不可行）
• 渐进式披露：只加载元数据 = 约 3,400 代币（节省 98%）
• 按需加载：只加载任务所需的 2~3 个技能 = 追加约 15,000 代币

技能由 4 种触发条件 自动加载。

flowchart TD
    REQ[分析用户请求] --> KW{关键字检测}
    REQ --> AG{智能体调用}
    REQ --> PH{工作流阶段}
    REQ --> LN{语言检测}

    KW -->|"api, database"| SKILL1[moai-domain-backend]
    AG -->|"manager-develop"| SKILL1
    PH -->|"run 阶段"| SKILL2[moai-workflow-ddd]
    LN -->|"Python 文件"| SKILL3[moai-domain-backend]

    SKILL1 --> LOAD[技能加载完成]
    SKILL2 --> LOAD
    SKILL3 --> LOAD

# 在技能 frontmatter 中定义触发
triggers:
  keywords: ["api", "database", "authentication"] # 关键字匹配
  agents: ["manager-spec", "manager-develop"] # 调用智能体时
  phases: ["plan", "run"] # 工作流阶段
  languages: ["python", "typescript"] # 编程语言

触发优先级：

1. 关键字 (keywords)：在用户消息中检测到关键字时立即加载
2. 智能体 (agents)：调用特定智能体时自动加载
3. 阶段 (phases)：按 Plan/Run/Sync 阶段加载
4. 语言 (languages)：按正在操作的文件的编程语言加载

可以在 Claude Code 对话中直接调用技能。

# 在 Claude Code 中调用技能
> Skill("moai-domain-backend")
> Skill("moai-domain-frontend")
> Skill("moai-ref-api-patterns")

大多数情况下，技能会由触发机制 自动加载。用户无需手动调用，系统会分析对话上下文并激活合适的技能。

技能文件位于 .claude/skills/ 目录。

.claude/skills/
├── moai-foundation-core/       # Foundation 类别
│   ├── skill.md                # 主技能文档 (500 行以内)
│   ├── modules/                # 深入文档 (无限制)
│   │   ├── trust-5-framework.md
│   │   ├── spec-first-ddd.md
│   │   └── delegation-patterns.md
│   ├── examples.md             # 实战示例
│   └── reference.md            # 外部参考链接
│
├── moai-domain-backend/        # Domain 类别
│   ├── skill.md
│   └── modules/
│       ├── api-patterns.md
│       └── microservices.md
│
└── my-skills/                  # 用户自定义技能 (更新时不受影响)
    └── my-custom-skill/
        └── skill.md

注意

注意：带 moai-* 前缀的技能在 MoAI-ADK 更新时会被覆盖。 个人技能务必创建在 .claude/skills/my-skills/ 目录。

技能前缀区分 分发主体,moai update 的行为也不同。

hns-* 前缀表示用户创建的 harness 技能,moai update 绝不覆盖或删除。不得把 hns-* 技能镜像到模板中(CI 守卫会检测)。

注意

注意:带 moai-* 前缀的技能在 MoAI-ADK 更新时会被覆盖。 个人技能与 harness 技能请创建在 hns-* 前缀或无前缀的目录。

每个技能的 skill.md 遵循以下结构。

---
name: moai-domain-backend
description: >
  后端开发专家。提供 API 设计、微服务、数据库集成模式。
  开发 API、Web 应用、数据管线时使用。
version: 3.0.0
category: domain
status: active
triggers:
  keywords: ["api", "database", "microservices", "authentication"]
allowed-tools: ["Read", "Grep", "Glob", "Bash"]
---

# 后端开发专家

## Quick Reference

(快速参考 - 30 秒)

## Implementation Guide

(实现指南 - 5 分钟)

## Advanced Patterns

(高级模式 - 10 分钟以上)

## Works Well With

(相关技能/智能体)

用户在 Python FastAPI 项目中工作的场景。

# 1. 用户请求开发 API
> 用 FastAPI 做一个用户认证 API

# 2. MoAI-ADK 自动检测的关键字
# "FastAPI" → 触发 moai-domain-backend (Python 模式经 rules/moai/languages/ 提供)
# "认证"    → 触发 moai-domain-backend
# "API"     → 触发 moai-domain-backend

# 3. 自动加载的技能
# - moai-domain-backend (Level 2): API 设计模式、认证策略
# - moai-foundation-core (Level 1): TRUST 5 质量标准

# 4. 智能体运用技能知识进行实现
# - 应用 FastAPI 路由模式
# - 应用 JWT 认证最佳实践
# - 自动生成 pytest 测试
# - 满足 TRUST 5 质量标准

多个技能在同一任务中协作的过程。

flowchart TD
    REQ["用户: 用 Supabase + Next.js
做一个全栈应用"] --> ANALYZE[请求分析]

    ANALYZE --> S1["moai-domain-frontend
React/Next.js 模式"]
    ANALYZE --> S2["moai-domain-backend
API 设计模式"]
    ANALYZE --> S3["moai-domain-database
数据库集成"]
    ANALYZE --> S4["moai-foundation-core
TRUST 5 质量"]

    S1 --> IMPL[集成实现]
    S2 --> IMPL
    S3 --> IMPL
    S4 --> IMPL

    IMPL --> RESULT["类型安全的
全栈应用"]

Claude Code 不仅在项目根目录，也会在嵌套的子目录（parent-walk）中发现 .claude/skills/。因此 monorepo 可以把各包本地的技能放在各包自己的 .claude/skills/ 目录中。当在包含自己 .claude/skills/ 的嵌套目录内工作时，该嵌套目录的技能会在该子树内与根级技能一起加载。

当同一技能名称出现在嵌套链上的多个 .claude/skills/ 目录中时，由 closest-directory-wins（最近目录优先）规则解决冲突：离当前工作目录最近的 .claude/skills/ 会遮蔽 (shadow) 树上更高层的同名技能。这与嵌套 .claude/ 目录下已经适用于智能体、工作流、output-styles 的先行规则一致 — 最内层的 .claude/ 获胜。有意覆盖根技能的包本地技能必须保持同名。改名不会覆盖，而是产生第二个技能。

disableBundledSkills（settings.json 布尔值，或环境变量形式）会把 Claude Code 捆绑的 skills 与工作流 — 例如 /deep-research、内置斜杠命令 skills — 从 discovery 中隐藏，只显示 enterprise + personal + project + plugin skills。需要提供一个精选的无捆绑 skill 表面时使用。MoAI-ADK 不在自己的生成器中生成此开关，此处将其记录为可用选项。配套的 --safe-mode 启动标志记录在 Settings JSON 指南。

• 智能体指南 - 运用技能的智能体体系
• 构建器智能体指南 - 自定义技能的创建方法
• CLAUDE.md 指南 - 技能配置与规则体系

信息

提示：用好技能的核心是 使用合适的关键字。请求"用 Python 做一个 REST API"时，moai-domain-backend 技能会自动激活 （Python 模式经 rules/moai/languages/ 提供），生成最优代码。