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

> Understand how reference files link to skills via the routing table. Learn about topic mapping, file paths, and dynamic loading conditions in Claude Skills. This guide explains the process.

- Repository: [Jeffallan/claude-skills](https://github.com/jeffallan/claude-skills)
- Tags: tutorial
- Published: 2026-02-19

---

**Reference files are linked to skills through a three-column routing table in each [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/skills/react-expert/SKILL.md) (lines 46-52) demonstrates this linkage:

```markdown
| 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`](https://github.com/Jeffallan/claude-skills/blob/main/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:

```python
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:

```python
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`](https://github.com/Jeffallan/claude-skills/blob/main/references/react-19-features.md).

## Validation and Key Files

The repository maintains strict validation to ensure routing table integrity. The [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/CONTRIBUTING.md) | Documents the progressive‑disclosure pattern and canonical routing‑table syntax (lines 96‑108) |
| [`skills/react-expert/SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/server-components.md)) loaded via routing table |
| [`scripts/validate-skills.py`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) | Ensures routing table entries point to valid reference files and triggers |
| [`scripts/update-docs.py`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) files lightweight and focused.
- The **routing table** in each [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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.