# allowed-tools Field Guide > Comprehensive guide to using the allowed-tools frontmatter field in Claude Code Skills. - Skill: `tools-only/allowed-tools-field-guide` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/allowed-tools-field-guide` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/allowed-tools-field-guide/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/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 ```yaml --- 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____` - 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: ```yaml # 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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml allowed-tools: Read, WebFetch, WebSearch, Write ``` **Use cases:** - Research tasks - Documentation lookup - API reference checking ### Deployment Skills Skills that deploy code (use with caution): ```yaml 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:** ```yaml allowed-tools: Read, Write, Edit, Bash, WebFetch, WebSearch ``` ✅ **Appropriately restricted:** ```yaml allowed-tools: Read, Grep, Glob ``` ### Dangerous Patterns to Avoid **1. Unrestricted Bash** ```yaml # Dangerous - allows any shell command allowed-tools: Bash ``` **Better:** ```yaml # Restricted to specific commands allowed-tools: Bash(git:*), Bash(npm test:*) ``` **2. Write + Bash Together** ```yaml # 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** ```yaml # Too broad if MCP server has many tools allowed-tools: mcp__github__* ``` **Better:** ```yaml # 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: ```markdown ## 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 ```yaml 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 ```yaml 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 ```yaml 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.