claude-code-internal-architecture

Gives Claude Code accurate, mechanism-level knowledge of its own internals — so it stops guessing about nesting limits, precedence order, hook events, and cache behavior, and can actually design harnesses on top of itself.

Claude Code knows a lot about the world, but surprisingly little about the exact, current mechanics of the tool it's running inside — the depth-5 subagent cap, the settings precedence order, what each of the ~30 hook events actually fires on, how the plugin version cache trips people up, why bypassPermissions still prompts for some things. Ask it to design an agent team or debug a hook and it'll often produce something plausible-sounding but subtly wrong.

This plugin fixes that with one skill, claude-code-internal-architecture, built entirely from Claude Code's own official reference documentation: a lean SKILL.md hub plus ten deep-dive reference files covering the agent loop, context/caching, tools/permissions/sandboxing, subagents/agent teams, skills/memory, hooks, MCP, plugins/marketplaces, the CLI/settings hierarchy, the Agent SDK, and dynamic workflows.

Install

/plugin marketplace add ShulkwiSEC/claude-code-internal-architecture
/plugin install claude-code-internal-architecture@claude-code-internal-architecture-marketplace

Or locally, for development:

/plugin marketplace add ./claude-code-internal-architecture-pluggin
/plugin install claude-code-internal-architecture@claude-code-internal-architecture-marketplace

Update later with:

/plugin marketplace update claude-code-internal-architecture-marketplace
/plugin update claude-code-internal-architecture@claude-code-internal-architecture-marketplace

What's in it

The skill triggers automatically whenever a task touches Claude Code's own mechanics — designing a subagent tree, writing a hook, debugging a permission denial, building a plugin, deciding between a skill and a subagent for some behavior. It can also be invoked directly for a quick lookup.

skills/claude-code-internal-architecture/
├── SKILL.md                          # hub: mental model, reference index, load-bearing facts, design checklist
└── references/
    ├── agent-loop-and-context.md     # turn mechanics, compaction, prompt caching, checkpointing, fast mode
    ├── tools-and-permissions.md      # full tool inventory, permission rules/modes, sandboxing, advisor
    ├── subagents-and-teams.md        # frontmatter schema, depth cap, spawn budget, agent teams, worktrees
    ├── skills-and-memory.md          # progressive disclosure, triggering, CLAUDE.md precedence, auto memory
    ├── hooks.md                      # every lifecycle event, handler types, exit-code semantics
    ├── mcp.md                        # transports, tool naming, tool search, managed MCP
    ├── plugins-and-marketplaces.md   # plugin.json/marketplace.json schemas, versioning, the plugin cache
    ├── cli-and-settings.md           # CLI flags, settings precedence, env vars, sessions
    ├── sdk-and-workflows.md          # Agent SDK, custom tools, dynamic workflows
    └── sessions-and-surfaces.md      # glossary, surfaces, scheduling mechanisms, remote control

SKILL.md stays under ~150 lines on purpose — it's the always-loaded-on-trigger layer. The reference files (~230–660 lines each, with a table of contents past ~300 lines) are the "read only when actually needed" layer, following the same progressive-disclosure principle the skill teaches.

Sourcing and accuracy

Every reference file was built by fetching Claude Code's own current documentation (code.claude.com/docs) and synthesizing it — not written from memory. Docs drift as Claude Code ships new versions; this plugin is a snapshot, not a live feed. Re-run the research pass periodically (or whenever something in here looks stale) rather than treating it as permanently authoritative.

Keeping this up to date

This repo carries its own maintainer tooling in .claude/agents/ — project-scoped subagents (they load automatically when you open this repo in Claude Code, and are not shipped as part of the plugin itself) that turn "keep the skill current" into a repeatable pipeline instead of a from-scratch research session every time:

1. feature-scout — checks Claude Code's changelog/what's-new pages and official docs for anything new or changed since the reference files were last touched.
2. reference-writer — researches one topic cluster from official sources and writes/updates the matching references/*.md file in this skill's house style.
3. skill-reviewer — QAs a reference-file change: line-count/TOC discipline, factual spot-check, leak-scan for anything that shouldn't be in a public repo, consistency with SKILL.md's index.
4. plugin-packager — handles release mechanics: claude plugin validate --strict, a correct version bump (see the versioning trap in references/plugins-and-marketplaces.md), and the CHANGELOG.md entry.

See the repo-root CLAUDE.md for the full workflow and editing conventions.

License

MIT — see LICENSE.