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

> Discover how Impeccable loads reference files. Learn about the `readSourceFiles` utility and placeholder replacement for efficient frontend design.

- Repository: [Paul Bakaus/impeccable](https://github.com/pbakaus/impeccable)
- Tags: internals
- Published: 2026-03-09

---

**Reference files in the Impeccable frontend-design skill are loaded from a `reference/` subdirectory by `readSourceFiles()` in [`scripts/lib/utils.js`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/typography.md)
- [`color-and-contrast.md`](https://github.com/pbakaus/impeccable/blob/main/color-and-contrast.md)
- [`spatial-design.md`](https://github.com/pbakaus/impeccable/blob/main/spatial-design.md)
- [`motion-design.md`](https://github.com/pbakaus/impeccable/blob/main/motion-design.md)
- [`interaction-design.md`](https://github.com/pbakaus/impeccable/blob/main/interaction-design.md)
- [`responsive-design.md`](https://github.com/pbakaus/impeccable/blob/main/responsive-design.md)
- [`ux-writing.md`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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.

```javascript
// 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`](https://github.com/pbakaus/impeccable/blob/main/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:

```javascript
// 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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/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:

```markdown
→ *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`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js)) completes, these links point to valid files at locations like [`dist/cursor/.cursor/skills/frontend-design/reference/typography.md`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/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`](https://github.com/pbakaus/impeccable/blob/main/SKILL.md) file.