moai-foundation-claude

Claude Code Authoring Kit

Comprehensive reference for Claude Code Skills, sub-agents, plugins, slash commands, hooks, memory, settings, sandboxing, headless mode, and advanced agent patterns.

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

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 Agent(subagent_type="..."). Context window follows the session model (Sonnet 5 = 1M native on the Anthropic API; Haiku / gateway / older models = 200K — CC 2.1.197). Nesting: a subagent can spawn nested subagents only when its tools list includes Agent (CC 2.1.172); MoAI retained agents omit Agent, so they do not nest. To create or manage subagents, ask Claude or edit .claude/agents/ directly — the /agents wizard was removed in CC 2.1.198 (the official sub-agents doc still documented a /agents tabbed interface as of 2026-07-03; doc lag — verify in a live 2.1.198 session).

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.

Skill Creation

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

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.

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

Sub-agent Creation

Using /agents Command

CC 2.1.198 CHANGELOG delta: The /agents wizard was removed — per the CHANGELOG, "ask Claude to create or manage subagents, or edit .claude/agents/ directly." The official sub-agents doc still documented a /agents tabbed interface as of 2026-07-03 (doc lag, or the removal covers only the creation wizard); verify in a live 2.1.198 session before relying on the flow below.

Type /agents, select Create New Agent, define purpose and tools, press e to edit prompt.

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.

Critical Rules

• Cannot spawn other sub-agents by default (CC 2.1.172: a subagent CAN spawn nested subagents when its tools list includes Agent; MoAI retained agents omit Agent, so they do not nest)
• Cannot use AskUserQuestion effectively
• All user interaction before delegation
• Context window follows the session model (Sonnet 5 = 1M native on the Anthropic API; Haiku / gateway / older models = 200K — CC 2.1.197)

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.

Manifest (plugin.json)

Create a JSON object with name, description explaining plugin purpose, version as 1.0.0, and author object containing name field.

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.

Advanced Agent Patterns

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.

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

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

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)
• Run moai ast-grep to scan, moai ast-edit to rewrite matches
• 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

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

MoAI-ADK Integration

Core Skills

• moai-foundation-cc: This authoring kit
• moai-foundation-core: SPEC system and workflows
• moai-foundation-philosopher: Strategic thinking

Essential Sub-agents

• manager-spec: EARS specifications
• manager-develop: DDD execution
• Agent(general-purpose) with security instructions: Security analysis
• Agent(general-purpose) with backend instructions: API development
• Agent(general-purpose) with frontend instructions: UI implementation

Security Features

Sandboxing

• Filesystem: Write restricted to cwd
• Network: Domain allowlists via proxy
• OS-level: bubblewrap (Linux), Seatbelt (macOS)

Dev Containers

• Security-hardened with firewall
• Whitelisted outbound only
• --dangerously-skip-permissions for trusted only

Headless Safety

• Always use --allowedTools in CI/CD
• Validate inputs before passing to Claude
• Handle errors with exit codes

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

<!-- moai:evolvable-start id="rationalizations" -->

Common Rationalizations

Rationalization	Reality
"I will use Bash sed instead of Edit, it is faster"	Edit is the preferred tool for accuracy and review. Bash sed errors are silent and hard to trace.
"This hook does not need a timeout, it finishes quickly"	Hooks without timeouts can hang the entire session. Always set an explicit timeout.
"I can put all logic in CLAUDE.md, rules are overkill"	CLAUDE.md has a 40K character limit. Rules load conditionally and scale without bloating the prompt.
"Settings.json changes are low risk"	Incorrect settings.json breaks hooks, permissions, and model routing. Validate the JSON after every edit.
"I will skip progressive disclosure, all content is needed"	Loading 5K tokens for every skill wastes 67% of context. Level 1 metadata is sufficient for routing.
"This sk

---

Content truncated.