Skill tool grants
Gating tools with allowed-tools in a skill
A skill's SKILL. front-matter may carry an allowed- key that
gates which tools the skills attached to a configuration (or task) grant for a
run. The resolution is fail-closed on declaration, computed over the
configuration's effective skills (enabled, non-orphaned, at or above the
instance trust floor, deduped):
- Absent (no skill declares
allowed-) — no opinion; all registered tools are offered.tools - Declared list — the union of the declared lists across the effective skills; only those tools are offered (intersected with what is actually registered, so an unknown name is dropped).
- Declared empty (
allowed-) — declares zero tools; if no other effective skill widens the set, the run gets no tools and is a single plain completion.tools: []
A disabled or orphaned skill never grants tools. The allow-list is enforced both when the tools are offered to the model and again when a tool call is executed, so a prompt injection cannot reach a tool the skills did not grant.
The list is resolved once, when the run starts, over the configuration's skills and the skills forced on the run (the playground's skill selection, or a queued run's), and stored with the run; a queued run resolves it when it is enqueued. A run that waits in the queue, for an approval or for input is continued against that list intersected with the list resolved from the skills as they are then: a change while the run waits can take tools away, never add one. Disabling the only declaring skill therefore does not open a waiting run to every tool. A run queued or suspended by an earlier version has no stored list and continues with the list as it is then.
The effective set is not the same as what ends up in the prompt. The
skill-block byte budget (skills., see
Managing skills) is applied after the
allow-list has been computed, while the block is assembled. A skill dropped
for the budget therefore still contributes its allowed-, but its
usage rules never reach the model. That order is deliberate: a budget-aware
union would let the drop of the last declaring skill collapse the allow-list
to "no restriction" — every registered tool — which is a looser gate, not a
tighter one. Keep skills. above the composed size of the skills
you rely on if you want their prose to arrive alongside the tools it
describes; every drop is logged as a warning.
See ADR-038 for the runtime design and security rationale.