moai-foundation-cc

name	moai-foundation-cc
description	Canonical Claude Code authoring kit covering Skills, sub-agents, plugins, slash commands, hooks, memory, settings, sandboxing, headless mode, and advanced agent patterns. Use when creating Claude Code extensions or configuring Claude Code features.
when_to_use	Use for Claude Code authoring and extension: Skills, sub-agents, plugins, slash commands, hooks, memory, settings, sandboxing, headless mode, orchestration, and delegation/agent-pattern authoring.
license	Apache-2.0
compatibility	Designed for Claude Code
allowed-tools	Read, Write, Edit, Grep, Glob, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
user-invocable	false
metadata	{"version":"5.0.0","category":"foundation","status":"active","updated":"2026-01-11","modularized":"false","tags":"foundation, claude-code, skills, sub-agents, plugins, slash-commands, hooks, memory, settings, sandboxing, headless, agent-patterns","aliases":"moai-foundation-cc"}
progressive_disclosure	{"enabled":true,"level1_tokens":100,"level2_tokens":5000}

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="..."). 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.

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

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
• Cannot use AskUserQuestion effectively
• All user interaction before delegation
• Each gets own 200K context

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)
• 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

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

• spec-builder: EARS specifications
• manager-develop: DDD execution
• expert-security: Security analysis
• expert-backend: API development
• expert-frontend: 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

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 skill does not need allowed-tools, Claude will figure it out"	Missing allowed-tools means the skill silently inherits all tools. Explicit is safer than implicit.

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).