What Does allowed-tools Mean in a SKILL.md?

The Short Answer

allowed-tools (or ## Tools in SKILL.md format) is the permission boundary that defines what an AI agent skill is allowed to do.

Think of it like the permissions you grant a mobile app — but instead of "access to camera" or "location services," it's "can run bash commands" or "can make HTTP requests."

Understanding the Syntax

Basic Format

## Tools
- bash
- curl
- git
- python

This skill can:

✅ Execute any bash command
✅ Make HTTP requests with curl
✅ Run git commands
✅ Execute Python code

Claude Code Format

{
  "name": "Database Skill",
  "allowed-tools": ["bash", "psql", "file"],
  "description": "Query PostgreSQL databases"
}

GitHub Copilot Format

skills:
  - name: web-search
    tools:
      - curl
      - grep

Why This Matters

Real-World Example: The Dangerous Skill

## Description
"A simple skill to format JSON files"

## Tools
- bash
- curl
- python

What the author claims: It formats JSON.

What it can actually do:

Execute any shell command (bash)
Exfiltrate data to external servers (curl)
Run arbitrary Python code (python)

The gap: allowed-tools grants far more power than the description suggests.

Tool-by-Tool Risk Guide

🔴 CRITICAL Risk — Use Extreme Caution

Tool	What It Enables	Real Risk
`bash` / `sh` / `zsh`	Execute any shell command	Complete system compromise
`curl` / `wget`	HTTP requests, downloads	Data exfiltration, malware download
`sudo`	Elevated privileges	Privilege escalation, system takeover
`eval`	Dynamic code execution	Code injection, arbitrary execution
`exec`	Replace process	Process hijacking
`ssh` / `scp`	Remote access	Lateral movement, unauthorized access

When to allow: Almost never. If a skill needs these, it needs extreme scrutiny.

🟡 HIGH Risk — Review Carefully

Tool	What It Enables	Real Risk
`python` / `python3`	Python code execution	Arbitrary code, package installation
`node` / `nodejs`	JavaScript execution	NPM package risks, code execution
`docker`	Container operations	Container escape, host access
`make`	Build execution	Arbitrary command execution via Makefile
`npm` / `pip` / `gem`	Package management	Supply chain attacks, malicious packages

When to allow: When the skill's purpose genuinely requires it (e.g., a Python linting skill needs python).

🟢 LOW Risk — Generally Safe

Tool	What It Enables	Real Risk
`git`	Version control	Very low (read-only operations)
`grep`	Text search	None (read-only)
`ls`	Directory listing	None (information disclosure only)
`cat` / `head` / `tail`	File reading	Low (depends on what files)
`find`	File search	Low (information disclosure)
`diff`	File comparison	None (read-only)
`awk` / `sed`	Text processing	Low (depends on usage)

When to allow: Generally safe for most skills. Still verify the context.

Common Patterns Explained

Pattern 1: The "Everything" Skill

## Tools
- bash
- curl
- python
- node
- docker

Translation: This skill can do literally anything on your system.

Risk level: 🔴 CRITICAL

Should you install it? Only if:

You wrote it yourself
You fully trust the author
You've audited every line of code

Pattern 2: The Read-Only Skill

## Tools
- git
- grep
- ls
- cat

Translation: This skill can read files and git history but can't modify your system.

Risk level: 🟢 LOW

Should you install it? Probably safe, but verify it's not reading sensitive files.

Pattern 3: The Database Skill

## Tools
- psql
- file
- cat

Translation: Can query PostgreSQL and read files.

Risk level: 🟡 MEDIUM

What to check:

Does it have database credentials?
Can it read ~/.pgpass or connection files?
What queries can it run?

Pattern 4: The Web API Skill

## Tools
- curl
- jq
- grep

Translation: Can make HTTP requests and process JSON.

Risk level: 🟡 HIGH (because of curl)

What to check:

What endpoints does it call?
Does it send sensitive data?
Can the URLs be manipulated?

Platform Differences

Claude Code

{
  "allowed-tools": ["tool1", "tool2"],
  "permissions": {
    "read_only": false
  }
}

Explicit allowed-tools array
Optional permissions object
Can specify read_only: true for safer defaults

GitHub Copilot

skills:
  - id: custom-skill
    tools:
      - git
      - bash

YAML configuration
tools array in skill definition
Less granular than Claude Code

OpenAI Codex

Codex uses a similar format to Claude Code but with some differences:

{
  "tools": ["bash", "python"],
  "sandbox": {
    "network": false,
    "filesystem": "read_only"
  }
}

sandbox options for additional constraints
network: false prevents external calls
filesystem: "read_only" prevents modifications

Red Flags to Watch For

🚩 Flag 1: Too Many Tools

## Tools
- bash
- curl
- wget
- python
- node
- docker
- ssh
- sudo

Problem: No legitimate skill needs all of these. This is either:

Poorly designed (over-privileged)
Malicious (maximizing attack surface)

🚩 Flag 2: Dangerous Combinations

## Tools
- bash
- curl

Problem: Can execute commands AND exfiltrate data. Classic combination for:

Data theft
Reverse shells
Malware delivery

🚩 Flag 3: Mismatched Tools

## Description
"A skill to check git commit messages"

## Tools
- bash
- curl
- nmap
- metasploit

Problem: Why does a git skill need network scanning and penetration testing tools?

🚩 Flag 4: Dynamic Execution

## Tools
- bash
- eval
- exec

Problem: Can execute arbitrary code passed as arguments. Extremely dangerous.

Best Practices for Authors

1. Principle of Least Privilege

Only request tools your skill actually needs:

## Bad: Over-privileged
## Tools
- bash
- curl
- python
- node
- docker

## Good: Minimal permissions
## Tools
- git
- grep

2. Document Why

## Tools
- psql

## Why
This skill queries PostgreSQL databases to generate reports.
It only runs SELECT statements and does not modify data.

3. Use Read-Only When Possible

{
  "allowed-tools": ["git", "grep", "cat"],
  "permissions": {
    "read_only": true
  }
}

4. Avoid Shell Execution

Instead of:

## Tools
- bash

## Commands
- bash -c "git log --oneline"

Use:

## Tools
- git

## Commands
- git log --oneline

Best Practices for Users

1. Verify Before Installing

Always check allowed-tools before installing a skill. If you see:

bash + curl
sudo
eval

Stop and audit the full skill code.

2. Prefer Read-Only Skills

When possible, choose skills with read_only: true or minimal tool sets.

3. Test in Isolation

# Create isolated test environment
mkdir ~/skill-test
cd ~/skill-test

# Install and test here first
# Verify behavior before using in production

4. Scan With SkillShield

npx skillshield scan ./suspicious-skill/

SkillShield flags over-privileged skills automatically.

FAQ

Q: Can a skill with only "git" still be dangerous?

A: Yes, but less so. A git skill could:

Clone malicious repositories
Exfiltrate data via git commits to external repos
Modify git hooks

However, it can't directly execute arbitrary code or access files outside git repos.

Q: What's the difference between "tools" and "allowed-tools"?

A: They're the same thing, just different naming:

## Tools in SKILL.md markdown format
allowed-tools in Claude Code JSON format
tools in GitHub Copilot YAML format

Q: Can I restrict a skill's tools after installation?

A: Generally no. The skill defines its own tool requirements. You can:

Modify the SKILL.md (if you maintain a fork)
Use sandboxing tools to restrict runtime behavior
Choose a different skill with fewer permissions

Q: Are there any safe tools?

A: No tool is 100% safe in all contexts, but these are generally low-risk:

git (for reading history)
grep (for searching)
ls (for listing)
cat (for reading files — but verify which files)

Q: Why would a skill need bash?

A: Legitimate reasons:

Complex multi-step operations
Using tools not in the standard tool list
Legacy script integration

However, most modern skills should use specific tools instead of bash when possible.

The Bottom Line

allowed-tools is the security boundary for AI agent skills.

Every tool you grant is a permission you're giving to code written by someone else. Before installing any skill:

Read the allowed-tools / ## Tools section
Understand what each tool enables
Verify the tools match the skill's stated purpose
Be extra cautious with bash, curl, sudo, eval
When in doubt, scan with SkillShield

Remember: You wouldn't install a mobile app that requests every possible permission. Treat AI agent skills the same way.

Related Resources

How to Audit Agent Skills: skillshield.dev/blog/how-to-audit-agent-skills
Agent Skills Security Checklist: skillshield.dev/checklist
SkillShield Scanner: skillshield.dev
Claude Code Docs: docs.claude.com/skills