Skill References

[haydenrear]

I think it would be cool to add references for other skills to the frontmatter. And potentially then they can be included in a nested directory, or downloaded transitively?

[sungyubkim]

+1 — I've been running a cross-skill shared references pattern in production and wanted to share concrete evidence for why this would be valuable in the spec.

The Problem: Duplication in Practice

This repo already has a real example of the cost of missing cross-skill references. The docx, pptx, and xlsx skills each bundle identical copies of 10 ISO-IEC29500 XSD schema files (verified byte-identical via git SHA):

File	docx	pptx	xlsx
shared-math.xsd	✓	✓ (identical)	✓ (identical)
shared-commonSimpleTypes.xsd	✓	✓ (identical)	✓ (identical)
shared-bibliography.xsd	✓	✓ (identical)	✓ (identical)
... (7 more files)	✓	✓ (identical)	✓ (identical)

That's 30 files where 10 would suffice. When these schemas need updating, all three skills must be patched in lockstep — a maintenance burden that grows with each new Office-format skill.

What I've Been Running

I maintain a ~/.claude/docs/ directory with shared reference documents that multiple skills load on demand via explicit Read instructions in their SKILL.md:

~/.claude/
├── docs/                              # Cross-skill shared references
│   ├── thinking-router.md             # → used by 6 skills
│   ├── knowledge-grounding.md         # → used by 4 skills
│   ├── skill-guardrails.md            # → used by 1 skill + 3 agents
│   └── thinking-frameworks/           # → used by 7 skills
│       ├── first-principles.md
│       ├── failure-discovery.md
│       └── ...
├── skills/
│   ├── discovery/SKILL.md             # contains: Read ~/.claude/docs/thinking-router.md
│   ├── designing/SKILL.md             # contains: Read ~/.claude/docs/thinking-router.md
│   └── research-execution/SKILL.md    # contains: Read ~/.claude/docs/thinking-router.md

Key properties of this pattern:

• DRY: One source of truth, N skills reference it
• On-demand loading: Files enter context only when a skill explicitly reads them (unlike rules/, which auto-load at session start)
• Progressive disclosure: Aligns with the spec's existing metadata → instructions → resources model

I've been running this across 8 skills and 3 agents for several months. The main trade-off is that loading depends on the model's instruction-following rather than harness-level guarantees, but in practice this has been reliable.

Minimal Proposal

A lightweight addition to the spec that could address this without major infrastructure:

Option A — Collection-level _shared/ directory

my-skills-collection/
├── _shared/                     # Shared across sibling skills
│   └── office-schemas/
│       └── shared-math.xsd
├── docx/
│   ├── SKILL.md                 # Read ../_shared/office-schemas/shared-math.xsd
│   └── scripts/
├── pptx/
│   └── SKILL.md
└── xlsx/
    └── SKILL.md

Spec change: document _shared/ as an optional convention for skill collections. Skills reference shared files via relative paths. No new frontmatter fields needed — just a naming convention.

Option B — references frontmatter field (as you suggested)

---
name: pptx
description: ...
references:
  - docx/scripts/office/schemas   # Sibling skill path
  - _shared/office-schemas        # Or a shared directory
---

Spec change: add an optional references field that declares cross-skill file dependencies. Clients can use this for validation, pre-fetching, or transitive installation.

I'd lean toward Option A for simplicity — it requires no client changes, just a documented convention. Option B is more powerful but needs client support.

Either way, the core need is clear: when skills share a domain (Office formats, thinking frameworks, API patterns), a first-class mechanism for shared references would reduce duplication and improve maintainability.