# How the Impeccable Prefixing System Prevents Command Name Conflicts

> Discover how the Impeccable prefixing system elegantly prevents command name conflicts by automatically generating prefixed command versions, ensuring a smooth installation.

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

---

**The Impeccable prefixing system automatically generates parallel versions of every skill with an `i-` prefix (e.g., `/i-audit` alongside `/audit`), ensuring that installing the universal bundle never overwrites existing commands in your editor.**

The `pbakaus/impeccable` repository implements a systematic namespacing scheme that eliminates command-name collisions across supported AI tooling platforms. By shipping both prefixed and un-prefixed variants in the universal bundle, the Impeccable prefixing system guarantees backward compatibility while preventing conflicts with user-defined or host-editor commands.

## Dual-Version Build Process

The build pipeline orchestrates a double-run of every provider transformer to create two complete sets of skills. In [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js), the orchestrator first generates the standard un-prefixed transforms, then immediately executes each transformer a second time with `prefix: 'i-'` and an output suffix `'-prefixed'`:

```javascript
// scripts/build.js (simplified)
await transformProvider(provider, { prefix: '', suffix: '' });
await transformProvider(provider, { prefix: 'i-', suffix: '-prefixed' });

```

This approach ensures that every provider—Cursor, Claude Code, Gemini, Codex, Agents, and Kiro—ships with identical functionality but distinct command namespaces.

## Name Transformation Pipeline

Each provider’s transformer handles the mechanical renaming of skills and their associated commands. In [`scripts/lib/transformers/cursor.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/transformers/cursor.js), the transformer constructs the final skill name using template literal concatenation:

```javascript
const newSkillName = `${prefix}${skill.name}`;

```

The same logic prefixes every command name injected into the skill body, ensuring that `{{available_commands}}` placeholders receive the updated list. The `replacePlaceholders` utility in [`scripts/lib/utils.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/utils.js) processes these injections during the build, guaranteeing that any dynamic command references reflect the prefixed variant.

## Cross-Reference Rewriting

After placeholder substitution, the system must update any hardcoded references within the skill documentation. The `prefixSkillReferences` utility scans the skill body and systematically rewrites in-text mentions:

- Command invocations like `/audit` become `/i-audit`
- Skill references like "the audit skill" become "the i-audit skill"

This ensures consistency between the declared command names and the documentation users actually read. According to the source code in [`scripts/lib/utils.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/utils.js) (lines 10-25), the utility performs regex-based replacements to catch both slash-commands and prose references.

## Bundle Distribution and User Selection

The `assembleUniversal` step in [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js) merges both the normal and prefixed provider directories into a single `universal` folder. The generated [`README.txt`](https://github.com/pbakaus/impeccable/blob/main/README.txt) explicitly warns users that the prefixed bundle uses the `i-` prefix to avoid conflicts:

```

Skills in this bundle are prefixed with i- (e.g. /i-audit) to avoid conflicts.

```

End-users select their preferred variant through the frontend interface. The toggle logic in [`public/app.js`](https://github.com/pbakaus/impeccable/blob/main/public/app.js) (lines 222-224) allows runtime selection between standard and prefixed bundles:

```javascript
const usePrefixed = document.getElementById('prefix-toggle').checked;
const bundleName = usePrefixed ? `${provider}-prefixed` : provider;
downloadBundle(bundleName);

```

## Summary

- **Parallel generation**: The build script runs each transformer twice—once without a prefix and once with `i-`—to create conflict-free versions of every skill.
- **Systematic renaming**: Transformers modify skill names, command lists, and placeholder values to inject the prefix consistently.
- **Documentation sync**: The `prefixSkillReferences` utility rewrites internal text references so documentation matches the new command names.
- **Universal packaging**: Both variants ship in the same bundle, with a frontend toggle allowing users to choose the prefixed version when conflicts are a concern.

## Frequently Asked Questions

### What is the default prefix used by Impeccable?

The default prefix is **`i-`**. This value is hardcoded in the build script ([`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js)) and is applied to all skills and their associated commands during the second pass of the transformer pipeline.

### Can I customize the prefix value?

While the default build configuration uses `i-`, the transformer architecture accepts any string as the `prefix` parameter. The `transformProvider` function in [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js) passes this value through to each provider-specific transformer, meaning custom build pipelines could theoretically substitute alternative prefixes.

### How does the system handle internal skill references?

The `prefixSkillReferences` function in [`scripts/lib/utils.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/utils.js) (lines 10-25) scans the skill body after placeholder replacement and performs regex-based substitutions. It rewrites both slash-command invocations (e.g., `/audit` → `/i-audit`) and prose mentions (e.g., "the audit skill" → "the i-audit skill") to maintain internal consistency.

### Which files control the prefixing behavior?

Three critical files manage the prefixing lifecycle:
- **[`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js)**: Orchestrates the dual-run build process and assembles the universal bundle with the README warning.
- **[`scripts/lib/utils.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/utils.js)**: Implements `prefixSkillReferences` for text rewriting and `replacePlaceholders` for command list injection.
- **`scripts/lib/transformers/*.js`**: Provider-specific transformers (cursor.js, claude-code.js, etc.) that apply the prefix to skill metadata and command names.