# Differences Between Impeccable Provider Outputs: Cursor, Claude Code, Gemini, Codex, Agents, and Kiro > Explore differences in Impeccable's provider outputs Cursor, Claude Code, Gemini, Codex, Agents, and Kiro. Understand variations in metadata, syntax, and substitution across these tools. - Repository: [Paul Bakaus/impeccable](https://github.com/pbakaus/impeccable) - Tags: deep-dive - Published: 2026-03-09 --- **Impeccable maintains a single source of truth in `source/skills/` and uses provider-specific transformers in `scripts/lib/transformers/` to generate tailored bundles for Cursor, Claude Code, Gemini, Codex, Agents, and Kiro, differing in front-matter metadata, argument syntax, and placeholder substitution.** The [pbakaus/impeccable](https://github.com/pbakaus/impeccable) repository stores all design knowledge as markdown skills in `source/skills/`. During the build process orchestrated by [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js), six distinct transformers convert these source files into provider-specific outputs. Each transformer—located in `scripts/lib/transformers/`—modifies YAML front-matter, handles arguments differently, and substitutes provider-specific placeholders to ensure compatibility with each LLM tool's unique requirements. ## How the Build System Transforms Source Files The build pipeline relies on shared utilities in [`scripts/lib/utils.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/utils.js) to process source files before applying provider-specific logic. Three core functions handle the heavy lifting: - **`readSourceFiles()`** – Parses the YAML front-matter of every [`SKILL.md`](https://github.com/pbakaus/impeccable/blob/main/SKILL.md) in `source/skills/` and gathers reference markdown files from `reference/` subdirectories. - **`replacePlaceholders(content, provider, commandNames)`** – Substitutes tokens like `{{model}}`, `{{config_file}}`, and `{{ask_instruction}}` with values from `PROVIDER_PLACEHOLDERS` specific to each provider. - **`generateYamlFrontmatter(data)`** – Constructs the YAML header that each transformer writes to the output file based on provider requirements. After reading sources, [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js) invokes each transformer sequentially, outputting to `dist//` directories while preserving the skill directory structure. ## Provider-Specific Output Differences Each provider receives a customized bundle with distinct front-matter fields, argument handling, and syntax transformations. ### Cursor Output Cursor receives the most minimal transformation. The transformer in [`scripts/lib/transformers/cursor.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/transformers/cursor.js) emits **only skills** (no commands) to `dist/cursor/.cursor/skills/`. Key characteristics: - **Front-matter**: Contains only `name`, `description`, and optional `license`. - **Placeholders**: Uses `replacePlaceholders` with the Cursor model configuration. - **Cross-skill references**: Optionally prefixes references (`/skillname` → `/i-skillname`). ```yaml --- name: frontend-design description: Create distinctive, production-grade frontend interfaces... --- ``` ### Claude Code Output The Claude Code transformer in [`scripts/lib/transformers/claude-code.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/transformers/claude-code.js) produces the richest metadata to `dist/claude-code/.claude/skills/`. Key characteristics: - **Front-matter**: Includes `user-invokable`, `args` (with name, description, required fields), `license`, `compatibility`, `metadata`, and `allowed-tools`. - **Argument preservation**: Maintains the full argument list from source files, allowing Claude Code to present structured input forms. - **Placeholders**: Expands using `PROVIDER_PLACEHOLDERS['claude-code']` (sets `{{model}}` to Claude, `{{config_file}}` to [`CLAUDE.md`](https://github.com/pbakaus/impeccable/blob/main/CLAUDE.md)). ```yaml --- name: frontend-design description: Create distinctive, production-grade frontend interfaces... user-invokable: true args: - name: theme description: Desired visual theme required: false license: Apache 2.0 --- ``` ### Gemini Output Gemini's transformer in [`scripts/lib/transformers/gemini.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/transformers/gemini.js) targets `dist/gemini/.gemini/skills/` and handles arguments differently due to CLI limitations. Key characteristics: - **Argument collapsing**: All `{{arg}}` placeholders in the body are **collapsed to a single `{{args}}`** placeholder because the Gemini CLI accepts only one free-form argument string. - **Front-matter**: Same minimal structure as Cursor (`name`, `description`). - **Placeholders**: Uses `PROVIDER_PLACEHOLDERS['gemini']` for provider-specific values. ### Codex Output The Codex transformer in [`scripts/lib/transformers/codex.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/transformers/codex.js) outputs to `dist/codex/.codex/skills/` and converts Impeccable's argument syntax to Codex's shell-style variables. Key characteristics: - **Variable syntax**: Converts every `{{argName}}` in the body to **`$ARGNAME`** (uppercase) to match Codex's variable interpolation. - **Front-matter**: Includes `argument-hint` generated from the source `args` array to guide users on required inputs, plus optional `license`. - **Placeholders**: Uses `PROVIDER_PLACEHOLDERS['codex']`. ```yaml --- name: frontend-design description: Create distinctive, production-grade frontend interfaces... argument-hint: --- ``` ### Agents Output (VS Code Copilot + Antigravity) The Agents transformer in [`scripts/lib/transformers/agents.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/transformers/agents.js) supports VS Code's Agent system, outputting to `dist/agents/.agents/skills/`. Key characteristics: - **Hybrid front-matter**: Combines Claude Code's `user-invokable` flag with Codex's `argument-hint` logic, but omits Claude-specific fields like `allowed-tools`. - **Variable syntax**: Uses the same `$ARGNAME` uppercase transformation as Codex for body content. - **Placeholders**: Uses `PROVIDER_PLACEHOLDERS['agents']`. ### Kiro Output Kiro's transformer in [`scripts/lib/transformers/kiro.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/transformers/kiro.js) outputs to `dist/kiro/.kiro/skills/` and treats content as plain markdown with minimal processing. Key characteristics: - **No argument handling**: Kiro treats the body as plain markdown without argument-specific transformations. - **Flexible metadata**: Front-matter includes `license`, `compatibility`, and `metadata` (accepting any custom keys), but no structured argument definitions. - **Placeholders**: Uses `PROVIDER_PLACEHOLDERS['kiro']` for basic substitutions like `{{model}}`. ```yaml --- name: frontend-design description: Create distinctive, production-grade frontend interfaces... license: Apache 2.0 compatibility: any metadata: {} --- ``` ## Installing Provider Bundles Each generated bundle follows a specific installation pattern for its target tool. **Cursor**: ```bash cp -r dist/cursor/.cursor my-project/ # Creates .cursor/skills/ with SKILL.md files ``` **Claude Code**: ```bash cp -r dist/claude-code/.claude my-project/ # Creates .claude/skills/ with rich front-matter for structured invocation ``` **Gemini**: ```bash cp -r dist/gemini/.gemini my-project/ # Creates .gemini/skills/ with unified {{args}} placeholder ``` **Codex**: ```bash cp -r dist/codex/.codex/* ~/.codex/ # Installs to ~/.codex/ for /prompts: invocations with $VARIABLE syntax ``` **Agents (VS Code)**: ```bash cp -r dist/agents/.agents/* ~/.config/Code/User/ # Makes skills available via slash-commands in VS Code Copilot ``` **Kiro**: ```bash cp -r dist/kiro/.kiro/* ~/.kiro/ # Installs plain markdown prompts with metadata headers ``` ## Summary - **Impeccable** maintains one source of truth in `source/skills/` and transforms it via [`scripts/build.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/build.js) and six provider-specific transformers. - **Cursor** receives minimal YAML (`name`, `description`) with basic placeholder substitution. - **Claude Code** gets rich front-matter including structured `args`, `user-invokable` flags, and compatibility metadata. - **Gemini** collapses all arguments to a single `{{args}}` placeholder to match its CLI constraints. - **Codex** converts arguments to shell-style `$ARGNAME` variables and includes `argument-hint` in front-matter. - **Agents** combine Claude Code's invocability with Codex's variable syntax for VS Code's Agent system. - **Kiro** outputs plain markdown with flexible metadata but no argument processing. ## Frequently Asked Questions ### Why does Gemini use a single {{args}} placeholder instead of individual arguments? The Gemini CLI only accepts one free-form argument string when invoking custom commands. The transformer in [`scripts/lib/transformers/gemini.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/transformers/gemini.js) collapses all `{{arg}}` placeholders into a single `{{args}}` token to accommodate this limitation, ensuring the skill body can reference user input without requiring named parameter support that the Gemini interface does not provide. ### How does Impeccable handle placeholder substitution across different providers? All transformers call `replacePlaceholders(content, provider, commandNames)` from [`scripts/lib/utils.js`](https://github.com/pbakaus/impeccable/blob/main/scripts/lib/utils.js), which maps tokens like `{{model}}`, `{{config_file}}`, and `{{ask_instruction}}` to values stored in `PROVIDER_PLACEHOLDERS`. Each provider key (cursor, claude-code, gemini, codex, agents, kiro) contains specific strings—for example, `{{model}}` becomes "Claude" for claude-code and kiro, while `{{config_file}}` becomes [`CLAUDE.md`](https://github.com/pbakaus/impeccable/blob/main/CLAUDE.md) or `.cursorrules` depending on the target platform. ### Can I use the same skill source for multiple providers simultaneously? Yes. Because Impeccable keeps skills in `source/skills/` and generates isolated bundles in `dist/`, you can install multiple provider outputs in the same project. For instance, you might copy `dist/cursor/.cursor/` for Cursor IDE support while also using `dist/claude-code/.claude/` for Claude Code CLI, with each tool reading only its own configuration directory. ### What happens to reference files during the build process? If a skill contains a `reference/` subdirectory with additional markdown files, each transformer copies these files unchanged to the output directory after processing them through `replacePlaceholders`. This ensures cross-skill documentation remains available while still substituting provider-specific values like model names or configuration file references.