allowed-tools
Claude CodeDefinition
A skill frontmatter field that whitelists which tools a skill can use during its execution. Enforces the principle of least privilege for skills. Use specific tool names or MCP server patterns (e.g., 'mcp__github__*' allows all GitHub MCP tools).
Example Usage
Set allowed-tools: [read_file, list_directory] for an analysis skill to prevent it from writing files even if asked.
Why It Matters for the CCA-F Exam
The CCA-F exam tests whether candidates understand how to apply least-privilege principles inside Claude Code skills. Expect questions that ask you to identify which frontmatter field restricts tool access, or to choose the correct allowed-tools configuration for a scenario (e.g., a read-only audit skill that must never write files).
In Depth
The allowed-tools field in a skill's CLAUDE.md frontmatter is the primary mechanism for enforcing least-privilege access within Claude Code. When you define a skill, you can whitelist the exact set of tools — built-in Claude Code tools, MCP server tools, or both — that the skill is permitted to invoke. Any tool not on that list is silently blocked, even if the model would otherwise attempt to call it.
This matters because skills are reusable, often shared across a team, and may be invoked in contexts where their author didn't anticipate every downstream risk. An analysis skill that only needs to read files has no business writing to disk or spawning shell commands. Without allowed-tools, a prompt injection inside a file the skill reads could coerce the model into performing destructive actions. With allowed-tools: [Read, Glob], that attack surface collapses — the tool calls simply won't execute.
The field accepts an array of tool name strings. Built-in tools use their camelCase names (Read, Write, Bash, Glob, Edit). MCP server tools follow the mcp__<server>__<tool> naming pattern. Glob patterns are supported: mcp__github__* whitelists every tool on the configured GitHub MCP server without enumerating each one individually.
A common design pattern pairs allowed-tools with context: fork — run the skill in an isolated context so its output doesn't pollute the main conversation, and restrict the tools it can reach so it can't cause side effects. Together these two frontmatter fields produce skills that are both safe to share and easy to reason about. The full skill-frontmatter spec defines several other fields (description, model, context) that work alongside allowed-tools to shape a skill's behavior.
The least-privilege principle applies directly here: every skill should be granted exactly the tools it requires and nothing more. This is especially important for skills that operate on external data — web fetches, file reads from untrusted repositories, user-supplied inputs — where the content itself could attempt to redirect the model's behavior. Scoping tools tightly converts those risks from "potential arbitrary code execution" into "harmless refused tool call."
For the exam, think of allowed-tools as the per-skill equivalent of the global permissions block in .claude/settings.json. The settings file governs what the entire Claude Code session can do; allowed-tools governs what a single skill invocation can do, and it can only be a subset of what the session permits. You cannot use allowed-tools to grant a skill access to a tool that the enclosing session has not already permitted — the effective set is always the intersection.
The Tool Distribution & Least Privilege concept on this platform goes deeper into threat-modelling tool access across multi-agent systems, which is examined alongside allowed-tools in Domain 3 questions. Understanding both layers — session-level permissions and skill-level allowed-tools — is essential for answering questions about defense-in-depth in Claude Code deployments.
Frequently Asked Questions
Does allowed-tools override the global settings.json permissions?
No — it narrows them. A skill can only be granted tools that the session already permits. If `Bash` is blocked at the session level, adding it to `allowed-tools` does nothing. The effective tool set is the intersection of session-level permissions and the skill's allowed-tools list.
What happens when a skill tries to call a tool not in its allowed-tools list?
The tool call is blocked and Claude Code surfaces an error or silently refuses the call, depending on the invocation context. The model is informed that the tool is unavailable and typically handles the failure gracefully — for example, by returning a partial result or explaining that a certain action is outside its permitted scope.
Can I use wildcards like mcp__github__* in the allowed-tools list?
Yes. Glob patterns are supported for MCP tool names. `mcp__github__*` permits every tool exposed by the GitHub MCP server. This is useful when the exact set of MCP tools a server exposes may change over time, or when a skill genuinely needs full access to one MCP server but should be isolated from all others.