--- name: Claude Code Authoring Kit slug: claude-code-authoring-kit category: AI Engineering description: Claude Code Authoring Kit is a comprehensive reference for creating and configuring Claude Code extensions, covering Skills, sub-agents, plugins, slash commands, hooks, memory, settings, sandboxing, headless mode, and advanced agent patterns. github: "https://github.com/modu-ai/moai-adk/tree/main/.claude/skills/moai-foundation-cc" language: Go stars: 1177 forks: 220 install: "npx degit https://github.com/modu-ai/moai-adk/tree/main/.claude/skills/moai-foundation-cc ~/.claude/skills/moai-foundation-cc" installs_to: ~/.claude/skills/moai-foundation-cc source_path: .claude/skills/moai-foundation-cc/SKILL.md collection_size: 25 category_size: 2451 collection_url: "https://dirskills.com/collections/modu-ai/moai-adk" added: 2026-08-20T07:55:50.689Z last_synced: 2026-08-20T07:55:50.689Z canonical_url: "https://dirskills.com/skills/claude-code-authoring-kit" --- # Claude Code Authoring Kit Claude Code Authoring Kit is a comprehensive reference for creating and configuring Claude Code extensions, covering Skills, sub-agents, plugins, slash commands, hooks, memory, settings, sandboxing, headless mode, and advanced agent patterns. **Install:** ```bash npx degit https://github.com/modu-ai/moai-adk/tree/main/.claude/skills/moai-foundation-cc ~/.claude/skills/moai-foundation-cc ``` ## README # 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 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-grep` to scan, `moai ast-edit` to rewrite matches - 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 - 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 (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).