How Reference Files Are Loaded and Included in the Impeccable Frontend-Design Skill

Reference files in the Impeccable frontend-design skill are loaded from a reference/ subdirectory by readSourceFiles() in scripts/lib/utils.js, stored in memory as a references array, and then copied to each provider's distribution folder by transformer scripts after processing with replacePlaceholders().

The Impeccable repository manages AI coding skills as directory-based modules, where the frontend-design skill supplements its core SKILL.md with specialized reference documents. Understanding how these reference files are loaded and included reveals the build pipeline's architecture for distributing multi-file skills to various AI providers like Cursor, Claude-code, and Gemini.

Directory Structure of the Frontend-Design Skill

The frontend-design skill follows a standardized directory layout within source/skills/frontend-design/. The main entry point is SKILL.md, which contains the primary skill instructions and links to supplemental materials.

Adjacent to the main file sits an optional reference/ subdirectory containing seven domain-specific markdown files:

• typography.md
• color-and-contrast.md
• spatial-design.md
• motion-design.md
• interaction-design.md
• responsive-design.md
• ux-writing.md

This structure allows the skill to maintain a concise main document while offloading detailed specifications to modular reference files that get loaded and included during the build process.

Loading Reference Files into Memory

The readSourceFiles Utility

The build pipeline scans for skills using readSourceFiles() defined in scripts/lib/utils.js (lines 27-56). When processing the frontend-design skill, the function detects the presence of a reference/ folder and iterates through every .md file inside it.

Each reference file is read from disk and transformed into a structured object with three properties:

• name: The filename without extension (e.g., "typography")
• content: The raw markdown text
• filePath: The absolute path to the source file

These objects populate the skill.references array attached to the skill's in-memory representation.

// scripts/lib/utils.js (excerpt from readSourceFiles)
if (fs.existsSync(referenceDir)) {
  const refFiles = fs.readdirSync(referenceDir).filter(f => f.endsWith('.md'));
  for (const refFile of refFiles) {
    const refPath = path.join(referenceDir, refFile);
    const refContent = fs.readFileSync(refPath, 'utf-8');
    references.push({
      name: path.basename(refFile, '.md'),
      content: refContent,
      filePath: refPath
    });
  }
}

Transforming and Including References for Each Provider

Provider-Specific Distribution

Every provider-specific transformer (Cursor, Claude-code, Gemini, Codex, and Agents) processes the skill.references array during the distribution phase. The transformer creates a reference/ subdirectory in the target output folder, processes each reference file's content through replacePlaceholders() to inject provider-specific tokens like {{model}}, and writes the processed markdown to the distribution directory.

In scripts/lib/transformers/cursor.js (lines 45-55), the implementation checks for the existence of references, ensures the target directory exists, and copies each file:

// scripts/lib/transformers/cursor.js (excerpt)
if (skill.references && skill.references.length > 0) {
  const refDir = path.join(skillDir, 'reference');
  ensureDir(refDir);
  for (const ref of skill.references) {
    const refOutputPath = path.join(refDir, `${ref.name}.md`);
    const refContent = replacePlaceholders(ref.content, 'cursor');
    writeFile(refOutputPath, refContent);
    refCount++;
  }
}

The Agents transformer (scripts/lib/transformers/agents.js, lines 52-61) implements identical logic for the .agents/skills/ output path, ensuring consistent reference file inclusion across all supported providers.

Linking References in the Skill Body

The main frontend-design/SKILL.md establishes connections to its reference files using standard markdown relative links. These paths resolve correctly after transformation because the transformer maintains the reference/ subdirectory structure in the output.

Typical links within the skill document appear as:

→ *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.*
→ *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.*

When the build script (scripts/build.js) completes, these links point to valid files at locations like dist/cursor/.cursor/skills/frontend-design/reference/typography.md, ensuring that AI assistants can access the full context of the frontend-design skill guidelines.

Summary

• Reference files reside in source/skills/frontend-design/reference/ as supplemental markdown documents.
• Loading mechanism: readSourceFiles() in scripts/lib/utils.js scans the reference directory and attaches a references array to the skill object.
• Processing pipeline: Each transformer (Cursor, Agents, etc.) iterates over skill.references, runs replacePlaceholders() for provider-specific tokens, and copies files to dist/<provider>/skills/frontend-design/reference/.
• Link resolution: Relative paths in SKILL.md resolve correctly in the final distribution because the directory structure is preserved during the copy operation.

Frequently Asked Questions

Where are reference files stored in the Impeccable repository?

Reference files are stored in the source/skills/frontend-design/reference/ directory. This folder contains seven markdown files covering specific domains like typography, color theory, and responsive design. The build system treats any .md file in this location as a reference document to be bundled with the skill.

How does the build system detect which files to include as references?

The readSourceFiles() function in scripts/lib/utils.js automatically detects the presence of a reference/ subdirectory when scanning skill folders. It filters for files ending in .md and loads them into memory as an array of objects containing the filename, content, and original file path. This array becomes the skill.references property used by downstream transformers.

Do reference files get modified during the build process?

Yes, reference files undergo placeholder replacement before distribution. The replacePlaceholders() function processes each reference file's content to substitute tokens like {{model}} or {{config_file}} with values appropriate for the target provider (Cursor, Claude-code, etc.). This ensures that provider-specific configurations are injected into the reference documentation while maintaining a single source of truth in the source/ directory.

Can skills other than frontend-design use reference files?

Yes, any skill in the Impeccable repository can include a reference/ subdirectory. The loading and inclusion logic in readSourceFiles() and the transformer scripts is generic and applies to all skills uniformly. If the reference folder exists, its contents are loaded and distributed; if absent, the skill ships with only its main SKILL.md file.

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