Shared Content References
Resolve "where does the shared copy live?" for prose duplicated across two or more SKILL.md or
agent files inside one plugin.
1. Scope Gate
Applies when the same prose is needed by 2+ SKILL.md or agent files in one plugin.
Does not apply — route elsewhere instead:
- One skill's own content is too long → activate the
/plugin-creator:refactor-skill skill
(SK006/SK007 token thresholds).
- Deciding whether content belongs in a skill's
SKILL.md body or its own references/
directory (a single-skill boundary, not a cross-skill one) → activate the
/plugin-creator:optimize skill or the /plugin-creator:agentskills skill.
- Sharing executable code (scripts, shell utilities) rather than prose → activate the
/plugin-creator:component-patterns skill, §Shared Resources (lib/ at the plugin root,
accessed via ${CLAUDE_PLUGIN_ROOT}/lib/).
2. Placement Decision
flowchart TD
Start(["Same prose needed in 2+ places"]) --> Q1{"Consumed by components<br>in 2+ skill directories,<br>or by an agent<br>(agents have no references/)?"}
Q1 -->|"Yes"| Root["Place in plugin-root docs/<br>Reference via Technique 1"]
Q1 -->|"No — one skill plus<br>the agents it dispatches"| SkillRef["Place in that skill's references/<br>Reference via the ${CLAUDE_SKILL_DIR} form<br>from Technique 2"]
Root --> Q2{"More than ~3 shared docs<br>accumulate in this location?"}
SkillRef --> Q2
Q2 -->|"Yes"| Index["Add an index skill (Technique 2)<br>so consumers load one skill<br>instead of repeating paths"]
Q2 -->|"No"| Direct["Reference the doc directly<br>from each consumer<br>No index skill needed yet"]
3. Technique 1 — Plugin-Root Shared Doc
[<doc name>](../../docs/<doc>.md) — contains <what>; read before <when>.
From skills/<name>/SKILL.md the relative link stays inside the plugin and needs no harness
support, so it is the primary form for a doc consumed across 2+ skill directories. Claude Code
also substitutes ${CLAUDE_PLUGIN_ROOT} in plain SKILL.md prose and markdown link targets;
write that form only in a plugin that targets Claude Code alone. Load
verification.md before relying on either form in a new,
unverified runtime.
4. Technique 2 — The Index-Skill Pattern
An index skill's own SKILL.md lists each shared doc with the annotation contract from
annotation-format.md:
[<doc name>](${CLAUDE_SKILL_DIR}/references/<doc>.md) — contains <what>; read before <when>.
Every consumer skill or agent writes one sentence and never repeats a path:
For <topic>, activate the /plugin-name:index-skill-name skill.
Moving or renaming a shared doc becomes a one-file edit inside the index skill.
Shared content lives inside the plugin that ships it. A doc in the surrounding repo is not
shared content — an installed consumer never has that tree, so the reference resolves for the
author alone.
5. Reference Files
Confirm each shared reference is present in every environment, bundled and reached by a
relative path inside the plugin, or inlined; otherwise inline, bundle, guard, or delete it. A
harness variable counts only where that harness substitutes it.
Load annotation-format.md before writing any reference
link created by Technique 1 or 2 — defines what every reference must state and why.
Load what-not-to-use.md before reaching for a symlink, a
../ path, or copy-paste to share content across components — each fails for a documented
reason.
Load verification.md after adding or changing any shared
reference — canary, skilllint, and target-existence checks.
6. Related Skills
/plugin-creator:optimize — the SKILL.md-vs-references/ boundary within one skill; load
first if the question is about one skill's own structure, not sharing across skills./plugin-creator:agentskills — the Agent Skills Open Standard for cross-agent-product
portability. ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_SKILL_DIR} are Claude-Code-specific and do
not carry over to a portable skill./plugin-creator:refactor-skill — one skill exceeding SK006/SK007 token thresholds; a
different problem from N skills sharing content./plugin-creator:component-patterns — §Shared Resources covers shared executable code
(lib/ at the plugin root), the code counterpart to this skill's shared prose.- The
plugin-assessor agent's cross-component duplicate-content check routes here for the remedy.
- The
start-refactor-task skill's CREATE shared references if specified step routes here for
what a shared reference is and how to create one.