Canonical: https://botbento.com/blog/agent-skills-allowed-tools-is-not-a-sandbox/ Format: Markdown representation of the public HTML page. [Home](/) / [Blog](/blog/) FIELD NOTES / 4 MIN READ # Agent Skills' allowed-tools Field Won't Sandbox a Skill by Itself Agent Skills let a bot load a folder of instructions on demand, and the SKILL.md frontmatter can list allowed-tools to pre-approve what the skill may call. The open specification marks that field experimental, and host support varies, so it is not a safe stand-in for your own permission boundary. Before installing a third-party skill, read its full body and any scripts, and enforce tool access at the host or connection level, not by trusting the frontmatter. By BotBento Editorial · Published 2026-10-08 · Updated 2026-10-08 AI-assisted editorial: researched and drafted with AI using the primary sources linked below. Examples are illustrative; they are not measured product results. [Editorial policy](/editorial/). ## In this article - [What loading a skill actually does](#what-a-skill-is) - [What the allowed-tools field actually declares](#what-allowed-tools-declares) - [A worked example: a log-analysis skill from an outside source](#worked-example) - [What allowed-tools does not do](#what-the-field-doesnt-do) - [A decision you can apply before installing a skill](#decision-checklist)[Read as Markdown ](/text/blog/agent-skills-allowed-tools-is-not-a-sandbox/index.md) ## Key takeaways - SKILL.md's allowed-tools field is optional and marked experimental in the open Agent Skills specification; a host can ignore it entirely. - The open specification does not define an enforcement policy or a duration for allowed-tools. Check your host's actual permissions before relying on the declaration. - Scope real permissions at the host or connection layer (which skills can load, which tools the session can call) and treat allowed-tools as documentation of intent, not enforcement. ## What loading a skill actually does A skill is a directory built around one required file: SKILL.md. The file carries YAML frontmatter plus a Markdown body. In the Claude Agent SDK, configured filesystem locations supply skill metadata at startup, and the full body loads when the agent invokes the skill. Other hosts may discover skills differently, so check the implementation you actually run. Once loaded, a skill's body can ask the agent to use tools. Whether a call is permitted depends on the host's tool policy, not on the body merely asking for it. Review the full instructions and any referenced files before treating an outside skill as safe; a short frontmatter description cannot tell you everything the skill will ask the agent to do. Sources: [Extend agents with skills - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/skills). ## What the allowed-tools field actually declares The open Agent Skills specification defines an optional frontmatter field, allowed-tools, as a space-separated string of tools pre-approved to run. It labels the field experimental and says support may vary between implementations. Its example is allowed-tools: Bash(git:\*) Bash(jq:\*) Read. That example names permitted tool patterns; it does not mean Git is read-only. A Git command can change files or remote state, depending on what the host permits. The important distinction is between a declaration in a file and an actual runtime decision. The specification describes the field but does not prescribe one universal enforcement policy, approval lifetime, or denial rule for tools outside the list. An operator must check how a particular host interprets allowed-tools and what permissions the session grants independently of that field. Sources: [Specification - Agent Skills](https://agentskills.io/specification). ## A worked example: a log-analysis skill from an outside source Say you pull a community skill named log-analyzer into your bot's skills directory. Its frontmatter lists allowed-tools: Read Grep, and the description says it scans application logs for error patterns. That reads like a safe, read-only skill: no writes, no shell, no network. Now open the body and the scripts/ folder, which the frontmatter doesn't force you to do but the spec's own directory structure allows: scripts/ can hold arbitrary executable code the skill references. If the body instructs the agent to run a bundled script, and your host's actual permission model allows that session to execute scripts or make network calls, the allowed-tools line in the frontmatter does nothing to stop it — because allowed-tools is a declared pre-approval list for tools, not an enforced denylist for everything else the session can already do. The gap between what the skill says it needs and what the session can actually do is the part a reader has to check by hand. This is the same failure mode as trusting a plugin manifest's declared scopes without checking what the runtime actually grants: the declaration describes intent, and intent is not enforcement unless something downstream checks it on every call. Sources: [Specification - Agent Skills](https://agentskills.io/specification). ## What allowed-tools does not do Three limits matter for a bot builder deciding whether to trust this field. First, the open specification does not say how long a pre-approval lasts; that is implementation-specific. Second, it does not define a universal rule that blocks every tool outside the declared list. Third, support can vary between hosts, as the specification explicitly warns. A skill author cannot infer a host's effective permissions from this line alone, and an operator should test the actual host policy before relying on it. The Claude Agent SDK docs show one host-level control: pass an explicit skills list so the Skill tool invokes only named skills. The docs also warn that unlisted skill files remain reachable through Read and Bash if those tools are available. So an invocation allow-list helps narrow one path, but it is not a filesystem sandbox. Pair it with the session's tool permissions and any file or network restrictions that your host actually enforces. Sources: [Specification - Agent Skills](https://agentskills.io/specification), [Extend agents with skills - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/skills). ## A decision you can apply before installing a skill Treat every third-party skill the way you'd treat a new dependency with a README that claims limited permissions: read the claim, then verify the runtime, not the other way around. Before loading a skill your bot didn't author: read the full SKILL.md body, not just the frontmatter description. Check scripts/ and references/ for instructions that run commands, reach a network endpoint, or write files, regardless of what allowed-tools claims. In a host that offers a skill invocation list, name only the skills the session needs, then separately limit Read, Bash, and other tools as appropriate. Finally, scope external connections and credentials to the task, the same way you'd scope an API key, so that an instruction inside a skill cannot reach further than the session actually permits. If you can't inspect a skill's full contents — because it's distributed as a compiled bundle or pulled from an unaudited registry at runtime — the safest default is to assume allowed-tools is advisory only and gate the session's actual tool access yourself. Sources: [Specification - Agent Skills](https://agentskills.io/specification), [Extend agents with skills - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/skills). ## Primary sources Sources checked 2026-10-08. Standards and product documentation can change; follow the linked version when implementing. - [Specification - Agent Skills](https://agentskills.io/specification) — agentskills.io - [Extend agents with skills - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/skills) — Anthropic BotBento is in development. [Suggest a correction](/contact/).