Proposal: machine-evaluable 'dependencies' field in frontmatter for tools

Proposal: machine-evaluable dependencies field in frontmatter for tools

Summary

Add an optional dependencies field to SKILL.md frontmatter that lets a skill declare, in machine-evaluable form, the tools (and optionally resources/prompts, if relevant) it needs in order to function — with all / any semantics. This gives hosts a basis for deciding whether a skill should be surfaced or activated at all, rather than discovering a missing prerequisite mid-task.

Motivation

description tells an agent when a skill applies. Nothing tells the host whether the skill can actually run in the current environment. The concrete failure mode:

1. A skill's workflow orchestrates a set of tools.
2. Those tools aren't all available in this environment (feature-gated, entitlement-gated, permission-gated, or just not installed).
3. The host still surfaces the skill; the agent loads the full SKILL.md into context, starts the workflow, and hits a "tool not available" wall partway through - or worse, as we've observed in our production environment, hallucinates that something is possible because the skill has now told the LLM what is possible.

This is especially acute for MCP-served skills, where tool availability is per-session: the same server exposes different tools/list results to different users based on flags, entitlements, and permission bits. A production example: versioned tool pairs are common (get_order / get_order_v2), and a skill needs the capability, satisfiable by either version.

The complementary MCP-side discussion is in modelcontextprotocol/modelcontextprotocol#2640 — comment here. That thread frames the "skill required to make the server work at all" vs. "skill that orchestrates tools you could use without it" distinction. This proposal is the source-agnostic declaration half; the MCP spec would own the MCP-specific evaluation half.

Why existing fields don't cover this

• compatibility is free-text human prose (≤500 chars, "intended product, system packages, network access"). It's not machine-evaluable and can't be resolved against a host's actual tool list. It answers "will this work on my platform," not "are these specific tools available to me right now."
• allowed-tools (Experimental; see #144) is a permission grant — "the skill is pre-approved to use these." That's the opposite direction: it widens access, it doesn't check availability. A skill can be granted a tool that isn't present, and allowed-tools says nothing about whether it is.

dependencies fills the gap: a requirement check, not a grant and not prose.

Proposed shape

---
name: refund-workflow
description: Dispute a chargeback on an order. Use when a guest reports a disputed charge.
dependencies:
  tools:
    all: [get_order, get_check_details]
    any: [dispute_chargeback, dispute_chargeback_v2]
---

• all — every entry must resolve to an available tool.
• any — at least one must.
• A bare list is shorthand for all.
• Type-keyed (tools:) so the same field can later express resources: / prompts: without a schema change, without implying they carry equal weight (tools are where real per-environment variance lives).

Deliberately out of scope: a recursive boolean tree (any nested in all nested in any). Flat all + any groups per type express every skill we could find a real need for. Add nesting if and when a concrete skill can't be expressed without it.

Semantics (source-agnostic declaration, host-specific evaluation)

The field declares intent uniformly. How "available" is resolved is the host's job and differs by skill source:

• Filesystem / harness-provided skills: resolve names against the tools the agent harness exposes.
• MCP-served skills: resolve against the server's tools/list for the current session (this is what makes it powerful — same server, different users, different result).

Recommended host behavior when dependencies are unsatisfied (non-normative here; the binding rules for MCP would live in #2640):

• A host MAY omit / not surface the skill.
• If it does surface it, it SHOULD mark it unavailable and expose a human-readable reason, to support "here's how to get access" affordances.

Evaluation is intentionally soft: an unknown or unresolvable name should not hard-fail skill parsing — it degrades to "this skill's prerequisites aren't met," never a validation error. Tool identity is scoped to the resolving host's namespace; cross-server/global tool identity is explicitly deferred.

Open questions

1. Field placement — is dependencies the right name, or should this nest under a broader requirements?
2. Relationship to allowed-tools — should a tool in dependencies imply nothing about permission (kept fully orthogonal — recommended), or auto-suggest an allowed-tools entry? Recommend orthogonal.
3. compatibility overlap — keep them distinct (prose vs. machine-evaluable) or eventually fold structured deps under compatibility? Recommend distinct.
4. Validation — skills-ref should validate structure (keys, list-of-strings, all/any) but not attempt availability resolution, which is inherently host-dependent.

Prior art / related

• modelcontextprotocol/modelcontextprotocol#2640 (Skills over MCP) — the transport that makes per-session tool resolution meaningful.
• #144 — allowed-tools type clarification (adjacent field, different purpose).
• #137 — nested skills (adjacent structural question).