YAML allowed-tools — runtime test
Hands-on runtime battle-test of YAML allowed-tools. Result: INCONCLUSIVE.
YAML allowed-tools lists were tested for tool-restriction enforcement in skill frontmatter but did not block tools as expected; actual enforcement was only confirmed via agent tools: definitions.
Test Setup
A skill frontmatter experiment on 2026-01-07 attempted to restrict tool access using two syntax variants: a YAML list format (allowed-tools: [Read, Grep, Glob]) and comma-separated string format (allowed-tools: Read,Grep,Glob). Both were tested in a Skill frontmatter context to verify that Bash would be blocked when not listed. A third test confirmed that tool restrictions did work when defined in an agent's tools: field.
What the Test Found
The YAML and comma-separated formats did not enforce the expected restrictions: Bash remained callable despite being absent from the allowed-tools lists. In contrast, when identical tool lists were defined in a custom agent's tools: field, Bash was properly blocked. This revealed a critical semantic gap: allowed-tools in skill frontmatter either serves a different purpose (such as affecting permission-prompt behavior rather than runtime enforcement) or requires additional configuration to work.
Implications
The finding clarifies the actual runtime boundary: tool restrictions in Claude Code are enforced at the agent level via the tools: field, not at the skill level via allowed-tools metadata. Practitioners seeking to restrict tool access should use custom agents, not skill declarations. The function of allowed-tools in skill frontmatter remains unresolved and may warrant deeper investigation into permission-prompt logic or conditional agent configuration.
Status
INCONCLUSIVE. YAML list parsing did not provably fail; the absence of an expected block could reflect unimplemented enforcement, configuration gaps, or a redefined purpose for the field that was not tested. Tool restriction enforcement via agents was confirmed.
Test Results: YAML-Style allowed-tools Lists
Feature: Added support for YAML-style lists in frontmatter allowed-tools field
Tested: 2026-01-07
Test Attempts
Test 1: YAML List Format in Skill
allowed-tools:
- Read
- Grep
- Glob
Result: INCONCLUSIVE - Bash still worked when it should have been blocked
Test 2: Comma Format in Skill
allowed-tools: Read,Grep,Glob
Result: INCONCLUSIVE - Same issue, Bash still worked
Test 3: Tool Restriction via Agent
agent: cheap-researcher # agent defines tools: Read, Grep, Glob
Result: PASS - Bash was blocked (from earlier custom agent tests)
Key Finding
Tool restrictions work via agent definitions, not skill allowed-tools:
| Location | Field | Enforced? |
|---|---|---|
| Agent definition | tools: |
YES |
| Skill frontmatter | allowed-tools: |
NO (or needs more testing) |
Hypothesis
The allowed-tools field in skill frontmatter may serve a different purpose:
- Maybe it affects permission prompts (what gets asked vs auto-allowed)
- Maybe it's advisory for the agent, not enforced
- Maybe it only works with specific configurations
Recommendation
For tool restriction enforcement, use custom agents with tools: field, not allowed-tools: in skill frontmatter.
Status: INCONCLUSIVE
YAML list parsing unclear. Tool restrictions only verified working via agent definitions.
test_b56cc0179a808a566a3a709ded255199b87705613b1e2fd064d57fa75a6b679d2856ceafad6b1daa8f982493871b6dd41f78757606821591800e762ba965ede0d5e4e62e9af7f1c5d46199b0b156567cfaa8f5b29847745723d197dd962995911405ae8114b1091038fac2cdee1ee03Signed with an ed25519 key held off the repo. Anyone can verify against the published public key; nobody without the secret key can forge it. Click verify: it recomputes the signature in your browser. The signature proves integrity and authorship of this exact content — not a third-party timestamp or that the underlying claim is objectively true. signedAt is when the @f3/attest pipeline ran, not when the work happened; the evidence refs carry the source dates.
- verifies YAML allowed-tools Primitive