Back to Details

moai-foundation-claude

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Code Authoring Kit

Claude Code开发工具包

Comprehensive reference for Claude Code Skills, sub-agents, plugins, slash commands, hooks, memory, settings, sandboxing, headless mode, and advanced agent patterns.
这是一份关于Claude Code Skills、子代理（sub-agents）、插件、斜杠命令、钩子、记忆、设置、沙箱、无头模式以及高级Agent模式的综合参考文档。

Documentation Index

文档索引

Core Features:
  • reference/claude-code-skills-official.md - Agent Skills creation and management
  • reference/claude-code-sub-agents-official.md - Sub-agent development and delegation
  • reference/claude-code-plugins-official.md - Plugin architecture and distribution
  • reference/claude-code-custom-slash-commands-official.md - Command creation and orchestration
Configuration:
  • reference/claude-code-settings-official.md - Configuration hierarchy and management
  • reference/claude-code-memory-official.md - Context and knowledge persistence
  • reference/claude-code-hooks-official.md - Event-driven automation
  • reference/claude-code-iam-official.md - Access control and security
Advanced Features:
  • reference/claude-code-sandboxing-official.md - Security isolation
  • reference/claude-code-headless-official.md - Programmatic and CI/CD usage
  • reference/claude-code-devcontainers-official.md - Containerized environments
  • reference/claude-code-cli-reference-official.md - Command-line interface
  • reference/claude-code-statusline-official.md - Custom status display
  • reference/advanced-agent-patterns.md - Engineering best practices
核心功能：
  • reference/claude-code-skills-official.md - Agent Skills的创建与管理
  • reference/claude-code-sub-agents-official.md - 子代理的开发与委托
  • 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 - 工程最佳实践

Quick Reference

快速参考

Skills: Model-invoked extensions in ~/.claude/skills/ (personal) or .claude/skills/ (project). Three-level progressive disclosure. Max 500 lines.
Sub-agents: Specialized assistants via Task(subagent_type="..."). Own 200K context. Cannot spawn sub-agents. Use /agents command.
Plugins: Reusable bundles in .claude-plugin/plugin.json. Include commands, agents, skills, hooks, MCP servers.
Commands: User-invoked via /command. Parameters: $ARGUMENTS, $1, $2. File refs: @file.
Hooks: Events in settings.json. PreToolUse, PostToolUse, SessionStart, SessionEnd, PreCompact, Notification.
Memory: CLAUDE.md files + .claude/rules/*.md. Enterprise to Project to User hierarchy. @import syntax.
Settings: 6-level hierarchy. Managed to file-managed to CLI to local to shared to user.
Sandboxing: OS-level isolation. Filesystem and network restrictions. Auto-allow safe operations.
Headless: -p flag for non-interactive. --allowedTools, --json-schema, --agents for automation.
Skills：由模型调用的扩展，存储在~/.claude/skills/（个人）或.claude/skills/（项目）目录下。采用三级渐进式披露架构，最大支持500行代码。
子代理：通过Task(subagent_type="...")创建的专业助手，拥有独立的200K上下文，无法生成其他子代理，可使用/agents命令进行管理。
插件：可复用的功能包，存储在.claude-plugin/plugin.json中，包含命令、代理、Skills、钩子、MCP服务器等组件。
命令：用户通过/command格式调用，参数包括$ARGUMENTS、$1、$2，文件引用使用@file。
钩子：在settings.json中配置的事件，包括PreToolUse、PostToolUse、SessionStart、SessionEnd、PreCompact、Notification。
记忆：由CLAUDE.md文件和.claude/rules/*.md文件组成，遵循企业→项目→用户的层级结构，支持@import语法。
设置：6级层级结构，从托管式到文件托管、CLI、本地、共享再到用户级。
沙箱：操作系统级别的隔离机制，包含文件系统和网络限制，自动允许安全操作。
无头模式：使用-p flag启用非交互模式，通过--allowedTools、--json-schema、--agents参数实现自动化。

Skill Creation

Skill创建

Progressive Disclosure Architecture

渐进式披露架构

Level 1 (Metadata): Name and description loaded at startup, approximately 100 tokens per Skill
Level 2 (Instructions): SKILL.md body loaded when triggered, under 5K tokens recommended
Level 3 (Resources): Additional files loaded on demand, effectively unlimited
第1层（元数据）：名称和描述在启动时加载，每个Skill约占100 tokens
第2层（指令）：触发时加载SKILL.md主体内容，建议不超过5K tokens
第3层（资源）：按需加载额外文件，无实际数量限制

Required Format

要求格式

Create a SKILL.md file with YAML frontmatter containing name in kebab-case and description explaining what it does and when to use it in third person. Maximum 1024 characters for description. After the frontmatter, include a heading with the skill name, a Quick Start section with brief instructions, and a Details section referencing REFERENCE.md for more information.
创建SKILL.md文件，包含YAML前置元数据，其中name采用短横线命名法（kebab-case），description以第三人称说明功能及使用场景，最大长度1024字符。前置元数据后，需包含Skill名称的标题、快速入门章节（含简要说明）以及详细信息章节（引用REFERENCE.md获取更多内容）。

Best Practices

最佳实践

  • Third person descriptions (does not I do)
  • Include trigger terms users mention
  • Keep under 500 lines
  • One level deep references
  • Test with Haiku, Sonnet, Opus
  • 使用第三人称描述（避免使用“我”）
  • 包含用户可能提及的触发词
  • 代码行数控制在500行以内
  • 仅使用一级深度引用
  • 分别使用Haiku、Sonnet、Opus模型进行测试

Sub-agent Creation

子代理创建

Using /agents Command

使用/agents命令

Type /agents, select Create New Agent, define purpose and tools, press e to edit prompt.
输入/agents，选择Create New Agent，定义用途和工具，按e键编辑提示词。

File Format

文件格式

Create a markdown file with YAML frontmatter containing name, description explaining when to invoke (use PROACTIVELY for auto-delegation), tools as comma-separated list (Read, Write, Bash), and model specification (sonnet). After frontmatter, include the system prompt.
创建markdown文件，包含YAML前置元数据，其中name为代理名称，description说明调用时机（使用PROACTIVELY表示自动委托），tools为逗号分隔的工具列表（Read、Write、Bash），model指定模型（如sonnet）。前置元数据后，需包含系统提示词。

Critical Rules

关键规则

  • Cannot spawn other sub-agents
  • Cannot use AskUserQuestion effectively
  • All user interaction before delegation
  • Each gets own 200K context
  • 无法生成其他子代理
  • 无法有效使用AskUserQuestion工具
  • 所有用户交互需在委托前完成
  • 每个子代理拥有独立的200K上下文

Plugin Creation

插件创建

Directory Structure

目录结构

Create my-plugin directory with .claude-plugin/plugin.json, commands directory, agents directory, skills directory, hooks/hooks.json, and .mcp.json file.
创建my-plugin目录，包含.claude-plugin/plugin.json、commands目录、agents目录、skills目录、hooks/hooks.json以及.mcp.json文件。

Manifest (plugin.json)

清单文件（plugin.json）

Create a JSON object with name, description explaining plugin purpose, version as 1.0.0, and author object containing name field.
创建JSON对象，包含name、description（说明插件用途）、version（格式如1.0.0）以及author对象（包含name字段）。

Commands

命令操作

Use /plugin install owner/repo to install from GitHub. Use /plugin validate . to validate current directory. Use /plugin enable plugin-name to enable a plugin.
使用/plugin install owner/repo从GitHub安装插件 使用/plugin validate .验证当前目录 使用/plugin enable plugin-name启用插件

Advanced Agent Patterns

高级Agent模式

Two-Agent Pattern for Long Tasks

长任务双代理模式

Initializer agent: Sets up environment, feature registry, progress docs
Executor agent: Works single features, updates registry, maintains progress
See reference/advanced-agent-patterns.md for details.
初始化代理：负责搭建环境、功能注册、进度文档管理
执行代理：负责单个功能开发、更新注册表、维护进度
详情请参考reference/advanced-agent-patterns.md

Orchestrator-Worker Architecture

编排者-工作者架构

Lead agent: Decomposes tasks, spawns workers, synthesizes results
Worker agents: Execute focused tasks, return condensed summaries
主导代理：负责分解任务、生成工作者代理、合成结果
工作者代理：负责执行聚焦任务、返回精简摘要

Context Engineering Principles

上下文工程原则

  • Smallest set of high-signal tokens
  • Just-in-time retrieval over upfront loading
  • Context compaction for long sessions
  • External memory files persist outside window
  • 最小化高信号token集合
  • 优先使用即时检索而非预加载
  • 长会话中进行上下文压缩
  • 外部记忆文件持久化存储在上下文窗口之外

Tool Design Best Practices

工具设计最佳实践

  • Consolidate related functions into single tools
  • Return high-signal context-aware responses
  • Clear parameter names (user_id not user)
  • Instructive error messages with examples
  • 将相关功能整合到单个工具中
  • 返回高信号、上下文感知的响应
  • 使用清晰的参数名称（如user_id而非user）
  • 提供带示例的指导性错误信息

Explore/Search Performance Optimization

探索/搜索性能优化

When using Explore agent or direct exploration tools (Grep, Glob, Read), apply these optimizations to prevent performance bottlenecks with GLM models:
AST-Grep Priority
  • Use structural search (ast-grep) before text-based search (Grep)
  • Load moai-tool-ast-grep skill for complex pattern matching
  • Example: 
    sg -p 'class $X extends Service' --lang python
    is faster than 
    grep -r "class.*extends.*Service"
Search Scope Limitation
  • Always use 
    path
    parameter to limit search scope
  • Example: 
    Grep(pattern="func ", path="internal/core/")
    instead of 
    Grep(pattern="async def")
File Pattern Specificity
  • Use specific Glob patterns instead of wildcards
  • Example: 
    Glob(pattern="internal/core/*.go")
    instead of 
    Glob(pattern="src/**/*.py")
Parallel Processing
  • Execute independent searches in parallel (single message, multiple tool calls)
  • Maximum 5 parallel searches to prevent context fragmentation
使用Explore代理或直接探索工具（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个并行搜索，避免上下文碎片化

Workflow: Explore-Plan-Code-Commit

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

Phase 1 Explore: Read files, understand structure, map dependencies
Phase 2 Plan: Use think prompts, outline approach, define criteria
Phase 3 Code: Implement iteratively, verify each step, handle edges
Phase 4 Commit: Descriptive messages, logical groupings, clean history
阶段1 探索：读取文件、理解结构、映射依赖关系
阶段2 规划：使用思考提示词、概述实现方案、定义验收标准
阶段3 编码：迭代式实现、验证每一步、处理边缘情况
阶段4 提交：编写描述性提交信息、逻辑分组提交、保持清晰的提交历史

MoAI-ADK Integration

MoAI-ADK集成

Core Skills

核心Skills

  • moai-foundation-claude: This authoring kit
  • moai-foundation-core: SPEC system and workflows
  • moai-foundation-philosopher: Strategic thinking
  • moai-foundation-claude：本开发工具包
  • moai-foundation-core：SPEC系统与工作流
  • moai-foundation-philosopher：战略思考

Essential Sub-agents

关键子代理

  • spec-builder: EARS specifications
  • manager-ddd: DDD execution
  • expert-security: Security analysis
  • expert-backend: API development
  • expert-frontend: UI implementation
  • spec-builder：EARS规范构建
  • manager-ddd：领域驱动设计（DDD）执行
  • expert-security：安全分析
  • expert-backend：API开发
  • expert-frontend：UI实现

Security Features

安全特性

Sandboxing

沙箱

  • Filesystem: Write restricted to cwd
  • Network: Domain allowlists via proxy
  • OS-level: bubblewrap (Linux), Seatbelt (macOS)
  • 文件系统：仅允许写入当前工作目录（cwd）
  • 网络：通过代理实现域名白名单
  • 操作系统级别：Linux使用bubblewrap，macOS使用Seatbelt

Dev Containers

开发容器

  • Security-hardened with firewall
  • Whitelisted outbound only
  • --dangerously-skip-permissions for trusted only
  • 经过安全加固，内置防火墙
  • 仅允许白名单内的出站请求
  • --dangerously-skip-permissions参数仅适用于可信环境

Headless Safety

无头模式安全

  • Always use --allowedTools in CI/CD
  • Validate inputs before passing to Claude
  • Handle errors with exit codes
  • 在CI/CD中始终使用--allowedTools参数
  • 传递给Claude前验证输入
  • 使用退出码处理错误

Resources

资源

For detailed patterns and working examples, see the reference directory.
Version History:
  • v5.0.0 (2026-01-11): Converted to narrative format per CLAUDE.md Documentation Standards
  • v4.0.0 (2026-01-06): Added plugins, sandboxing, headless, statusline, dev containers, CLI reference, advanced patterns
  • v3.0.0 (2025-12-06): Added progressive disclosure, sub-agent details, integration patterns
  • v2.0.0 (2025-11-26): Initial comprehensive release
如需详细模式和可用示例，请查看reference目录。
版本历史：
  • v5.0.0（2026-01-11）：根据CLAUDE.md文档标准转换为叙事格式
  • v4.0.0（2026-01-06）：新增插件、沙箱、无头模式、状态行、开发容器、CLI参考、高级模式
  • v3.0.0（2025-12-06）：新增渐进式披露、子代理详情、集成模式
  • v2.0.0（2025-11-26）：首次全面发布