YAML allowed-tools

The allowed-tools field in skill frontmatter does not enforce tool restrictions at runtime; use agent tools: definitions instead.

How It Works

Skill definitions accept an allowed-tools field in YAML frontmatter, supporting both list and comma-delimited formats:

allowed-tools:
  - Read
  - Grep
  - Bash

or

allowed-tools: Read,Grep,Bash

The field parses without error. However, tests revealed it does not restrict which tools a skill can invoke.

What the Test Found

Three test attempts ran in January 2026. Tests 1 and 2 declared allowed-tools in skill frontmatter using both list and comma formats; Bash remained callable despite no restriction declared. Both returned INCONCLUSIVE—the lists parsed, but tool access was not constrained.

Test 3 applied a different mechanism: defining a custom agent with an explicit tools: field. That agent successfully blocked Bash. The result: PASS.

Why It Matters

Tool restrictions are a sandboxing primitive. If you need to limit a skill's access, do not rely on allowed-tools in the skill frontmatter. Instead, assign the skill to a custom agent and define the tools: list in the agent definition. The agent boundary enforces; the skill field does not (or requires additional undocumented configuration).

Caveats

Status is INCONCLUSIVE. The allowed-tools field may serve an advisory purpose—affecting permission prompts rather than hard enforcement—or may require specific runtime conditions not tested. Further investigation required to determine whether it modulates permission request scope or has no effect at all.

References

• Test date: 2026-01-07
• Source: /docs/experiments/claude-features/2.1.0/tests/08-yaml-allowed-tools/TEST-RESULTS.md