allowed-tools Field Guide

allowed-tools Field Guide

Comprehensive guide to using the allowed-tools frontmatter field in Claude Code Skills.

Overview

The allowed-tools field is a Claude Code-specific feature that restricts which tools Claude can use when a Skill is active. This provides three key benefits:

1. Security - Prevent Skills from performing unintended or dangerous operations
2. Focus - Keep Skills constrained to their specific purpose
3. User Experience - Avoid permission prompts for pre-approved tools

Syntax

---
name: my-skill
description: Skill description
allowed-tools: Read, Write, Edit, Bash(git:*), Grep
---

Format:

• Comma-separated list of tool names
• Tool names are case-sensitive
• Bash patterns use parentheses with glob patterns
• Whitespace around commas is optional

Available Tools

Complete reference of all tools available in Claude Code for use in allowed-tools field.

1. File Operations

Read - Read files from filesystem

• Supports images, PDFs, Jupyter notebooks, and text files
• Use for: Code analysis, documentation extraction, examining configurations
• Example: Read to examine source files

Write - Create new files

• Overwrites if file already exists
• Use for: Generating new content, report creation, template instantiation
• Example: Write to create new documentation files

Edit - Modify existing files with exact string replacements

• Preserves file structure and formatting
• Use for: Code refactoring, configuration updates, in-place modifications
• Example: Edit to update configuration values

Glob - Find files by glob pattern

• Supports patterns like **/*.js, src/**/*.tsx
• Use for: File discovery, locating test files, finding configs
• Example: Glob to find all test files matching **/*_test.py

Grep - Search file contents with regex patterns

• Supports full regex syntax and output modes
• Use for: Code search, finding function definitions, log analysis
• Example: Grep to search for specific patterns in code

2. Code Editing

NotebookEdit - Edit Jupyter notebook cells

• Supports insert, delete, and replace operations
• Use for: Working with .ipynb files
• Example: NotebookEdit to modify notebook cells

3. Command Execution

Bash - Execute bash commands in persistent shell

• Can be restricted with patterns (see Bash Tool Patterns below)
• Use for: Running tests, git operations, build processes
• Example: Bash(git:*) to allow git commands only

Bash Patterns (restrict bash to specific commands):

• Bash(git:*) - Git commands only
• Bash(npm:*) - npm commands only
• Bash(docker:*) - Docker commands only
• Bash(pytest:*) - pytest commands only
• Bash(bq:*) - BigQuery CLI commands only
• Bash - All bash commands (use with caution)

BashOutput - Retrieve output from background bash shells

• Use for: Monitoring long-running background processes
• Example: BashOutput to check test run progress

KillBash - Terminate running background bash shells

• Use for: Cleaning up background processes
• Example: KillBash to stop a background server

4. Web and Search

WebFetch - Fetch and process web content with AI

• Converts HTML to markdown
• Use for: API documentation lookup, fetching external data
• Example: WebFetch to retrieve documentation from URLs

WebSearch - Search the web for up-to-date information

• Provides current information beyond model cutoff
• Use for: Research, fact-checking, finding recent information
• Example: WebSearch to find latest library versions

5. Task Management

TodoWrite - Create and manage structured task lists

• Use for: Planning complex workflows, tracking progress
• Example: TodoWrite to create task breakdown

Task - Launch specialized subagents for complex tasks

• Delegates to specialized agents with their own context
• Use for: Complex multi-step workflows, specialized analysis
• Example: Task to delegate to code-reviewer subagent

6. Workflow Control

ExitPlanMode - Exit planning mode and present plan to user

• Use for: Finalizing plans before implementation
• Example: ExitPlanMode after creating implementation plan

SlashCommand - Execute custom slash commands

• Use for: Triggering user-defined workflows
• Example: SlashCommand to run /deploy command

AskUserQuestion - Ask user questions during execution

• Use for: Gathering preferences, clarifying requirements
• Example: AskUserQuestion to choose deployment target

7. MCP Integration

ListMcpResources - List available MCP resources

• Use for: Discovering MCP server capabilities
• Example: ListMcpResources to see available resources

ReadMcpResource - Read specific MCP resource content

• Use for: Accessing MCP resource data
• Example: ReadMcpResource to read database schemas

MCP Server Tools - Tools provided by installed MCP servers

• Format: mcp__<server-name>__<tool-name>
• Inherited by default if allowed-tools field is omitted
• Example: mcp__github__create_issue, mcp__slack__send_message

To see available MCP tools, use /mcp in Claude Code.

Bash Tool Patterns

The Bash tool supports glob patterns to allow specific command categories:

# Allow all git commands
Bash(git:*)

# Allow specific git commands
Bash(git status:*), Bash(git diff:*)

# Allow npm commands
Bash(npm:*)

# Allow multiple command families
Bash(git:*), Bash(npm:*), Bash(ls:*)

# Allow all bash (not recommended for security)
Bash

Pattern syntax:

• command:* - All invocations of command
• command subcommand:* - Specific subcommand
• * - All bash (use sparingly)

Common Patterns

Read-Only Skills

Skills that should never modify files:

allowed-tools: Read, Grep, Glob

Use cases:

• Code analysis
• Documentation extraction
• Security auditing
• Read-only data analysis

File Editing Skills

Skills that modify files but don't execute code:

allowed-tools: Read, Write, Edit, Glob, Grep

Use cases:

• Code refactoring
• Template generation
• Configuration updates
• Documentation generation

Git Integration Skills

Skills that work with git repositories:

allowed-tools: Read, Write, Edit, Bash(git:*), Grep, Glob

Use cases:

• Automated committing
• Branch management
• Code review workflows
• Repository analysis

Testing Skills

Skills that run tests and analyze results:

allowed-tools: Read, Bash(npm test:*), Bash(pytest:*), Grep, Glob

Use cases:

• Test execution
• Test result analysis
• Coverage reporting

Web Research Skills

Skills that gather information from the web:

allowed-tools: Read, WebFetch, WebSearch, Write

Use cases:

• Research tasks
• Documentation lookup
• API reference checking

Deployment Skills

Skills that deploy code (use with caution):

allowed-tools: Read, Bash(git:*), Bash(npm:*), Bash(docker:*), Grep

Use cases:

• Deployment workflows
• Build processes
• CI/CD integration

Security Considerations

Principle of Least Privilege

Always grant the minimum tools necessary:

❌ Too permissive:

allowed-tools: Read, Write, Edit, Bash, WebFetch, WebSearch

✅ Appropriately restricted:

allowed-tools: Read, Grep, Glob

Dangerous Patterns to Avoid

1. Unrestricted Bash

# Dangerous - allows any shell command
allowed-tools: Bash

Better:

# Restricted to specific commands
allowed-tools: Bash(git:*), Bash(npm test:*)

2. Write + Bash Together

# Potentially dangerous - can create and execute files
allowed-tools: Write, Bash

Only combine these when the Skill's purpose requires it and you trust the Skill's implementation.

3. MCP Tools Without Specificity

# Too broad if MCP server has many tools
allowed-tools: mcp__github__*

Better:

# Specific tools only
allowed-tools: mcp__github__create_issue, mcp__github__add_comment

Auditing Skill Tool Usage

When reviewing Skills (especially from third parties), check:

1. Does the Skill request more tools than it needs?
2. Are Bash patterns specific enough?
3. Does the Skill combine dangerous tool combinations?
4. Are MCP tools from trusted servers?

Determining Tools for Your Skill

Step 1: List Required Operations

What does your Skill need to do?

• Read files? → Read
• Modify files? → Edit or Write
• Find files? → Glob
• Search code? → Grep
• Execute commands? → Bash(...)
• Access web? → WebFetch or WebSearch

Step 2: Choose Minimum Set

Start with the smallest set and add only when necessary.

Step 3: Test and Refine

Test the Skill. If Claude can't complete tasks, review what additional tools are needed.

Step 4: Document Tool Usage

In your SKILL.md, explain why each tool is needed:

## Tool Requirements

This skill requires the following tools:

- **Read**: To examine source files for analysis
- **Grep**: To search for specific patterns in code
- **Glob**: To find all test files matching `*_test.py`
- **Bash(pytest:*)**: To execute tests and capture output

Examples from claude-code-meta Skills

claude-code-hooks Skill

allowed-tools: Read, Write, Edit, Bash, Glob, Grep

Reasoning: Hooks skill needs to create hook scripts (Write), modify configs (Edit), execute hooks for testing (Bash), and search for examples (Grep, Glob).

claude-code-slash-commands Skill

allowed-tools: Read, Write, Edit, Bash, Glob, Grep

Reasoning: Commands skill creates command files (Write), modifies existing ones (Edit), tests command execution (Bash), and searches for command patterns (Grep, Glob).

claude-code-mcp Skill

allowed-tools: Read, Bash, Grep

Reasoning: MCP configuration skill reads config files (Read), executes claude mcp commands (Bash), and searches for MCP patterns (Grep). Notably does NOT include Write/Edit as MCP configuration is typically done via CLI, not file editing.

Troubleshooting

Skill Can't Complete Task

Symptom: Claude reports it can't use a required tool.

Solution: Add the tool to allowed-tools or verify the tool name spelling.

Permission Prompts Appear

Symptom: User gets permission prompts despite allowed-tools.

Solution: Ensure the tool is listed in allowed-tools. Check for typos in tool names (they're case-sensitive).

Skill Uses Wrong Tool

Symptom: Claude uses an unexpected tool to accomplish a task.

Solution: This may indicate the allowed-tools list is too permissive. Restrict to only necessary tools.

Bash Pattern Not Working

Symptom: Bash commands are blocked despite pattern.

Solution: Verify pattern syntax:

• Bash(command:*) not Bash(command*)
• Bash(git status:*) for specific subcommand
• Patterns are exact match on command prefix

Best Practices

1. Start Restrictive - Begin with minimal tools and add as needed
2. Document Choices - Explain why each tool is required
3. Test Thoroughly - Verify the Skill works with the restricted toolset
4. Audit Regularly - Review and remove unnecessary tools
5. Use Patterns - For Bash, use specific patterns instead of wildcard
6. Think Security - Consider what could go wrong with each tool combination

Reference: Complete Tool List

See the Claude Code documentation for the complete list of available tools and their capabilities.

Common tools include:

• File: Read, Write, Edit, Glob, Grep
• Execution: Bash, Task
• Web: WebFetch, WebSearch
• Claude Code: Skill, SlashCommand, AskUserQuestion
• MCP: mcp____

For MCP tools, use /mcp in Claude Code to see available servers and their tools.