# Purpose of the Reference Directory in a Skill: Modular Content Management in Garden Skills

> Discover the purpose of the reference directory in Garden Skills. Learn how it stores reusable assets like templates and examples for dynamic prompt population and content generation.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: internals
- Published: 2026-08-28

---

**The `references/` directory in a Garden Skills project stores reusable Markdown and JSON assets—such as templates, examples, and style guides—that skills import at runtime to populate prompts, generate content, and enforce consistency without hard-coding text blocks.**

In the ConardLi/garden-skills repository, every skill can include a dedicated `references/` folder that separates dynamic content from executable logic. This architectural decision enables developers to update prompt templates and auxiliary data independently of the skill's core code, making the entire system more maintainable and modular. Understanding the purpose of the reference directory in a skill is essential for anyone building extensible AI-powered workflows on this platform.

## What Is the Reference Directory in a Skill?

The `references/` directory serves as a standardized location for **reusable assets** that describe templates, examples, style guides, and auxiliary data. Rather than embedding large text blocks directly into source code, developers place these resources in `skills/<skill>/references/` where they can be organized by category and accessed programmatically.

According to the repository's implementation, the platform runtime automatically scans the `references/` folder and makes these files available to the skill's execution environment. This convention allows skills to treat documentation and prompt engineering as data rather than code.

## How Skills Consume Reference Files at Runtime

Skills read reference files to perform three critical functions: **populating prompts**, **generating structured content**, and **enforcing consistency** across outputs. The separation of concerns allows non-developers to edit Markdown templates without risking changes to the skill's logic.

### Template Loading in Practice

The **GPT-Image-2** skill demonstrates this pattern clearly. As documented in [`website/gpt-image2-website/README.md`](https://github.com/ConardLi/garden-skills/blob/main/website/gpt-image2-website/README.md), each prompt template lives under `references/<category>/<template>.md` and is loaded dynamically when the skill executes. Similarly, the **Web-Video-Presentation** skill, defined in [`skills/web-video-presentation/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/SKILL.md), references several Markdown files inside its own `references/` folder to drive script generation and outline formatting.

### Runtime Implementation Examples

When implementing a skill, you can resolve and read these assets using standard file system operations:

```typescript
// Example: Load a reference template inside a skill script
import { readFileSync } from "fs";
import { resolve } from "path";

// Resolve the path to a reference file (e.g., a prompt template)
const tmplPath = resolve(__dirname, "references", "ui-mockups", "live-commerce-ui.md");

// Read the template content as a string
const tmpl = readFileSync(tmplPath, "utf-8");

// Use the template when constructing a prompt for an LLM
const prompt = `${tmpl}\nUser request: ${userInput}`;

```

For debugging or inventory purposes, you can enumerate all available references:

```python

# Example: Python script that lists all reference files for a skill

import pathlib

skill_root = pathlib.Path(__file__).parent
ref_dir = skill_root / "references"

for ref_file in ref_dir.rglob("*.md"):
    print(f"Reference: {ref_file.relative_to(skill_root)}")

```

## Directory Structure and Organization

The reference directory follows a predictable hierarchy that skills depend upon. Files are typically organized under `skills/<skill>/references/` with subdirectories categorizing assets by type or function.

Key conventions include:
- **Location**: `skills/<skill>/references/` holds the Markdown/JSON assets
- **Documentation**: `skills/<skill>/SKILL.md` documents which reference files are required and how they are consumed
- **Categorization**: Subdirectories like `references/ui-mockups/` or `references/templates/` group related assets

This structure allows the runtime to locate resources predictably while giving developers flexibility in organizing large asset libraries.

## Version Control and Modularity Benefits

By isolating reference material from executable code, the Garden Skills architecture enables **independent versioning** of content and logic. Developers can update a prompt template in [`references/prompts/v1.md`](https://github.com/ConardLi/garden-skills/blob/main/references/prompts/v1.md) and commit that change without touching the skill's TypeScript or Python files. This separation supports:
- **Non-technical editing**: Copywriters can modify Markdown files without code review
- **A/B testing**: Swapping reference directories allows testing different prompt strategies
- **Reusability**: Multiple skills can symlink or copy the same reference assets

## Packaging and Deployment Considerations

During the release process, the build system must include the `references/` directory in the skill package. The repository's release logic, located in `scripts/release/lib/skills.mjs`, explicitly handles packaging the `references/` directory alongside the skill's code. This ensures that when a skill deploys to the Claude plugin runtime or other execution environments, all required templates and data files are present.

## Summary

- The `references/` directory stores **Markdown and JSON assets** that skills load dynamically to avoid hard-coding text blocks.
- Skills like **GPT-Image-2** and **Web-Video-Presentation** import files from `references/<category>/<template>.md` to populate prompts and guide generation workflows.
- The separation enables **independent updates** of content versus code, improving maintainability and allowing non-developers to edit templates.
- The build process in `scripts/release/lib/skills.mjs` packages the `references/` folder during deployment to ensure runtime availability.
- Each skill documents its required references in `skills/<skill>/SKILL.md`, creating a clear contract between assets and logic.

## Frequently Asked Questions

### Can a skill function without a references directory?

Yes, but it loses the ability to externalize prompt templates and style guides. Without `references/`, all content must be hard-coded into the skill's source files, making updates more difficult and increasing the risk of code bloat. The platform does not enforce the presence of this directory, but it is strongly recommended for complex skills.

### What file types belong in the references folder?

The directory primarily contains **Markdown (`.md`)** and **JSON (`.json`)** files. Markdown files typically store prompt templates, style guides, and example outputs, while JSON files may hold structured data schemas or configuration objects. According to the repository conventions seen in [`website/gpt-image2-website/README.md`](https://github.com/ConardLi/garden-skills/blob/main/website/gpt-image2-website/README.md), these assets are organized by category within subdirectories.

### How does the runtime access files in the references directory?

The execution environment automatically scans the `references/` folder and makes files available to the skill at runtime. Skills access these assets using standard file system operations like `readFileSync` in Node.js or `pathlib` in Python, resolving paths relative to the skill's root directory. This approach is demonstrated in the TypeScript and Python examples above.

### Is the references directory mandatory in the Garden Skills framework?

No, the `references/` directory is optional. However, it is considered a best practice for skills that generate dynamic content or rely on complex prompts. The **Web-Video-Presentation** skill and **GPT-Image-2** skill both utilize this pattern extensively, as documented in their respective SKILL.md files, suggesting it is the standard approach for production-grade skills in the ConardLi/garden-skills ecosystem.