Allowed Tools

A skill that can do anything is a skill you cannot trust. The allowed-tools frontmatter field lets you explicitly declare which tools a skill is permitted to use. This creates a safety boundary: the skill can only perform actions you have explicitly authorized. It also helps the agent stay focused, because a smaller tool set means fewer options to consider and faster, more predictable execution.

Why Restrict Tools?

Without allowed-tools, a skill has access to every tool the agent supports: Bash, Read, Write, Edit, Glob, Grep, web search, and more. This is fine for general conversation, but skills represent specific workflows where broad access is unnecessary and potentially dangerous.

Consider a skill that generates commit messages:

It needs to read the git diff. It does not need to write files.
It needs to run git diff --cached. It does not need to run rm -rf.
It should produce text output. It does not need web search.

By restricting tools, you make the skill's capabilities explicit and auditable. Anyone reading the frontmatter immediately understands what the skill can and cannot do.

Basic Syntax

The allowed-tools field is a YAML list of tool names and optional argument patterns:

commit-msg/SKILL.md

---
description: Generate a commit message for staged changes
allowed-tools:
  - Bash(git diff --cached)
  - Bash(git log --oneline -5)
---

Look at the staged changes and recent history.
Write a conventional commit message.

This skill can only run two specific git commands. Any attempt to use Bash for other purposes, or to use tools like Write or Edit, will be blocked.

Available Tool Names

Here are the tools you can reference in allowed-tools:

tool-reference.md

# File operations
Read          # Read file contents
Write         # Create or overwrite files
Edit          # Make targeted edits to existing files
Glob          # Find files by pattern
Grep          # Search file contents

# Shell access
Bash          # Run shell commands (supports glob patterns)

# Task management
Task          # Create and manage subtasks
TodoRead      # Read the todo list
TodoWrite     # Write to the todo list

# Web
WebSearch     # Search the web
WebFetch      # Fetch a URL

# Code intelligence
LS            # List directory contents

Bash Glob Patterns

The Bash tool is special because it supports glob-style patterns for restricting which commands can be run. This is where allowed-tools becomes truly powerful.

Exact Commands

Exact match

allowed-tools:
  - Bash(git diff --cached)      # Only this exact command
  - Bash(npm test)               # Only this exact command

Wildcard Patterns

Wildcard patterns

allowed-tools:
  - Bash(git *)                  # Any git subcommand
  - Bash(npm run *)              # Any npm script
  - Bash(docker compose *)       # Any docker compose command
  - Bash(*)                      # Any command (full access)

Combining Patterns

Combined tool set

allowed-tools:
  - Bash(git *)                  # Full git access
  - Bash(npm test *)             # Test commands with any args
  - Bash(npm run lint *)         # Lint commands with any args
  - Bash(cat *)                  # Read any file via cat
  - Read                         # Also allow the Read tool
  - Grep                         # And the Grep tool

⚠️Bash(*) is unrestricted

Using Bash(*) grants the skill permission to run any shell command. This effectively removes the safety boundary for shell access. Only use it for skills where you genuinely need unrestricted shell access, such as deployment or environment setup skills that you trust completely.

Real-World Examples

Read-Only Analysis Skill

A skill that analyzes code but never modifies anything:

analyze-complexity/SKILL.md

---
description: Analyze code complexity and suggest refactoring targets
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash(wc -l *)
  - Bash(find . -name '*.ts' -type f)
---

Analyze the codebase for complexity hotspots:

1. Find the largest files by line count
2. Look for deeply nested functions
3. Identify functions with many parameters
4. Report the top 10 refactoring candidates

Deployment Skill

A skill with broad but still scoped access for deployments:

deploy-staging/SKILL.md

---
description: Deploy the application to staging environment
allowed-tools:
  - Bash(git *)
  - Bash(npm run build)
  - Bash(npm run test)
  - Bash(docker compose *)
  - Bash(curl -X POST https://api.staging.example.com/deploy/*)
  - Read
---

Deploy to staging with these safety checks:

1. Ensure all tests pass: `npm run test`
2. Ensure the build succeeds: `npm run build`
3. Verify we're on the correct branch
4. Run `docker compose up -d` to deploy
5. Hit the health check endpoint to verify

Focused Writing Skill

A skill that creates files but has no shell access:

new-component/SKILL.md

---
description: Create a new React component with test and story files
allowed-tools:
  - Read
  - Write
  - Glob
---

Create a new React component named $1 with:

1. The component file: src/components/$1/$1.tsx
2. A test file: src/components/$1/$1.test.tsx
3. A Storybook story: src/components/$1/$1.stories.tsx

Read existing components in src/components/ to match the
project's patterns and conventions.

💡Start restrictive, expand as needed

When creating a new skill, start with the minimum set of tools and add more only when you discover the skill needs them. It is much easier to add a tool than to audit why a skill did something unexpected with broad permissions.

What Happens Without allowed-tools?

If you omit the allowed-tools field entirely, the skill inherits whatever tools are available in the current session. This is convenient for quick prototyping but should be avoided for production skills that are shared with a team or stored in version control.

prototype/SKILL.md

---
description: Quick prototype skill (no tool restrictions)
---

# No allowed-tools field means full tool access

This skill can use any tool the agent supports.
Fine for personal experimentation, risky for shared skills.

Debugging Tool Restriction Errors

When the agent tries to use a tool that is not in the allowed-tools list, the tool call will be blocked and the agent will receive an error message. It will typically adapt by finding an alternative approach using only the permitted tools.

Example: tool blocked by allowed-tools

> /commit-msg Agent: Let me check the staged changes... [Tool blocked: Write is not in allowed-tools for this skill] Agent: I'll focus on reading the diff and generating the message. [Runs: git diff --cached] ✓ [Runs: git log --oneline -5] ✓ Here's your commit message: feat(auth): add bearer token prefix stripping

What's Next

With tool restrictions in place, you can build skills that are safe and predictable. The next lesson covers supporting files — templates, scripts, and reference documents that live alongside your SKILL.md and extend its capabilities.