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

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, 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, 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:

// 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:

# 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 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, 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.

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