How to Work with the References Directory in Claude Skills

The references/ directory stores supplementary documentation, schemas, and API specifications that Claude loads on-demand, keeping your skill's main SKILL.md concise while enabling access to detailed contextual data.

Claude Skills are modular instruction packages that extend an agent's capabilities within the ComposioHQ/awesome-claude-skills ecosystem. While every skill requires a SKILL.md file at its root, the optional references/ directory allows developers to maintain information-rich skills without overwhelming the model's context window. This architectural pattern implements progressive disclosure, where heavy documentation is loaded only when specifically needed.

What Is the References Directory?

The references/ folder is an optional directory that sits alongside SKILL.md in your skill's root. According to the skill-creator guide in skill-creator/SKILL.md (lines 57-65), this directory is designed for documentation, schemas, API specs, or any detailed material that Claude should load on demand rather than keep in the main instruction body.

When a skill is activated, Claude initially sees only the metadata (name and description). The full SKILL.md body loads only if the skill appears relevant to the user's request. If the skill needs to consult large reference materials to complete a task, Claude pulls the appropriate files from references/ at that specific moment. This design prevents token-window bloat and enables repositories to host hundreds of skills without performance degradation.

When to Use References vs. SKILL.md

Separating content between your main skill file and the references directory requires understanding Claude's loading mechanism.

Content That Belongs in references/

Store files in references/ when the information is needed only for specific steps, not for every invocation of the skill. As documented in skill-creator/SKILL.md (lines 61-64), ideal candidates include:

• API reference guides with detailed endpoints and parameters
• Database schemas and table definitions
• Policy documents and compliance guidelines
• Large technical specifications exceeding a few thousand words

Content That Stays in SKILL.md

Core concepts, primary instructions, and essential context that Claude needs immediately upon skill activation should remain in the main SKILL.md. Avoid duplication: summarize core concepts in the skill body while keeping exhaustive details in the references.

Directory Structure and Creation

The references/ directory is automatically scaffolded when you create a new skill using the initialization script. In skill-creator/scripts/init_skill.py (lines 46-51), the init_skill.py script generates an empty references/ folder and places a starter file named api_reference.md to demonstrate the convention.

Your skill structure should look like this:

my-skill/
├── SKILL.md
├── references/
│   ├── api_reference.md
│   └── schema.md
└── scripts/
    └── (optional helper scripts)

Best Practices for Reference Files

To maximize the effectiveness of the progressive disclosure pattern, follow these guidelines derived from the source implementation:

• Keep files lean: Avoid files longer than 10,000 words when possible. Large documents should be split logically.
• Use clear filenames: Name files descriptively (e.g., database_schema.md, oauth2_spec.md) so Claude can discover them via natural-language cues.
• Add grep-style hints: Include explicit pointers in SKILL.md telling Claude when to load specific reference files, such as "Use references/schema.md for table definitions."

How Claude Loads Reference Files

Claude decides at runtime whether a reference file is relevant to the current task. When the skill's logic requires detailed data, the model streams the appropriate reference file into the context window. This just-in-time loading mechanism ensures that skills remain lightweight during initial evaluation while still accessing exhaustive data when executing complex, domain-specific tasks.

Example Implementation

Here's a practical example showing how to create a reference file for a finance database schema and reference it from your skill:

# Example: Adding a new reference file for a finance schema

import pathlib

skill_root = pathlib.Path("my-finance-skill")
ref_dir = skill_root / "references"
ref_dir.mkdir(parents=True, exist_ok=True)

# Create a markdown reference documenting database tables

(ref_dir / "schema.md").write_text(
    """# Finance Database Schema

## accounts

- id: integer (PK)
- name: string
- balance: decimal

## transactions

- id: integer (PK)
- account_id: integer (FK → accounts.id)
- amount: decimal
- date: datetime
    """
)

Then, reference this documentation in your SKILL.md:

---
name: finance-report
description: Generates financial reports based on the company database.
---

## When to Use This Skill

- Summarize quarterly earnings
- Produce balance-sheet overviews

## Instructions

1. Load the `references/schema.md` to understand table structures.
2. Query the `accounts` and `transactions` tables.
3. Assemble the report using the retrieved data.

> Use `references/schema.md` for table definitions.

Summary

• The references/ directory stores heavy documentation that would otherwise bloat the main SKILL.md context.
• Claude implements progressive disclosure: it loads reference files on-demand during task execution, not at skill activation.
• Store API specs, schemas, and detailed guides in references/; keep core instructions and summaries in SKILL.md.
• The init_skill.py script automatically creates the references/ folder when scaffolding new skills.
• Keep individual reference files under 10,000 words and use descriptive filenames with explicit loading hints in your skill instructions.

Frequently Asked Questions

What file types should go in the references directory?

Markdown files (.md) are the standard format for reference documentation. Store API specifications, database schemas, policy documents, or any detailed technical guides that support the skill's functionality but aren't required for every invocation. Avoid binary files or executable code; use the scripts/ or assets/ directories for those resources.

How does Claude decide when to load a reference file?

Claude evaluates the skill's current task context against the filenames and content descriptions in references/. When the skill instructions in SKILL.md explicitly mention a reference file (e.g., "load references/schema.md") or when the task clearly requires detailed data stored in that directory, Claude streams the file into the active context window at that specific moment.

Is there a size limit for reference files?

While there's no hard technical limit enforced by the file system, the source documentation recommends keeping reference files under 10,000 words when possible. Large files consume significant context window tokens when loaded, potentially limiting Claude's ability to process other information. If a document exceeds this size, consider splitting it into logically separated files (e.g., api_endpoints.md and api_authentication.md).

How do I create the references directory when scaffolding a new skill?

You don't need to create it manually. When you run skill-creator/scripts/init_skill.py to scaffold a new skill, the script automatically generates the references/ directory (lines 46-51 of the source) and populates it with a starter api_reference.md file. You can then add your own reference files alongside this template or replace it with your specific documentation.

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