Agent `skills:` preloading injects only SKILL.md, with no way to reach the skill's bundled resources

Summary

An agent's skills: frontmatter injects the rendered SKILL.md body and nothing else. The agent does not receive references/, assets/ or scripts/, and is not given the skill's base directory, so it cannot follow the relative paths that the preloaded body names.

The result is that preloading silently defeats progressive disclosure — the pattern skill-creator recommends for organising a skill.

This is distinct from the already-fixed "nothing is injected at all" bugs (#25834, #67251). Injection works correctly here; it is just body-only, and there is no affordance for reaching the rest.

Why this is surprising

The Agent Skills specification defines a skill as SKILL.md plus its bundled resources. The subagents documentation says:

The full content of each skill is injected into the subagent's context at startup.

Read against the spec's definition of "skill", "full content" implies the bundled resources too. In practice it means the body only.

So a skill that follows the recommended structure — a thin SKILL.md pointing at detailed references/ — becomes close to useless when preloaded, and nothing reports that. The agent gets a set of pointers it cannot follow.

Reproduction

Claude Code 2.1.281, macOS.

A plugin with one skill and one agent:

probe/
├── .claude-plugin/plugin.json      # { "name": "probe", ... }
├── skills/probe-criteria/
│   ├── SKILL.md                    # contains marker SKILLMD-PELICAN-8823,
│   │                               # and says "see references/detail.md"
│   └── references/detail.md        # contains marker REFFILE-WALRUS-4471
└── agents/probe-agent.md

# agents/probe-agent.md
---
name: probe-agent
description: Probe agent.
skills:
  - probe:probe-criteria
tools: Read
---

Run from a working directory unrelated to the plugin:

claude -p --plugin-dir ./probe --permission-mode auto \
  "Use the Agent tool with subagent_type 'probe:probe-agent' and ask it: \
   (1) is SKILLMD-PELICAN-8823 in your context before any tool call? \
   (2) is REFFILE-WALRUS-4471? \
   (3) Read the path exactly as the skill names it: references/detail.md"

Observed

| | Result |
| --- | --- |
| SKILL.md marker present before any tool call | ✅ yes |
| references/detail.md marker present | ❌ no |
| Read("references/detail.md") | ❌ File does not exist. Note: your current working directory is … |

The error names the run directory. Identical across two runs.

Expected

Either of:

1. Bundled resources are injected alongside the body, matching "full content of each skill"; or
2. The preloaded agent is given the skill's base directory, so the paths in the body are followable.

Either would make preloading mean what the spec means by a skill. (2) is the lighter change and would be enough, since it restores the agent's ability to follow what the body already tells it.

A third option — documenting that preloading is body-only — would at least stop authors being misled, and is worth doing in the meantime. But it is a patch over the behaviour rather than a fix for it. The specification defines a skill as its directory, not as one file in it; injecting part of that directory and calling it the skill leaves the implementation wrong in spirit however accurately it is described. Progressive disclosure is the recommended way to structure a skill, and preloading currently punishes skills for following it.

Notes

Invoking the skill is a partial workaround, not a fix. An agent with Skill in its allowlist can invoke the skill, and the tool result opens with Base directory for this skill: …, which the model can then join with the reference path. That works, but it requires granting Skill — which permits invoking any skill, not just the preloaded one — and it depends on the model making the join rather than on resolution. This is the same gap as anthropics/skills#1153, which notes that header is informational and does not affect path resolution.

Either workaround ends in an out-of-workspace read. The plugin cache sits outside the project, so reading a bundled file is permission-gated: it succeeds under auto, and fails under acceptEdits and manual with Claude requested permissions to read from … but you haven't granted it yet. A background or headless agent under a stricter mode has nobody to answer the prompt, so any guidance that relies on reading bundled files is fragile by default.