Differences Between Impeccable Provider Outputs: Cursor, Claude Code, Gemini, Codex, Agents, and Kiro

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 repository stores all design knowledge as markdown skills in source/skills/. During the build process orchestrated by 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 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 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 invokes each transformer sequentially, outputting to dist/<provider>/ 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 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).

---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces...
---

Claude Code Output

The Claude Code transformer in 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).

---
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 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 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'].

---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces...
argument-hint: <THEME=value>
---

Agents Output (VS Code Copilot + Antigravity)

The Agents transformer in 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 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}}.

---
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:

cp -r dist/cursor/.cursor my-project/

# Creates .cursor/skills/ with SKILL.md files

Claude Code:

cp -r dist/claude-code/.claude my-project/

# Creates .claude/skills/ with rich front-matter for structured invocation

Gemini:

cp -r dist/gemini/.gemini my-project/

# Creates .gemini/skills/ with unified {{args}} placeholder

Codex:

cp -r dist/codex/.codex/* ~/.codex/

# Installs to ~/.codex/ for /prompts:<skill> invocations with $VARIABLE syntax

Agents (VS Code):

cp -r dist/agents/.agents/* ~/.config/Code/User/

# Makes skills available via slash-commands in VS Code Copilot

Kiro:

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 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 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, 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 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.

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