How Reference Files Are Linked to Skills in the Routing Table: A Complete Guide

Reference files are linked to skills through a three-column routing table in each SKILL.md file that maps topics to relative file paths and defines "Load When" conditions to trigger dynamic loading of reference content.

In the Jeffallan/claude-skills repository, the routing table serves as the central mechanism for connecting skills to their detailed reference documentation. This architecture enables efficient progressive disclosure by keeping primary skill definitions lightweight while ensuring specialized knowledge loads dynamically when specific topics arise in user prompts.

Understanding the Skill Architecture and Routing Table Structure

Skill File Organization

Each skill resides in its own directory under skills/, containing a main SKILL.md file. To prevent bloating this primary file, detailed guidance lives in separate markdown files within a references/ subdirectory. For example, the React Expert skill stores its server components documentation at skills/react-expert/references/server-components.md.

The Three-Column Routing Table Format

The routing table appears in the "Reference Guide" section of every SKILL.md and follows this strict format:

| Topic | Reference | Load When |

• Topic: A short, human-readable label for the subject matter.
• Reference: A relative path to the markdown file containing full documentation, always relative to the skill's root directory (e.g., [`references/server-components.md`](https://github.com/Jeffallan/claude-skills/blob/main/references/server-components.md)).
• Load When: A textual condition that the runtime evaluates against the current prompt. When the condition matches, the engine automatically loads the referenced markdown and makes its content available to the skill's logic.

How the Routing Table Links Reference Files to Skills at Runtime

During execution, the Claude-Code runner parses the routing table and implements lazy loading through the following process:

1. Condition Monitoring: The runtime watches the user's request against the "Load When" column.
2. Path Resolution: When a condition matches, the engine resolves the relative path to an absolute path inside the repository (e.g., skills/react-expert/references/server-components.md).
3. Content Injection: The reference file content is read and inserted into the prompt sent to the model.

This implements the progressive disclosure pattern documented in CONTRIBUTING.md (lines 96-108), achieving approximately a 40% reduction in token load while maintaining access to rich, topic-specific material.

Concrete Example: React Expert Skill Routing

The React Expert skill in skills/react-expert/SKILL.md (lines 46-52) demonstrates this linkage:

| Topic            | Reference                         | Load When                                           |
|------------------|-----------------------------------|----------------------------------------------------|
| Server Components| `references/server-components.md`| RSC patterns, Next.js App Router                    |
| React 19         | `references/react-19-features.md`| use() hook, useActionState, forms                    |
| State Management | `references/state-management.md` | Context, Zustand, Redux, TanStack                     |
| Hooks            | `references/hooks-patterns.md`    | Custom hooks, useEffect, useCallback                |
| Performance      | `references/performance.md`       | memo, lazy, virtualization                           |
| Testing          | `references/testing-react.md`     | Testing Library, mocking                            |

When a user asks "How do I set up Server Components in a Next.js App Router?", the keywords RSC patterns and Next.js App Router satisfy the Load When condition. The runtime then loads skills/react-expert/references/server-components.md and injects its content into the model prompt.

Implementation: Loading Reference Files at Runtime

The loading mechanism operates through Python-based parsing and condition matching. Below is the simplified pseudocode illustrating how the routing table drives file linkage:

import yaml, re, pathlib, json

def load_skill(skill_dir: pathlib.Path, prompt: str):
    # 1️⃣ Read the SKILL.md front‑matter & body

    skill_md = (skill_dir / "SKILL.md").read_text()
    # Extract the markdown table after "Reference Guide"

    table = extract_routing_table(skill_md)

    for row in table:
        topic, ref_path, condition = row
        # 2️⃣ Check if the condition matches the prompt

        if matches_condition(condition, prompt):
            # 3️⃣ Resolve the relative path and read the file

            ref_file = skill_dir / ref_path.strip('`')
            ref_content = ref_file.read_text()
            # 4️⃣ Append the reference content to the model input

            prompt += f"\n\n## {topic}\n{ref_content}\n"

    return prompt

The condition matching uses keyword extraction against the user input:

def matches_condition(condition: str, user_input: str) -> bool:
    # lower‑case both strings for case‑insensitive matching

    condition = condition.lower()
    user_input = user_input.lower()
    # split on commas / “and” to get individual keywords

    keywords = re.split(r',|\band\b', condition)
    return any(kw.strip() in user_input for kw in keywords if kw.strip())

When processing "Give me an example of React 19 use() hook", the keywords use() and react 19 satisfy the React 19 row condition, triggering the load of references/react-19-features.md.

Validation and Key Files

The repository maintains strict validation to ensure routing table integrity. The scripts/validate-skills.py utility verifies that every path in the Reference column points to an existing file and that "Load When" clauses reference valid triggers from the skill's metadata.triggers list.

File	Role
CONTRIBUTING.md	Documents the progressive‑disclosure pattern and canonical routing‑table syntax (lines 96‑108)
skills/react-expert/SKILL.md	Concrete routing table implementation example (lines 46‑52)
skills/react-expert/references/*.md	Target reference files (e.g., server-components.md) loaded via routing table
scripts/validate-skills.py	Ensures routing table entries point to valid reference files and triggers
scripts/update-docs.py	Regenerates documentation and verifies routing table synchronization

Summary

• Reference files are stored in references/ subdirectories within each skill folder to keep SKILL.md files lightweight and focused.
• The routing table in each SKILL.md uses a three‑column format (Topic, Reference, Load When) to map topics to relative file paths and activation conditions.
• At runtime, the Claude‑Code runner evaluates Load When conditions against user prompts and lazily loads reference content only when matches occur, implementing progressive disclosure.
• This architecture reduces initial token load by approximately 40% while ensuring detailed, topic‑specific guidance remains available on demand.
• Validation scripts ensure all routing table entries point to existing files and reference valid trigger keywords.

Frequently Asked Questions

What is the exact format of the routing table in a SKILL.md file?

The routing table appears in the "Reference Guide" section and uses standard markdown table syntax with three columns: Topic, Reference, and Load When. The Reference column contains relative paths wrapped in backticks (e.g., [`references/server-components.md`](https://github.com/Jeffallan/claude-skills/blob/main/references/server-components.md)), and the Load When column contains comma‑separated keywords or phrases that trigger loading when detected in user input.

How does the runtime know when to load a specific reference file?

The runtime evaluates the Load When column against the current user prompt using keyword matching. As implemented in the validation logic, the system checks if keywords from the condition appear in the user input (case‑insensitive). When a match occurs, the engine resolves the relative path from the Reference column, reads the file from the references/ directory, and injects its content into the model prompt.

Can reference files be shared between different skills?

No, reference files are scoped to individual skills. Each skill maintains its own references/ subdirectory containing markdown files specific to that skill's domain. While the routing table mechanism is consistent across the repository, the paths in the Reference column are relative to the specific skill's root directory (e.g., skills/react-expert/references/server-components.md), ensuring isolation and preventing cross‑skill dependencies.

What happens if a reference file listed in the routing table is missing?

The validation script scripts/validate-skills.py prevents this scenario by checking that every path in the Reference column points to an existing file before deployment. If a file is missing, the validation fails with an error indicating the broken path. At runtime, if a reference were somehow missing despite validation, the loader would raise a FileNotFoundError when attempting to resolve the path, preventing the skill from providing incomplete information.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}