/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
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"

# MoAI Extension: Progressive Disclosure
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="..."). 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 nat