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.
Instrucciones de origen · Vista previa de solo lectura
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.
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: by default a subagent CAN spawn subagents of its own, up to three layers below the main conversation; CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH changes the limit and 1 turns nesting off (CC 2.1.217+). At the depth limit Claude Code withholds the Agent tool. To stop one specific subagent from spawning, omit Agent from its tools list or add it to disallowedTools — MoAI retained agents omit Agent, so they do not nest regardless of the depth setting. 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.
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
Nesting is allowed by default (three layers below the main conversation); MoAI retained agents omit Agent from tools, so they do not spawn subagents of their own
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
"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.
"allowed-tools restricts which tools the skill may use"
It does the opposite: allowed-tools pre-approves those tools for the turn that invokes the skill, so they run without a permission prompt. The field that removes tools is disallowed-tools. Omitting allowed-tools is not a leak — the standard permission model still applies.
Red Flags
CLAUDE.md exceeds 40,000 characters
Hook registered in settings.json without a corresponding script file
Skill frontmatter grants a broad allowed-tools set when a narrow one would do (the field pre-approves tools, so every entry is a permission prompt waived)
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
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/
Skill allowed-tools lists only the tools the skill actually runs (space-separated, comma-separated, and YAML-list forms are all accepted)
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
