Agent skills

An agent skill is a package of instructions, usually a folder with a SKILL.md file, that an AI agent loads when a task calls for it. Once there are many skills, the question is how they work together: whether one skill can call, reference or hand work to another, whether they share terms and state, and what happens when a named skill is missing. The specifications and tools that exist define almost nothing for this (Agent Skills, n.d.), so composition is mostly done in prose and left to the model. Its main disputes are whether skills should depend on one another at all, whether prose references are reliable, and how far the analogy to software modules holds. Evaluating whether a skill works at all is a separate topic (Evaluating agent instructions).

History

How skills emerged and how the specification developed is not yet covered; this section needs a source.

Core concepts

What a skill specification provides

The open Agent Skills specification lists the front matter fields name, description, license, compatibility, metadata and allowed-tools. None of them declares a dependency on, or invokes, another skill (Agent Skills, n.d.). The compatibility field is free text about environment requirements (Agent Skills, n.d.), and allowed-tools, a list of pre-approved tools, is marked experimental, with support varying between implementations (Agent Skills, n.d.). The only cross-file mechanism is a relative file reference inside one skill, kept one level deep (Agent Skills, n.d.).

Harnesses (the programs that run an agent) add their own mechanisms, none of them a skill-to-skill call:

• In Claude Code, the model can invoke any skill through a Skill tool unless the skill sets disable-model-invocation; specific skills can be allowed or denied with Skill(name) permission rules (Anthropic, n.d.c). A skill can run in a forked subagent (context: fork) that does not see the conversation, so it has to stand alone, and an agent field picks the subagent type (Anthropic, n.d.c). Subagents can preload skills, with full content injected at startup (Anthropic, n.d.c). Its allowed-tools only pre-approves tools and is not a dependency mechanism, and it accepts but ignores the compatibility field (Anthropic, n.d.c). Users can stack several skills by naming them in one message; the page describes no skill-to-skill invocation (Anthropic, n.d.c).
• Hermes shows a skill only when named toolsets are present (requires_toolsets) or only when they are missing (fallback_for_toolsets), a dependency on tools rather than on other skills (Nous Research, n.d.). It also groups skills into bundles and allows chaining slash commands in one message (Nous Research, n.d.).
• Codex declares tool dependencies, not skill dependencies, in openai.yaml, and lets a skill opt out of implicit invocation while an explicit $skill mention still works (OpenAI, n.d.).
• Cursor documents no skill-to-skill reference; disable-model-invocation makes a skill explicit-only (Cursor, n.d.).

Claude Code does support declared dependencies one level up, between plugins that can carry skills: they are listed in plugin.json and auto-installed with version ranges (Anthropic, n.d.d).

How skills are made to work together in practice

With no declared link, composition happens by instruction. A tutorial describes skills as unable to call each other directly; a skill body can tell Claude to invoke others by name, which makes it an orchestrating skill (Claude with Skills, n.d.). The same tutorial says each sub-skill remains usable alone while the orchestrator only chains them (Claude with Skills, n.d.). A second practitioner source describes the model, not the skills, as the coordinator that carries one skill’s result to the next (MindStudio, 2026). Both are low-trust sources without measurements.

Terms for working together

The vocabulary is loose. One guide uses layering for several skills active in one context, delegation for one skill invoking another in a forked, isolated context, a pipeline for sequential chaining with output handed on, and fan-out for one orchestrator invoking several skills in parallel (Lip, 2026). Another source uses layering for the opposite structure, a higher-level skill orchestrating lower-level ones, and chaining for one skill’s output feeding another (Dubois, 2026). Claude Code’s documentation uses stacking for the user naming several skills at the start of one message (Anthropic, n.d.c). A vendor page about agents, not skills, separates composability as a design property from chaining as fixed-order execution and orchestration as a central agent decomposing and delegating work at runtime (Ayswarrya G, 2026).

Shared terms, output formats and handoff files

Anthropic’s authoring guide, which says nothing on one skill referencing another (Anthropic, n.d.e), gives advice that carries over to handoffs. It tells authors to pick one term per concept and keep it (Anthropic, n.d.e), and to use output templates, strict when consumers need an exact structure and flexible otherwise (Anthropic, n.d.e). It recommends an intermediate plan file validated before execution, so a later step can check an earlier step’s output (Anthropic, n.d.e), and file references kept one level deep because Claude may read nested ones only partially (Anthropic, n.d.e). One practitioner source recommends each chained skill declare an input schema and a predictable output format (MindStudio, 2026). For the shared-understanding side of handoffs between an agent and a person, see Common ground.

Analogies from software modularity

Writers map skills onto software ideas. A preprint on authoring skills defines a skill that relies on another’s internal behaviour or output format as coupled to it, so a change to one can break the other, says dependencies should be few and explicit, and recommends a single responsibility per skill (Destefanis, 2026). A blog maps composition onto Unix pipes, with the agent as the shell, and skill metadata onto C header files separating interface from implementation, and warns against mega-skills (Botticelli, 2026). Another applies the Unix rule of one job per program to prompts, noting that in 2023 no pipe equivalent existed for language models (Rickard, 2023). The peer-reviewed precedent is Decomposed Prompting (ICLR 2023), which presents prompt modules for sub-tasks that can be optimised and replaced independently (Khot et al., 2023); it concerns prompt modules, not skills. An author arguing for an import system notes that a missing or ambiguous skill fails quietly in lazy loaders, unlike module systems, and that dependency resolution should fail before the agent runs (Pan, 2026a).

Questions, controversies, and new developments

Should skills depend on each other?

A measurement study of over 1.43 million skills found that only 8.92% have direct skill dependencies, fewer than package (15.48%) or external-service (22.25%) dependencies (Jia et al., 2026). It reports no standard dependency declaration and rare dependency-like fields (Jia et al., 2026), with reuse concentrated in a few targets (Jia et al., 2026). Almost a third of skills that have dependencies sit in a reference cycle (Jia et al., 2026), and risk travels along these links: some skills inherit malicious signals only transitively, and mutually referencing skills form clusters where a flaw in one propagates to all (Jia et al., 2026). Dependency information is mostly implicit, and the authors recommend typed dependency manifests (Jia et al., 2026). The opposing practitioner position is that a skill should be usable alone and that an orchestrator, not the skills, should hold the links (Claude with Skills, n.d.).

Do agents follow a skill named inside another skill?

Adjacent evidence is thin. In Vercel’s evals the agent never invoked an available skill in 56% of cases by default, and an explicit instruction raised triggering to 95% or more and the pass rate to 79% (Gao, 2026a); explicit instructions in the agent’s own configuration also helped (Gao, 2026a). In one author’s tests, hook-based prompting gave 20% activation with a simple instruction versus 84% with forced evaluation, and multi-skill prompts were where the simple hook failed (Spence, 2025). A preprint says the decision to apply a skill, by matching its description, is probabilistic and nothing confirms the right skill fired (Destefanis, 2026). These figures concern a model choosing a skill, not one skill naming another, and the model and case count behind the Vercel figures are not stated.

User bug reports describe related failures in Claude Code: a parent skill that stops after a nested skill finishes, never running its later steps, without needing a forked context (jaried (GitHub user), 2026); explicit “mandatory continuation” text in the parent that did not prevent the halt (version 2.1.23, Opus 4.5) (virhdr (GitHub user), 2026); and an agent that skipped a skill its own instructions required, running the workflow from memory and missing a phase (coreyDavisFF (GitHub user), 2026). Whether later versions fixed the halting is unknown.

What goes wrong at the seams

SkillSeam reports that skills fail at the relationships between skills in a collection rather than alone (Kang, 2026). In its audits, overlapping lanes raised ownership conflicts from 0 of 16 to 14 of 16 cases, and bland triggers raised routing conflicts from 3 of 32 to 30 of 32 and inflated loaded-skill tokens 3.7 times (Kang, 2026). A measurement of compositional risk found that individually safe skills can combine into unsafe pairs: 22.25% of 211,575 pairs were flagged as structural candidates, of which about 18.2% of flagged hits were real (Wang et al., 2026c). Another preprint reports that actual skill-use precision falls from 29.6% to 3.3% as the pool grows from 5 to 100, and that skills fail under brittle assumptions, incompatible contexts or insufficient adaptation (Jiang et al., 2026). A practitioner source adds that models do not infer ownership boundaries between skills, that undeclared side effects break chained workflows (AgentConn Team, 2026), and that a double-run of one step by two skills is invisible, since both report success (AgentConn Team, 2026). This last point is unmeasured, and the preprint numbers are the authors’ own.

Does structure beat prose?

Composition papers treat choosing and ordering skills as the bottleneck. AgentSkillOS reports that DAG-based orchestration (a plan of steps with explicit ordering constraints) beats flat skill invocation with the same skills (Li et al., 2026b). A routing paper plans skill order with a dependency-aware DAG planner (Gao, 2026b). SkillComposer names composition selection a central bottleneck, raises pass rate over a no-skill baseline, and matches the gold-skill retrieval upper bound at lower prompt-token cost (Zhao et al., 2026a). A compiler approach, SkillSmith, notes that agents typically receive skills as guidance injected once matched, and proposes compiling them into minimal executable interfaces; it says nothing about handoff between skills (Xu et al., 2026). None of these studies tests hand-written prose references between skills, so they do not settle the question above.

When the other skill is missing

Practice differs by harness. Claude Code refuses to load a plugin whose declared dependency cannot be installed or is disabled, rather than degrading (Anthropic, n.d.d). In Hermes, a bundle that lists a missing skill still loads the others; the missing one is skipped, not fatal (Nous Research, n.d.). Outside declared dependencies, a missing or ambiguous skill fails quietly in lazy loaders (Pan, 2026a). Which behaviour is better is unevaluated.

Is the module analogy sound?

Shell pipes pass data between tools without the model, whereas a skill chain routes through it (Hurier, 2026), which is why one source calls the model the coordinator (MindStudio, 2026). The same author names security as the main blocker for the Unix composition model with agents in production (Hurier, 2026). Terms such as coupling and single responsibility are applied by opinion and by one conceptual preprint rather than tested (Destefanis, 2026).

Broader connections

Skills sit between prompt engineering and software modules. Prompt modules that can be optimised and replaced independently predate skills (Khot et al., 2023), and the multi-agent systems in Multi-agent research systems face the same question of what a coordinator passes to a worker. Whether a composed set of skills improves work is the subject of Evaluating agent instructions and of the tooling in Evaluation tooling for AI agents. Comparison with multi-agent handoff designs that pass goal, context and state is missing.

Further reading

• Jia and colleagues Jia et al. (2026): the only ecosystem-scale measurement of how skills depend on each other.
• Destefanis Destefanis (2026): a software-engineering framing of coupling, explicit dependencies and single responsibility.
• Anthropic’s Anthropic (n.d.e): shared terms, output templates and validated plan files.
• Kang Kang (2026): auditing a collection for ownership and routing conflicts.
• Pan Pan (2026a): the argument that agent stacks need an import system that fails early.