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.