How Impeccable Assembles the Universal Bundle from Provider Outputs

Impeccable's build system aggregates provider-specific configuration folders into a single universal directory using the assembleUniversal function in scripts/build.js, which maps each AI assistant's output into a ready-to-distribute bundle with optional prefixed skill variants.

The pbakaus/impeccable repository transforms canonical skill definitions into provider-native formats for Cursor, Claude Code, Gemini, Codex, Agents, and Kiro. To distribute these efficiently, the build pipeline must assemble the universal bundle from provider outputs, co-locating all supported configurations into a single, self-documented package. This process ensures users receive a consistent installation experience across every supported AI toolchain.

The Assembly Pipeline

The core logic resides in scripts/build.js, where the assembleUniversal function orchestrates the consolidation of disparate provider builds into one distributable structure.

Preparation and Cleanup

The function accepts a distDir path and an optional suffix parameter (used to distinguish regular and prefixed variants). It first constructs the target directory path and removes any existing universal folder to ensure clean output.

function assembleUniversal(distDir, suffix = '') {
  const universalDir = path.join(distDir, `universal${suffix}`);

  // Clean previous output
  if (fs.existsSync(universalDir)) {
    fs.rmSync(universalDir, { recursive: true, force: true });
  }

This initialization prevents stale files from contaminating new builds, critical for reproducible distribution artifacts.

Provider Mapping Strategy

An explicit mapping array defines the relationship between internal provider names and their emitted configuration directories. This hardcoded registry in scripts/build.js lines 42-48 ensures the build system knows exactly which dot-folders to collect.

• Cursor maps to .cursor
• Claude Code maps to .claude
• Gemini maps to .gemini
• Codex maps to .codex
• Agents maps to .agents
• Kiro maps to .kiro

This declarative approach makes it trivial to add new providers by extending the providerMappings array.

Directory Copying Logic

For each mapping, the script constructs source and destination paths dynamically. When the suffix is -prefixed, it targets directories like dist/cursor-prefixed/.cursor instead of the standard dist/cursor/.cursor. The helper copyDirSync recursively transfers the entire directory tree only if the source exists.

const providerMappings = [
  { provider: 'cursor',      configDir: '.cursor' },
  { provider: 'claude-code', configDir: '.claude' },
  { provider: 'gemini',      configDir: '.gemini' },
  { provider: 'codex',       configDir: '.codex' },
  { provider: 'agents',      configDir: '.agents' },
  { provider: 'kiro',        configDir: '.kiro' },
];

for (const { provider, configDir } of providerMappings) {
  const src = path.join(distDir, `${provider}${suffix}`, configDir);
  const dest = path.join(universalDir, configDir);
  if (fs.existsSync(src)) {
    copyDirSync(src, dest);
  }
}

This loop ensures that even if a specific provider build is missing, the universal bundle assembly continues for the remaining platforms.

Documentation Generation

Because the assembled folders are hidden dot-directories (e.g., .cursor, .claude), the build script generates a README.txt file inside the universal directory to guide installation. When the suffix indicates a prefixed bundle, the README includes a special note that skill IDs are prefixed with i- to avoid collisions.

const prefixNote = suffix ? '\nSkills in this bundle are prefixed with i- …\n' : '';
fs.writeFileSync(
  path.join(universalDir, 'README.txt'),
  `Impeccable — Design fluency for AI harnesses\nhttps://impeccable.style\n${prefixNote}…`
);

This self-documentation eliminates ambiguity for end users unpacking the archive into their projects.

Build Integration and Packaging

The universal assembly integrates into the main build flow through explicit orchestration and subsequent compression.

Dual Bundle Generation

The build() function in scripts/build.js invokes assembleUniversal twice to create both distribution variants:

// Inside build()
assembleUniversal(DIST_DIR);                // regular bundle
assembleUniversal(DIST_DIR, '-prefixed');   // prefixed bundle

This dual-pass approach generates universal/ and universal-prefixed/ directories side-by-side in the dist folder, accommodating users who need namespaced skill identifiers.

ZIP Archive Creation

After assembly, the createAllZips function in scripts/lib/zip.js compresses these directories into universal.zip and universal-prefixed.zip. This final step transforms the assembled directories into single-file artifacts ready for GitHub releases or direct download.

await createAllZips(DIST_DIR);  // Creates universal.zip & universal-prefixed.zip

According to the source code in scripts/lib/zip.js, this utility specifically targets the universal directories alongside individual provider packages, ensuring the aggregated bundles receive the same distribution treatment as standalone builds.

Summary

• Clean slate approach: assembleUniversal always removes existing universal directories before copying to prevent stale artifacts.
• Explicit provider registry: The providerMappings array in scripts/build.js hardcodes the six supported AI assistants and their respective config folder names.
• Suffix-driven variants: Passing '-prefixed' as the suffix parameter triggers alternative source paths and modified README documentation.
• Recursive file operations: The copyDirSync helper handles deep directory trees, while fs.rmSync with recursive: true ensures clean deletion.
• Self-documenting output: Generated README.txt files explain the bundle contents and prefixing behavior directly within the distribution archive.

Frequently Asked Questions

What is the universal bundle in Impeccable?

The universal bundle is a consolidated directory containing configuration folders for all six supported AI providers (Cursor, Claude Code, Gemini, Codex, Agents, and Kiro) in their native formats. It allows users to copy a single universal folder into their project to enable Impeccable skills across every supported toolchain simultaneously.

How does the build script handle prefixed vs regular bundles?

The assembleUniversal function accepts a suffix parameter that defaults to an empty string. When called with '-prefixed', it sources files from directories like cursor-prefixed/ instead of cursor/, and injects a note into the README explaining that all skill IDs carry the i- prefix. The build script runs the function twice—once without and once with the suffix—to generate both variants.

Where are the provider-specific configuration files stored?

Individual provider builds reside in dist/{provider}/ (e.g., dist/cursor/.cursor, dist/claude-code/.claude). The assembleUniversal function aggregates these into dist/universal/ by copying each provider's dot-folder into the combined structure according to the mappings defined in scripts/build.js.

What utility functions support the universal assembly process?

The process relies on ** copyDirSync** for recursive directory copying and ** fs.rmSync** with the recursive: true option for cleanup. Additionally, the ** createAllZips** function in scripts/lib/zip.js handles the final compression of the assembled universal directories into distribution-ready ZIP archives.

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