majiayu000 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:
- Skills Guide - Agent Skills creation and management
- Sub-agents Guide - Sub-agent development and delegation
- Plugins Guide - Plugin architecture and distribution
- Slash Commands - Command creation and orchestration
Configuration:
- Settings - Configuration hierarchy and management
- Memory - Context and knowledge persistence
- Hooks - Event-driven automation
- IAM & Permissions - Access control and security
Advanced Features:
- Sandboxing - Security isolation
- Headless Mode - Programmatic and CI/CD usage
- Dev Containers - Containerized environments
- CLI Reference - Command-line interface
- Statusline - Custom status display
- Advanced Patterns - Engineering best practices
Quick Reference (30 seconds)
Skills: Model-invoked extensions in ~/.claude/skills/ (personal) or .claude/skills/ (project). Three-level progressive disclosure. Max 500 lines.
Sub-agents: Specialized assistants via Task(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 (3 minutes)
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
---
name: skill-name
description: What it does AND when to use it. Third person. Max 1024 chars.
---
# Skill Name
## Quick start
Brief instructions here.
## Details
See [REFERENCE.md](REFERENCE.md) for more.
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 (3 minutes)
Using /agents Command
- Type /agents
- Select Create New Agent
- Define purpose and tools
- Press e to edit prompt
File Format
---
name: agent-name
description: When to invoke. Use PROACTIVELY for auto-delegation.
tools: Read, Write, Bash
model: sonnet
---
System prompt here.
Critical Rules
- Cannot spawn other sub-agents
- Cannot use AskUserQuestion effectively
- All user interaction before delegation
- Each gets own 200K context
Plugin Creation (3 minutes)
Directory Structure
my-plugin/
- .claude-plugin/plugin.json
- commands/
- agents/
- skills/
- hooks/hooks.json
- .mcp.json
Manifest (plugin.json)
{
"name": "my-plugin",
"description": "Plugin purpose",
"version": "1.0.0",
"author": {"name": "Author"}
}
Commands
/plugin install owner/repo /plugin validate . /plugin enable plugin-name
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 Advanced Patterns 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
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-claude: This authoring kit
- moai-foundation-core: SPEC system and workflows
- moai-foundation-philosopher: Strategic thinking
Essential Sub-agents
- spec-builder: EARS specifications
- manager-tdd: TDD 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
Version History
v4.0.0 (2026-01-06): Added plugins, sandboxing, headless, statusline, dev containers, CLI reference, advanced patterns from engineering blogs
v3.0.0 (2025-12-06): Added progressive disclosure, sub-agent details, integration patterns
v2.0.0 (2025-11-26): Initial comprehensive release