moai-foundation-claude

Claude Code 编写工具包

关于 Claude Code Skills、子 Agent、插件、斜杠命令、钩子、记忆、设置、沙箱、无头模式和高级 Agent 模式的全面参考。

文档索引

核心功能：

• reference/claude-code-skills-official.md - Agent Skills 的创建与管理
• reference/claude-code-sub-agents-official.md - 子 Agent 的开发与委派
• reference/claude-code-plugins-official.md - 插件架构与分发
• reference/claude-code-custom-slash-commands-official.md - 命令的创建与编排

配置：

• reference/claude-code-settings-official.md - 配置层级与管理
• reference/claude-code-memory-official.md - 上下文与知识持久化
• reference/claude-code-hooks-official.md - 事件驱动的自动化
• reference/claude-code-iam-official.md - 访问控制与安全

高级功能：

• reference/claude-code-sandboxing-official.md - 安全隔离
• reference/claude-code-headless-official.md - 编程式和 CI/CD 用法
• reference/claude-code-devcontainers-official.md - 容器化环境
• reference/claude-code-cli-reference-official.md - 命令行界面
• reference/claude-code-statusline-official.md - 自定义状态显示
• reference/advanced-agent-patterns.md - 工程最佳实践

快速参考

Skills：由模型调用的扩展，位于 ~/.claude/skills/（个人）或 .claude/skills/（项目）。采用三级渐进式披露。最多 500 行。

子 Agent：通过 Agent(subagent_type="...") 调用的专用助手。拥有独立的 200K 上下文。无法生成子 Agent。使用 /agents 命令。

插件：位于 .claude-plugin/plugin.json 中的可复用套件。包含命令、Agent、Skills、钩子和 MCP 服务。

命令：由用户通过 /command 调用。参数：$ARGUMENTS、$1、$2。文件引用：@file。

钩子：在 settings.json 中定义的事件。PreToolUse、PostToolUse、SessionStart、SessionEnd、PreCompact、Notification。

记忆：CLAUDE.md 文件 + .claude/rules/*.md。层级为企业到项目再到用户。使用 @import 语法。

设置：六级层级。由托管设置到文件托管设置，再到 CLI、本地、共享和用户设置。

沙箱：操作系统级隔离。限制文件系统和网络。自动允许安全操作。

无头模式：使用 -p 标志启用非交互模式。使用 --allowedTools、--json-schema、--agents 实现自动化。

创建 Skill

渐进式披露架构

第 1 级（元数据）：启动时加载名称和描述，每个 Skill 约占 100 个 token

第 2 级（说明）：触发时加载 SKILL.md 正文，建议少于 5K 个 token

第 3 级（资源）：按需加载其他文件，实际上没有数量限制

必需格式

创建一个 SKILL.md 文件，其中包含 YAML 前置元数据，包含 kebab-case 格式的名称，以及用第三人称说明其功能和适用场景的描述。描述最多 1024 个字符。前置元数据之后，添加一个以技能名称为标题的标题、包含简要说明的快速入门部分，以及引用 REFERENCE.md 以了解更多信息的详细信息部分。

最佳实践

• 使用第三人称描述（不要写成“我做……”）
• 包含用户会提及的触发词
• 保持在 500 行以内
• 引用仅深入一层
• 使用 Haiku、Sonnet、Opus 进行测试

创建子 Agent

使用 /agents 命令

输入 /agents，选择 Create New Agent，定义用途和工具，然后按 e 编辑提示词。

文件格式

创建一个带有 YAML 前置元数据的 Markdown 文件，其中包含名称、说明何时调用的描述（自动委派时使用 PROACTIVELY）、以逗号分隔的工具列表（Read、Write、Bash）以及模型规格（sonnet）。前置元数据之后，添加系统提示词。

关键规则

• 无法生成其他子 Agent
• 无法有效使用 AskUserQuestion
• 所有用户交互都必须在委派之前完成
• 每个子 Agent 都有独立的 200K 上下文

创建插件

目录结构

创建 my-plugin 目录，其中包含 .claude-plugin/plugin.json、commands 目录、agents 目录、skills 目录、hooks/hooks.json 和 .mcp.json 文件。

清单（plugin.json）

创建一个 JSON 对象，包含 name、说明插件用途的 description、值为 1.0.0 的 version，以及包含 name 字段的 author 对象。

命令

使用 /plugin install owner/repo 从 GitHub 安装。 使用 /plugin validate . 验证当前目录。 使用 /plugin enable plugin-name 启用插件。

高级 Agent 模式

长任务的双 Agent 模式

初始化 Agent：设置环境、功能注册表和进度文档

执行 Agent：处理单个功能、更新注册表并维护进度

详情请参阅 reference/advanced-agent-patterns.md。

编排者-工作者架构

主 Agent：分解任务、启动工作者并综合结果

工作者 Agent：执行专注任务并返回精简摘要

上下文工程原则

• 使用数量最少、信息量最高的 Token
• 优先按需检索，而非预先加载
• 对长会话进行上下文压缩
• 外部记忆文件会持久保存在上下文窗口之外

工具设计最佳实践

• 将相关功能整合到单个工具中
• 返回信息量高且能感知上下文的响应
• 使用清晰的参数名（user_id，而非 user）
• 提供包含示例的指导性错误消息

探索／搜索性能优化

使用 Explore Agent 或直接使用探索工具（Grep、Glob、Read）时，请应用以下优化，以避免 GLM 模型出现性能瓶颈：

优先使用 AST-Grep

• 先使用结构化搜索（ast-grep），再使用基于文本的搜索（Grep）
• 复杂模式匹配时加载 moai-tool-ast-grep skill
• 示例：sg -p 'class $X extends Service' --lang python 比 grep -r "class.*extends.*Service" 更快

限制搜索范围

• 始终使用 path 参数限制搜索范围
• 示例：使用 Grep(pattern="func ", path="internal/core/")，而非 Grep(pattern="async def")

明确指定文件模式

• 使用具体的 Glob 模式，而非通配符
• 示例：使用 Glob(pattern="internal/core/*.go")，而非 Glob(pattern="src/**/*.py")

并行处理

• 并行执行互不依赖的搜索（在单条消息中调用多个工具）
• 最多并行执行 5 次搜索，以防上下文碎片化

工作流：探索-计划-编码-提交

阶段 1 探索：读取文件、了解结构、梳理依赖关系

阶段 2 计划：使用思考提示词、列出方案、定义标准

阶段 3 编码：迭代实现、验证每个步骤、处理边界情况

阶段 4 提交：使用描述性消息、合理分组、保持历史记录整洁

MoAI-ADK 集成

核心技能

• moai-foundation-claude：此创作工具包
• moai-foundation-core：SPEC 系统和工作流
• moai-foundation-philosopher：战略思考

必备子 Agent

• spec-builder：EARS 规范
• manager-ddd：DDD 执行
• expert-security：安全分析
• expert-backend：API 开发
• expert-frontend：UI 实现

安全功能

沙箱

• 文件系统：写入操作仅限当前工作目录
• 网络：通过代理设置域名允许列表
• 操作系统级别：bubblewrap（Linux）、Seatbelt（macOS）

开发容器

• 采用强化安全配置，并启用防火墙
• 仅允许连接已列入白名单的出站地址
• --dangerously-skip-permissions 仅适用于可信场景

无头模式安全

• 在 CI/CD 中始终使用 --allowedTools
• 将输入传递给 Claude 前先进行验证
• 使用退出代码处理错误

资源

如需详细模式和可运行示例，请参阅 reference 目录。

版本历史：

• v5.0.0 (2026-01-11)：根据 CLAUDE.md 文档标准转换为叙述式格式
• v4.0.0 (2026-01-06)：新增插件、沙箱、无头模式、状态栏、开发容器、CLI 参考和高级模式
• v3.0.0 (2025-12-06)：新增渐进式披露、子 Agent 详情和集成模式
• v2.0.0 (2025-11-26)：首次全面发布