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: 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 with one deliberate carve-out — manager-lead carries it as the sole depth-1 fan-out seam, and every leaf worker it spawns MUST omit Agent (the depth-2 seal, enforced at lint time; sentinel DEPTH_SEAL_VIOLATION) — so nothing re-delegates below that one layer, 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.
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
/agentswizard 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/agentstabbed 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
Agentfromtools, 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
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-grepto scan,moai ast-editto rewrite matches - Example:
sg -p 'class $X extends Service' --lang pythonis faster thangrep -r "class.*extends.*Service"
Search Scope Limitation
- Always use
pathparameter to limit search scope - Example:
Grep(pattern="func ", path="internal/core/")instead ofGrep(pattern="async def")
File Pattern Specificity
- Use specific Glob patterns instead of wildcards
- Example:
Glob(pattern="internal/core/*.go")instead ofGlob(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: Converted to narrative format per CLAUDE.md Documentation Standards
- v4.0.0: Added plugins, sandboxing, headless, statusline, dev containers, CLI reference, advanced patterns
- v3.0.0: Added progressive disclosure, sub-agent details, integration patterns
- v2.0.0: 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. |
| "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
