Moai Foundation Cc

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

Common Rationalizations

Red Flags

• CLAUDE.md exceeds 40,000 characters
• Hook registered in settings.json without a corresponding script file
• Skill frontmatter uses space-separated allowed-tools instead of comma-separated
• Agent definition uses YAML array for tools instead of CSV string
• settings.json contains hardcoded absolute paths instead of $CLAUDE_PROJECT_DIR
• Progressive disclosure disabled for a skill that exceeds 3000 tokens

Provenance (frontmatter CSV-format drift): space-separated allowed-tools silently breaks tool permissions (CONST-V3R5-038) — observed recurrence, provenance pending in memory.

Verification

• CLAUDE.md character count is under 40,000 (show wc -c output)
• settings.json is valid JSON (show json validation output)
• Every hook in settings.json has a matching script file in .claude/hooks/
• All skill frontmatter uses CSV format for allowed-tools
• Agent frontmatter uses CSV for tools and YAML array for skills
• All metadata values in skill frontmatter are quoted strings
• $CLAUDE_PROJECT_DIR used instead of absolute paths in hook commands

Decision Heuristics

Fast defaults — always confirm against the cited body section for non-trivial decisions.

• If a deferred tool (AskUserQuestion etc.) is needed, default to a ToolSearch preload first (<- §Documentation Index / sub-agents).
• If declaring allowed-tools, default to a comma-separated string, never space-separated (<- §Red Flags).
• If CLAUDE.md nears 40K chars, default to moving detail into path-scoped rules (<- §Verification).
• If a hook is registered, default to also setting an explicit timeout (<- §Common Rationalizations).
• If a skill exceeds ~3000 tokens, default to keeping progressive disclosure enabled (<- §Common Rationalizations).