Claude Code's 43-Tool Architecture and Skill Design

If you treat Claude Code as a chatbot that can read files, you are underestimating the system by an order of magnitude. The CCLeaks research community has mapped out an architecture that looks less like a chat interface and more like an operating system: 2,000+ source files, 512K lines of TypeScript, and 43 built-in tools organized into categories that mirror the subsystems of a traditional OS.

Key Takeaways

• Claude Code contains 43 built-in tools across 2,000+ source files and 512K lines of TypeScript -- it is architecturally closer to an operating system than a chatbot.
• Every tool implements a 793-line interface standard with permission gating, concurrency safety flags, schema validation (Zod), and lazy loading controls.
• The query loop runs continuously: user input, system prompt build, API stream, tool execution, permission check, result collection, and repeat until no more tool calls.
• System prompts are assembled from 10+ sources (CLAUDE.md, tools, memory, git context, OS info) -- skill instructions compete for attention in this shared space.
• Skills sit on top of this architecture as the intelligence layer, with MCP providing connectivity and permissions providing safety.

Understanding this architecture does not require access to the source code. It requires understanding the patterns -- because those patterns determine what skills can do, how they get executed, and what separates a good skill from a great one.

Disclaimer: Analyzing Patterns, Not Source Code

What follows is based on CCLeaks research -- community-generated analysis of Claude Code's architecture derived from code artifacts, feature flags, and observable behavior. This content is AI-generated, may contain inaccuracies, and is not affiliated with or endorsed by Anthropic. The architectural patterns described here should be treated as informed analysis, not official documentation. Use this as a mental model for skill design, not as a specification to code against.

The 43-Tool Landscape

According to the CCLeaks analysis, Claude Code's 43 built-in tools span several categories:

File Operations -- reading, writing, editing, and managing files. These are the workhorses. Every skill that touches code relies on these tools, whether it invokes them directly or trusts the agent to use them.

Execution -- running commands in the shell, executing code. The Bash tool is the most powerful and most dangerous tool in the system. It is the escape hatch that lets Claude Code interact with the entire Unix environment.

Search -- finding files by pattern, searching content by regex, navigating codebases. These tools are what make Claude Code effective in large codebases where you cannot just read every file.

Agents -- spawning sub-agents, coordinating parallel work. The multi-agent infrastructure lives here, including the coordination tools described in the CCLeaks research.

MCP -- Model Context Protocol integration points. These are the bridges to external services, databases, APIs, and tools that extend Claude Code's reach beyond the local filesystem.

System -- meta-tools for managing the session, checking permissions, handling state. The plumbing that makes everything else work.

This is not a flat list. It is a layered architecture where tools build on each other and interact in defined ways.

The Tool Interface: 793 Lines of Standard

One of the most revealing details in the CCLeaks analysis is the tool interface specification. At 793 lines, it defines a standard that every tool must conform to. The key methods paint a picture of a carefully designed system:

call() -- the execution method. What the tool actually does when invoked.

description() -- how the tool explains itself to the model. This is not documentation for humans; it is documentation for the AI. The quality of this description directly affects how well the model uses the tool.

prompt() -- additional context injected into the system prompt when the tool is available. This is how tools shape the agent's behavior beyond just being callable.

schema validation (Zod) -- every tool has a typed schema for its inputs. This prevents malformed calls and enables the system to validate requests before execution.

This interface tells skill builders something important: tools in Claude Code are not just functions. They are self-describing, permission-aware, context-injecting components. Skills that understand this model can leverage it. Skills that ignore it leave value on the table.

Permission Gating: Why It Matters for Skills

Every tool implements checkPermissions(). This is the security layer that determines whether a tool invocation is allowed in the current context. The CCLeaks research describes a permission model that considers the session's trust level, the specific arguments being passed, and the tool's risk profile.

Two flags are particularly relevant for skill builders:

isReadOnly() -- does this tool only read data, or does it modify state? A tool that reads a file is fundamentally different from one that writes to it. This distinction determines whether the tool can be used freely or requires permission confirmation.

isDestructive() -- is this tool potentially dangerous? Deleting files, running shell commands with side effects, modifying configuration. Destructive tools get additional scrutiny.

For skill builders, the implication is direct: skills that primarily use read-only tools will face fewer permission barriers than skills that write files or execute commands. If your skill can accomplish its goal with Read, Grep, and Glob instead of Bash and Write, it will have a smoother execution experience.

This does not mean avoiding write operations. It means being intentional about when you need them and structuring your skill so that the destructive operations are concentrated and clearly justified.

Concurrency Safety: The Hidden Constraint

The CCLeaks analysis describes a isConcurrencySafe() method that defaults to false. This means most tools are not safe to run in parallel. In a system that increasingly supports multi-agent coordination, this constraint has significant implications.

If your skill's workflow involves multiple tool calls that could theoretically run in parallel -- searching for files while reading others, for example -- you need to understand that the tool layer may serialize these operations. Designing skills that assume parallel tool execution may produce unexpected behavior.

The practical advice: design your skill's workflow as a sequence of clear steps. Each step should complete before the next begins. If you need parallel investigation, that is a job for multiple sub-agents, not parallel tool calls within a single skill.

Lazy Loading and the Attention Economy

Two flags in the tool interface reveal how Claude Code manages the model's attention: shouldDefer and alwaysLoad.

Tools marked with shouldDefer are not loaded into the model's context until they are needed. This is an optimization: every tool loaded into context consumes tokens and attention. Tools that are rarely needed should not compete for attention with tools that are used constantly.

Tools marked with alwaysLoad are always present in context. These are the essential tools -- file reading, searching, editing -- that the agent needs in virtually every session.

For skill builders, this reveals a design principle: less is more. A skill that requires twenty tools loaded into context is competing with the system's own tools for the model's limited attention. A skill that requires two or three well-chosen tools is more likely to work reliably because the model can focus.

When you design a skill, ask yourself: what is the minimum set of tools this skill needs? Can you accomplish the same outcome with fewer tools? Every tool you add to the required set is a tax on the model's attention budget.

The Factory Pattern: How Tools Are Built

The CCLeaks research describes a buildTool() factory function that merges defaults with overrides. This is the mechanism that creates tool instances with consistent behavior while allowing customization.

The factory pattern has an important implication for extensibility. When new tools are added -- through MCP servers, custom agents, or skills -- they go through the same factory. They get the same permission checking, the same concurrency safety defaults, the same schema validation. The system is designed to be extended without compromising its safety properties.

This means skill builders benefit from the infrastructure even when they do not directly interact with it. When your skill triggers a Bash command, that command goes through the same permission gating as any other tool invocation. The security model protects your users regardless of whether your skill is aware of it.

The System Prompt Assembly

One of the most architecturally significant details in the CCLeaks analysis is that the system prompt is assembled from 10+ sources. This is not a single prompt template. It is a composition system that combines:

• Base agent instructions
• Tool descriptions and prompts
• CLAUDE.md project instructions
• Skill definitions
• MCP server context
• User preferences
• Session state
• Permission context
• Memory (in persistent-memory configurations)
• Team configuration (in multi-agent setups)

Your skill's instructions are one voice in a chorus. This has practical implications: your skill instructions need to be clear, concise, and compatible with the other sources. Instructions that contradict the base system behavior or other loaded skills will create confusion in the model's execution.

Write your skill instructions as if they are being appended to a document you cannot see. Be explicit about what your skill does and does not do. Avoid vague instructions that could be interpreted differently depending on what other context is loaded.

The Query Loop: Understanding Execution Flow

The CCLeaks analysis describes the core execution loop: User input enters the system, gets combined with the assembled system prompt, streams through the model, produces tool_use calls, each call goes through permission checking, executes, and the result loops back into the stream.

This loop is the heartbeat of Claude Code. Every skill invocation rides on this loop. Understanding it helps you design skills that work with the system rather than against it.

Key observations for skill builders:

Tool calls are the unit of action. The model does not take action through its text output. It takes action through tool calls. A skill that needs to accomplish something concrete should guide the model toward specific tool calls, not hope the model figures out the right tools on its own.

Permission checks happen per-call. Each tool invocation is independently checked. A skill that requires ten write operations will trigger ten permission checks. Design your skill's workflow to minimize unnecessary permission interruptions.

The loop continues until the model stops. There is no fixed number of iterations. The model decides when it has accomplished its goal. Skills that provide clear completion criteria help the model know when to stop. Skills with ambiguous goals risk either stopping too early or looping indefinitely.

Extension Points: Where Skills Fit

The CCLeaks analysis identifies six extension points in Claude Code's architecture: MCP servers, Custom agents, Skills, Hooks, Plugins, and CLAUDE.md files.

Skills occupy a specific niche in this hierarchy. They are more structured than CLAUDE.md instructions but less complex than full plugins. They can leverage MCP servers for external integrations but do not need to implement server protocols. They can spawn sub-agents but do not need to manage agent lifecycles.

The sweet spot for skills is domain expertise combined with tool-aware instructions. A skill knows which tools exist and how to use them effectively. It does not just say "review this code" -- it says "use Grep to find test files matching this pattern, use Read to examine the implementation, use Bash to run the test suite, and produce a structured report."

This is the difference between a prompt and a skill. A prompt describes what you want. A skill describes what you want and how to achieve it using the available tools.

The OS Analogy Is Not a Metaphor

Claude Code is an operating system. Not metaphorically. Structurally.

It has a kernel (the query loop and tool execution engine). It has system calls (the 43 built-in tools). It has a permission model (checkPermissions, isReadOnly, isDestructive). It has a process model (agents, sub-agents, daemon mode). It has a filesystem interface (file operation tools). It has a package manager (skill installation). It has configuration files (CLAUDE.md, settings.json, team configs).

Skills are the applications that run on this operating system. And just as the best desktop applications understood their OS deeply -- leveraging system calls efficiently, respecting permission models, working with the process scheduler -- the best skills will understand Claude Code's architecture deeply.

Practical Takeaways for Skill Builders

Be tool-aware. Do not write skills that assume the agent will figure out the tools. Reference specific tools in your skill instructions. "Use the Grep tool to search for..." is more effective than "search the codebase for..."

Minimize your tool footprint. Every tool you require is attention budget consumed. Use the fewest tools that accomplish the job.

Respect the permission model. Structure your skill so that read operations happen first, write operations happen last, and destructive operations are clearly justified. This creates a smoother user experience.

Design for the loop. Your skill instructions will be executed iteratively through the query loop. Provide clear steps, clear completion criteria, and clear error handling guidance.

Compose, do not monolith. The extension point architecture supports composition. A skill that does one thing well and composes with other skills and MCP servers is more valuable than a skill that tries to do everything internally.

Write for the chorus. Your skill instructions share context space with many other sources. Be specific, be concise, and avoid conflicts with standard agent behavior.

The builders who understand the 43-tool architecture -- and how it relates to context compaction and the broader CCLeaks findings -- will build skills that feel native to Claude Code. Not bolted on, but integrated. That is the difference between an app that tolerates the platform and an app that leverages it.

Frequently Asked Questions

What are the 43 built-in tools in Claude Code?

Claude Code's 43 tools span six categories: File Operations (Read, Edit, Write, Glob, Grep, NotebookEdit), Execution (Bash, PowerShell), Search and Fetch (WebFetch, WebSearch, ToolSearch), Agent Tools (Agent, SendMessage, TaskCreate/Get/Update/List/Stop/Output), MCP (MCPTool, ListMcpResources, ReadMcpResource), and System (AskUserQuestion, TodoWrite, Skill, RemoteTrigger, Cron operations). Additional feature-gated tools exist behind build flags.

What is the tool interface standard?

Every tool implements a 793-line interface that includes call() for execution, description() and prompt() for documentation, Zod schema validation for input, checkPermissions() for security gating, isConcurrencySafe() and isDestructive() for safety classification, and shouldDefer/alwaysLoad for lazy loading. The buildTool() factory pattern merges defaults with overrides.

How does the query loop work in Claude Code?

The query loop cycles: user input is wrapped into a message, the system prompt is built from 10+ sources, the message streams to the Claude API, response tokens are parsed for tool_use blocks, tools are looked up and permission-checked, StreamingToolExecutor runs them (potentially in parallel), results loop back as tool_result blocks, and the cycle repeats until no more tool calls are needed.

What is a tool-aware skill?

A tool-aware skill is designed with knowledge of Claude Code's built-in tools and their properties. Instead of writing raw Bash commands, it leverages the Edit tool (simpler permission classification). It respects concurrency safety, uses read operations before writes, and structures its workflow to flow through the permission model cleanly.

---

Explore production-ready AI skills at aiskill.market/browse or submit your own skill to the marketplace.