1# Impeccable
  2
  3The vocabulary you didn't know you needed. 1 skill, 18 commands, and curated anti-patterns for impeccable style. Works with Cursor, Claude Code, Gemini CLI, and Codex CLI.
  4
  5## Repository Purpose
  6
  7Maintain a **single source of truth** for design-focused skills and commands, then automatically transform them into provider-specific formats. Each provider has different capabilities (frontmatter, arguments, modular files), so we use a build system to generate appropriate outputs.
  8
  9## Architecture: Option A (Feature-Rich Source)
 10
 11We use a **feature-rich source format** that gets transformed for each provider:
 12
 13- **Source files** (`source/`): Full metadata with YAML frontmatter, args, descriptions
 14- **Build system** (`scripts/`): Transforms source → provider-specific formats
 15- **Distribution** (`dist/`): Committed output files for 4 providers
 16
 17### Why Option A?
 18
 19Cursor doesn't support frontmatter or arguments (lowest common denominator). Instead of limiting all providers, we:
 201. Author with full metadata in source files
 212. Generate full-featured versions for providers that support it (Claude Code, Gemini, Codex)
 223. Generate downgraded versions for Cursor (strip frontmatter, rely on appending)
 23
 24## Repository Structure
 25
 26```
 27impeccable/
 28├── source/                      # EDIT THESE! Single source of truth
 29│   ├── commands/                # Command definitions with frontmatter
 30│   │   └── normalize.md
 31│   └── skills/                  # Skill definitions with frontmatter
 32│       └── impeccable/
 33├── dist/                        # Generated outputs (committed for users)
 34│   ├── cursor/                  # Commands + Agent Skills
 35│   │   └── .cursor/
 36│   │       ├── commands/*.md
 37│   │       └── skills/*/SKILL.md
 38│   ├── claude-code/             # Full featured
 39│   │   └── .claude/
 40│   │       ├── commands/*.md
 41│   │       └── skills/*/SKILL.md
 42│   ├── gemini/                  # TOML commands + modular skills
 43│   │   ├── .gemini/
 44│   │   │   └── commands/*.toml
 45│   │   ├── GEMINI.md
 46│   │   └── GEMINI.*.md
 47│   └── codex/                   # Custom prompts + Agent Skills
 48│       └── .codex/
 49│           ├── prompts/*.md
 50│           └── skills/*/SKILL.md
 51├── api/                         # Vercel Functions (production)
 52│   ├── skills.js                # GET /api/skills
 53│   ├── commands.js              # GET /api/commands
 54│   └── download/
 55│       ├── [type]/[provider]/[id].js   # Individual downloads
 56│       └── bundle/[provider].js        # Bundle downloads
 57├── public/                      # Website for impeccable.style
 58│   ├── index.html               # Main page
 59│   ├── css/                     # Modular CSS (9 files)
 60│   │   ├── main.css             # Entry point with imports
 61│   │   ├── tokens.css           # Design system
 62│   │   └── ...                  # Component styles
 63│   └── app.js                   # Vanilla JS
 64├── server/                      # Bun server (local dev only)
 65│   ├── index.js                 # Serves website + API routes
 66│   └── lib/
 67│       └── api-handlers.js      # Shared API logic (used by both server & functions)
 68├── scripts/                     # Build system (Bun)
 69│   ├── build.js                 # Main orchestrator
 70│   ├── lib/
 71│   │   ├── utils.js             # Shared utilities
 72│   │   ├── zip.js               # ZIP generation
 73│   │   └── transformers/        # Provider-specific transformers
 74│   │       ├── cursor.js
 75│   │       ├── claude-code.js
 76│   │       ├── gemini.js
 77│   │       └── codex.js
 78├── README.md                    # End user documentation
 79├── DEVELOP.md                   # Contributor documentation
 80└── package.json                 # Bun scripts
 81```
 82
 83## Website (impeccable.style)
 84
 85**Tech Stack:**
 86- Vanilla JavaScript (no frameworks)
 87- Modern CSS with Bun's bundler (nesting, OKLCH colors, @import)
 88- **Local Development**: Bun server with native routes (`server/index.js`)
 89- **Production**: Vercel Functions with Bun runtime (`/api` directory)
 90- Deployed on Vercel with Bun runtime
 91
 92**Dual Setup:**
 93- `/api` directory contains individual Vercel Functions for production
 94- `/server` directory contains monolithic Bun server for local development
 95- `/server/lib/api-handlers.js` contains shared logic used by both
 96- Zero duplication: API functions and dev server import the same handlers
 97
 98**Design:**
 99- Editorial precision aesthetic
100- Cormorant Garamond (display) + Instrument Sans (body)
101- OKLCH color space for vibrant, perceptually uniform colors
102- Editorial sidebar layout (title left, content right)
103- Modular CSS architecture (9 files)
104
105**API Endpoints** (Vercel Functions):
106- `/` - Homepage (static HTML)
107- `/api/skills` - JSON list of all skills
108- `/api/commands` - JSON list of all commands
109- `/api/download/[type]/[provider]/[id]` - Individual file download
110- `/api/download/bundle/[provider]` - ZIP bundle download
111
112## Source File Format
113
114### Commands (`source/commands/*.md`)
115
116```yaml
117---
118name: command-name
119description: Clear description of what this command does
120args:
121  - name: argname
122    description: Argument description
123    required: false
124---
125
126Command prompt here. Use {{argname}} placeholders for arguments.
127```
128
129### Skills (`source/skills/*.md`)
130
131```yaml
132---
133name: skill-name
134description: Clear description of what this skill provides
135license: License info (optional)
136---
137
138Skill instructions for the LLM here.
139```
140
141## Build System
142
143Uses **Bun** for fast builds. Modular architecture:
144
145- **`utils.js`**: Shared functions (parseFrontmatter, readSourceFiles, writeFile, etc.)
146- **Transformer pattern**: Each provider has one focused file
147- **Registry**: `transformers/index.js` exports all transformers
148- **Main script**: `build.js` orchestrates everything (~50 lines)
149
150Run: `bun run build`
151
152## Provider Transformations
153
154### 1. Cursor (Agent Skills Standard)
155- **Commands**: Body only → `dist/cursor/.cursor/commands/*.md` (no frontmatter support)
156- **Skills**: Agent Skills standard → `dist/cursor/.cursor/skills/{name}/SKILL.md`
157  - Full YAML frontmatter with name/description
158  - Reference files in skill subdirectories
159- **Installation**: Extract ZIP into your project root, creates `.cursor/` folder
160- **Note**: Agent Skills require Cursor nightly channel
161
162### 2. Claude Code (Full Featured)
163- **Commands**: Full YAML frontmatter → `dist/claude-code/.claude/commands/*.md`
164- **Skills**: Full YAML frontmatter → `dist/claude-code/.claude/skills/{name}/SKILL.md`
165- **Preserves**: All metadata, all args
166- **Format**: Matches [Anthropic Skills spec](https://github.com/anthropics/skills)
167- **Installation**: Extract ZIP into your project root, creates `.claude/` folder
168
169### 3. Gemini CLI (Full Featured)
170- **Commands**: TOML format → `dist/gemini/.gemini/commands/*.toml`
171  - Uses `description` and `prompt` keys
172  - Transforms `{{argname}}` → `{{args}}` (Gemini uses single args string)
173- **Skills**: Modular with imports → `dist/gemini/GEMINI.{name}.md` (root level)
174  - Main `GEMINI.md` uses `@./GEMINI.{name}.md` import syntax
175  - Gemini automatically loads imported files
176- **Installation**: Extract ZIP into your project root, creates `.gemini/` folder + skill files
177
178### 4. Codex CLI (Full Featured)
179- **Commands**: Custom prompt format → `dist/codex/.codex/prompts/*.md`
180  - Uses `description` and `argument-hint` in frontmatter
181  - Transforms `{{argname}}` → `$ARGNAME` (uppercase variables)
182  - Invoked as `/prompts:<name>`
183- **Skills**: Agent Skills standard → `dist/codex/.codex/skills/{name}/SKILL.md`
184  - Same SKILL.md format as Claude Code with YAML frontmatter
185  - Reference files in skill subdirectories
186- **Installation**: Extract ZIP into your project root, creates `.codex/` folder
187
188## Key Design Decisions
189
190### Why commit dist/?
191End users can copy files directly without needing build tools.
192
193### Why separate transformers?
194- Each provider ~30-85 lines, easy to understand
195- Can modify one without affecting others
196- Easy to add new providers
197
198### Why Bun?
199- Much faster than Node.js (2-4x)
200- All-in-one toolkit (runtime + package manager)
201- Zero config, TypeScript native
202- Node.js compatible (works with existing code)
203
204### Why modular skills for Gemini/Codex?
205- Better context management (load only what's needed)
206- Cleaner file organization
207- Gemini: Uses native `@file.md` import feature
208- Codex: Uses routing pattern with AGENTS.md guide
209
210### Why vanilla JS for website?
211- No build complexity
212- Bun handles everything natively
213- Modern features (ES6+, CSS nesting, OKLCH colors)
214- Fast, lean, maintainable
215
216## Adding New Content
217
2181. **Create source file** in `source/commands/` or `source/skills/`
2192. **Add frontmatter** with name, description, args (for commands) or license (for skills)
2203. **Write body** with instructions/prompt
2214. **Build**: `bun run build`
2225. **Test** with your provider
2236. **Commit** both source and dist files
224
225## Important Notes
226
227- **Source is truth**: Always edit `source/`, never edit `dist/` directly
228- **Test across providers**: Changes affect 4 different outputs
229- **Argument handling**: Write prompts that work with both placeholders and appending
230- **Cursor limitations**: No frontmatter/args, so design for graceful degradation
231
232## Documentation
233
234- **README.md**: End user guide (installation, usage, quick dev setup)
235- **DEVELOP.md**: Contributor guide (architecture, build system, adding content)
236- **This file (AGENTS.md)**: Context for AI assistants and new developers
237
238## Provider Documentation Links
239
240- [Agent Skills Specification](https://agentskills.io/specification) - Open standard
241- [Cursor Commands](https://cursor.com/docs/agent/chat/commands)
242- [Cursor Rules](https://cursor.com/docs/context/rules)
243- [Cursor Skills](https://cursor.com/docs/context/skills)
244- [Claude Code Slash Commands](https://code.claude.com/docs/en/slash-commands)
245- [Anthropic Skills](https://github.com/anthropics/skills)
246- [Gemini CLI Custom Commands](https://cloud.google.com/blog/topics/developers-practitioners/gemini-cli-custom-slash-commands)
247- [Gemini CLI GEMINI.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md)
248- [Codex CLI Slash Commands](https://developers.openai.com/codex/guides/slash-commands)
249- [Codex CLI Skills](https://developers.openai.com/codex/skills/)
250