Skip to main content
Impeccable uses a sophisticated build system to maintain one source of truth for design skills and commands, then automatically transform them into provider-specific formats. Each AI tool has different capabilities, so we adapt the output rather than limiting the source.

​
Architecture Overview

Impeccable uses Option A: Feature-Rich Source architecture:
1

Source Files

Full metadata with YAML frontmatter, args, descriptions. Located in source/ directory.
2

Build System

Transforms source → provider-specific formats using Bun. Located in scripts/ directory.
3

Distribution

Committed output files for 6 providers in dist/ directory. Users can copy directly without build tools.

​
Why Option A?

Different providers have different capabilities:
  • Cursor: No frontmatter or arguments support (lowest common denominator)
  • Claude Code: Full YAML frontmatter, arguments, modular files
  • Gemini CLI: TOML commands, modular skills with imports
  • Codex CLI: Custom prompt format, arguments as variables
  • Agents: Agent Skills standard for VS Code Copilot, Antigravity
  • Kiro: Custom skill format
Instead of limiting all providers to Cursor’s capabilities, we:
  1. Author with full metadata in source files
  2. Generate full-featured versions for providers that support it
  3. Generate downgraded versions for Cursor
This allows each provider to use its native features while maintaining a single source of truth.

​
Source File Format

All skills follow the Agent Skills specification with YAML frontmatter: 
---
name: skill-name
description: Clear description of what this skill provides
license: License info (optional)
---

Skill instructions for the LLM here.

​
Skills vs Commands

Impeccable previously distinguished between skills and commands, but has now unified to a skills-only architecture:
  • Skills can be user-invokable (like commands) or non-invokable (like traditional skills)
  • The userInvokable: true frontmatter flag determines if a skill appears as a slash command
  • This simplifies the codebase while maintaining the same functionality

User-Invokable Skills

Skills with userInvokable: true appear as slash commands like /audit, /polish, /critique

Reference Skills

Skills like frontend-design are loaded automatically and provide context, not direct commands

​
Build System

The build system uses Bun for fast, zero-config builds. It follows a modular transformer pattern:

​
Architecture

scripts/
├── build.js              # Main orchestrator (~255 lines)
├── lib/
│   ├── utils.js          # Shared functions (parsing, file I/O)
│   ├── zip.js            # ZIP bundle generation
│   └── transformers/     # Provider-specific transformers
│       ├── cursor.js     # Strips frontmatter
│       ├── claude-code.js # Full featured
│       ├── gemini.js     # TOML commands + modular skills
│       ├── codex.js      # Custom prompt format
│       ├── agents.js     # Agent Skills standard
│       ├── kiro.js       # Kiro format
│       └── index.js      # Transformer registry

​
Build Process

1

Read Source Files

Parse all skills with YAML frontmatter from source/.claude/skills/
2

Transform for Each Provider

Apply provider-specific transformations (6 providers × 2 versions = 12 outputs)
3

Assemble Universal

Combine all provider outputs into universal bundles
4

Create ZIPs

Generate downloadable ZIP files for each provider
5

Build Website

Compile Tailwind CSS and bundle static site with Bun
Run the build: 
bun run build
Bun is 2-4x faster than Node.js and includes TypeScript support, package management, and bundling—no additional tools needed.

​
Provider Transformations

Each provider has a focused transformer file (~30-85 lines). Here’s how each works:

​
1. Cursor (Agent Skills Standard)

Format: Agent Skills standard
  • Skills: dist/cursor/.cursor/skills/{name}/SKILL.md
    • Full YAML frontmatter with name/description
    • Reference files in skill subdirectories
  • Installation: Extract ZIP into project root, creates .cursor/ folder
  • Limitation: Requires Cursor nightly channel
# Example: SKILL.md with frontmatter
---
name: audit
description: Run technical quality checks
---

Instructions...

​
2. Claude Code (Full Featured)

Format: Full YAML frontmatter (matches Anthropic Skills spec)
  • Skills: dist/claude-code/.claude/skills/{name}/SKILL.md
  • Preserves: All metadata, all args
  • Installation: Extract ZIP into project root or ~/.claude/ for global
This is the reference implementation—full metadata, modular structure, maximum flexibility.

​
3. Gemini CLI (Full Featured)

Format: Modular with imports
  • Skills: dist/gemini/GEMINI.{name}.md (root level)
    • Main GEMINI.md uses @./GEMINI.{name}.md import syntax
    • Gemini automatically loads imported files for better context management
  • Installation: Extract ZIP into project root, creates .gemini/ folder + skill files
# GEMINI.md
@./GEMINI.frontend-design.md
@./GEMINI.audit.md

​
4. Codex CLI (Full Featured)

Format: Agent Skills standard
  • Skills: dist/codex/.codex/skills/{name}/SKILL.md
    • Same SKILL.md format as Claude Code with YAML frontmatter
    • Reference files in skill subdirectories
  • Installation: Extract ZIP into project root, creates .codex/ folder

​
5. Agents (VS Code Copilot + Antigravity)

Format: Agent Skills standard
  • Skills: dist/agents/.agents/skills/{name}/SKILL.md
  • Installation: Extract ZIP into project root, creates .agents/ folder

​
6. Kiro

Format: Kiro custom format
  • Skills: dist/kiro/.kiro/skills/{name}/SKILL.md
  • Installation: Extract ZIP into project root, creates .kiro/ folder

​
Prefixed Versions

All providers are built in two versions:

Standard

Commands like /audit, /polish, /critique

Prefixed

Commands prefixed with i-: /i-audit, /i-polish, /i-critique. Useful for avoiding conflicts with existing commands.
The build system generates both automatically: 
// Standard version
transformClaudeCode(skills, DIST_DIR, patterns);

// Prefixed version
transformClaudeCode(skills, DIST_DIR, patterns, { 
  prefix: 'i-', 
  outputSuffix: '-prefixed' 
});

​
Universal Bundle

The universal bundle contains all providers in one package: 
universal/
├── .cursor/    → Cursor
├── .claude/    → Claude Code
├── .gemini/    → Gemini CLI (+ root-level files)
├── .codex/     → Codex CLI
├── .agents/    → VS Code Copilot, Antigravity
├── .kiro/      → Kiro
└── README.txt  → Installation instructions
These are hidden folders (dotfiles). On macOS, press Cmd+Shift+. in Finder to see them.

​
Key Design Decisions

​
Why Commit dist/?

End users can copy files directly without needing build tools. This makes installation trivial—just download and extract.

​
Why Separate Transformers?

  • Each provider ~30-85 lines, easy to understand
  • Can modify one without affecting others
  • Easy to add new providers (just add a new transformer file)

​
Why Bun?

Speed

Much faster than Node.js (2-4x)

All-in-One

Runtime + package manager + bundler

Zero Config

TypeScript native, no configuration needed

Compatible

Works with existing Node.js code

​
Why Modular Skills?

For Gemini and other providers that support it:
  • Better context management: Load only what’s needed
  • Cleaner organization: Each skill is independent
  • Native imports: Gemini uses @file.md syntax to load dependencies

​
Adding New Content

To add a new skill or update existing ones:
1

Edit Source Files

Create or modify files in source/.claude/skills/. Always edit source, never edit dist/ directly.
2

Add Frontmatter

Include YAML frontmatter with name, description, and userInvokable (if it’s a command).
3

Write Instructions

Write the skill body with clear instructions for the LLM.
4

Build

Run bun run build to generate all provider outputs.
5

Test

Test with your provider to verify the transformation works correctly.
6

Commit

Commit both source and dist files to keep them in sync.
Source is truth: Always edit source/, never edit dist/ directly. The build system overwrites dist/ on every run.

​
Website Integration

The build system also handles the website at impeccable.style:

​
Tech Stack

  • Frontend: Vanilla JavaScript, modern CSS
  • Styling: Tailwind CSS v4 with @theme directive
  • Development: Bun server with native routes (server/index.js)
  • Production: Vercel Functions with Bun runtime (/api directory)

​
Dual Server Setup

Development

Monolithic Bun server at server/index.js for fast local iteration

Production

Individual Vercel Functions in /api directory for serverless deployment
Both share the same handler logic from server/lib/api-handlers.js—zero duplication.

​
API Endpoints

EndpointPurpose
/Homepage (static HTML)
/api/skillsJSON list of all skills
/api/commandsJSON list of all commands
/api/download/[type]/[provider]/[id]Individual file download
/api/download/bundle/[provider]ZIP bundle download

​
Transformer Pattern

Each transformer follows the same interface: 
export function transformProviderName(skills, distDir, patterns, options = {}) {
  const { prefix = '', outputSuffix = '' } = options;
  const outputDir = path.join(distDir, `provider-name${outputSuffix}`);
  
  // 1. Filter to user-invokable skills
  const invokableSkills = skills.filter(s => s.userInvokable);
  
  // 2. Transform each skill
  for (const skill of skills) {
    // Provider-specific transformation logic
  }
  
  // 3. Write to output directory
  console.log(`✓ Provider Name: ${skills.length} skills`);
}
This pattern makes it easy to:
  • Add new providers (just implement the interface)
  • Test transformations in isolation
  • Maintain consistency across providers

​
Related

Design Principles

Learn the design principles encoded in the skills

Contributing

Guidelines for contributing to Impeccable

Build docs developers (and LLMs) love

Get started for freeTalk to us