Why Agent Skills Never Pass Data: Unpacking the Counterintuitive Design and Collaboration Strategy

When reading the official Agent Skills specification you quickly notice a surprising fact: the spec provides no requires, depends‑on, inputs or outputs fields, so skills cannot declare dependencies on each other.

1. What the spec defines – six self‑describing fields

All identity information for a skill lives in the front‑matter of a SKILL.md file. The optional fields are name, description, license, compatibility, metadata, version, author and allowed‑tools. Each field describes the skill itself; none point to other skills.

Unlike typical module systems (Node’s

package.json

dependencies

, Python’s

pyproject.toml

dependencies

, Maven’s <dependencies>, Cargo’s [dependencies]), there is no "I need X" declaration.

2. Runtime model – three phases inside a single skill

The spec defines a progressive‑disclosure model with three phases:

Discovery : on startup the system loads every skill’s name and description into context; no skill body is read.

Activation : when the agent deems a skill relevant, it loads the full SKILL.md.

Execution : the skill body may contain Read(references/xxx.md) or script calls that are loaded on demand.

Each phase touches only the internal state of a single skill; there is no cross‑skill data flow.

3. Evidence – <available_skills> is a flat list

The reference implementation emits an <available_skills> XML block that lists each skill with name, description and location. The list is flat – no edges, no DAG.

<available_skills>
  <skill>
    <name>shuge-fact-check</name>
    <description>对草稿做事实校验...</description>
    <location>.opencode/skills/shuge-fact-check/SKILL.md</location>
  </skill>
  ...
</available_skills>

4. The spec actively discourages coupling

The best‑practices document warns that tightly coupled skills increase context cost and cause instruction conflicts. The design encourages each skill to be a complete, independent capability; a skill should never require another skill to be useful.

5. Where does the dependency go?

All orchestration responsibility is pushed to the agent (the LLM). The agent scans <available_skills>, matches description semantically, activates needed skills, and passes each skill’s output to the next via the agent’s context.

6. Real‑world case – twelve independent skills

A writing project uses twelve skills (research, drafting, fact‑checking, anti‑AI polishing, image planning, assembly, etc.). None of the skill front‑matters mention another skill. The orchestrator agent shuge-article-writer contains a whitelist ( task.allow) of the sub‑agents and a natural‑language flow that dictates order and data hand‑off.

# shuge-article-writer.md excerpt
task:
  allow:
    shuge-research-v2: "allow"
    shuge-tech-writer: "allow"
    shuge-fact-checker: "allow"
    shuge-anti-ai-reviewer: "allow"
    shuge-image-planner: "allow"
    shuge-assemble: "allow"
    ...

7. Comparison with other dependency models

Traditional systems (Java import, microservice RPC, MCP tool contracts) declare explicit dependencies and data contracts. Agent Skills rely solely on the description natural‑language contract, matched by the LLM.

8. Trade‑offs

Benefits: extreme portability – a skill is just a directory with a SKILL.md. Drawbacks: orchestration logic is not standardized, so the same skill may behave differently under different agents.

9. Practical advice for skill designers

Make each skill runnable on its own; avoid designs that require another skill.

Write clear, precise description – it is the only matching entry point.

Persist outputs to files (e.g., articles/drafts/draft-01.md) so downstream skills can read them.

Keep orchestration logic in a separate orchestrator agent file, not scattered across skills.

Conclusion

The specification’s answer to the opening question is simple: skills do not pass data and do not declare dependencies. This intentional “dependency‑free” design makes skills highly portable but shifts all coordination, ordering, and data flow to the LLM‑driven agent layer, where natural‑language descriptions act as weak contracts.