pbakaus_impeccable/DEVELOP.md

Developer Guide

Documentation for contributors to Impeccable.

Architecture

This repository uses a feature-rich source format that transforms into provider-specific formats. We chose "Option A" architecture: maintain full metadata in source files and downgrade for providers with limited support (like Cursor), rather than limiting everyone to the lowest common denominator.

Why This Approach?

Different providers have different capabilities:

• Cursor: No frontmatter or argument support
• Claude Code, Gemini, Codex: Full support for metadata and arguments

By maintaining rich source files, we preserve maximum functionality where supported while still providing working (if simpler) versions for all providers.

Source Format

Commands (source/commands/*.md)

---
name: command-name
description: What this command does
args:
  - name: argname
    description: Argument description
    required: false
---

Your command prompt here with {{argname}} placeholders...

Frontmatter fields:

• name (required): Command identifier
• description (required): What the command does
• args (optional): Array of argument objects
  • name: Argument identifier
  • description: What it's for
  • required: Boolean (defaults to false)

Body: The actual prompt. Use {{argname}} for argument placeholders (automatically transformed to provider-specific syntax).

Skills (source/skills/*.md)

---
name: skill-name
description: What this skill provides
license: License info (optional)
compatibility: Environment requirements (optional)
---

Your skill instructions here...

Frontmatter fields (based on Agent Skills spec):

• name (required): Skill identifier (1-64 chars, lowercase/numbers/hyphens)
• description (required): What the skill provides (1-1024 chars)
• license (optional): License/attribution info
• compatibility (optional): Environment requirements (1-500 chars)
• metadata (optional): Arbitrary key-value pairs
• allowed-tools (optional, experimental): Pre-approved tools list

Body: The skill instructions for the LLM.

Building

Prerequisites

• Bun (fast JavaScript runtime and package manager)
• No external dependencies required

Commands

# Build all provider formats
bun run build

# Clean dist folder
bun run clean

# Rebuild from scratch
bun run rebuild

What Gets Generated

source/                  → dist/
  commands/*.md            cursor/commands/*.md         (body only)
  skills/*.md              cursor/skills/*/SKILL.md     (Agent Skills standard)

                           claude-code/commands/*.md    (full frontmatter)
                           claude-code/skills/*/SKILL.md

                           gemini/commands/*.toml       (TOML format)
                           gemini/GEMINI*.md            (modular)

                           codex/prompts/*.md           (custom prompt format)
                           codex/skills/*/SKILL.md      (Agent Skills standard)

Provider Transformations

Cursor (Agent Skills Standard)

• Commands → Body only → dist/cursor/.cursor/commands/*.md (no frontmatter support)
• Skills → Agent Skills standard → dist/cursor/.cursor/skills/{name}/SKILL.md
  • Full YAML frontmatter support
  • Reference files in skill subdirectories
• Note: Agent Skills require Cursor nightly channel

Claude Code (Full Featured)

• Keeps full YAML frontmatter + body
• Commands → dist/claude-code/commands/*.md
• Skills → dist/claude-code/skills/{name}/SKILL.md

Gemini CLI (Full Featured)

• Commands converted to TOML format → dist/gemini/commands/*.toml
  • description and prompt keys
  • Arguments converted to {{args}} (Gemini uses single args string)
• Skills → Modular GEMINI.{name}.md files
• Main GEMINI.md imports skill files using @./GEMINI.{name}.md syntax
  • Uses Gemini's native import feature for modular context files

Codex CLI (Full Featured)

• Commands → Custom prompts with argument-hint → dist/codex/.codex/prompts/*.md
  • Frontmatter uses description and argument-hint (not args array)
  • Placeholders transformed from {{argname}} to $ARGNAME (uppercase)
  • Invoked as /prompts:<name>
• Skills → Agent Skills standard → dist/codex/.codex/skills/{name}/SKILL.md
  • Uses same SKILL.md format as Claude Code
  • Reference files in subdirectories

Pi (Agent Skills Standard)

• Skills → Agent Skills standard → dist/pi/.pi/skills/{name}/SKILL.md
  • Standard frontmatter: name, description, license, compatibility, metadata
  • Reference files in skill subdirectories

Adding New Content

1. Create Source File

For a command:

# Create source/commands/mycommand.md
touch source/commands/mycommand.md

Add frontmatter and content following the format above.

For a skill:

# Create source/skills/myskill.md
touch source/skills/myskill.md

Add frontmatter and content following the format above.

2. Build

bun run build

This generates all 4 provider formats automatically.

3. Test

Test with your provider of choice to ensure it works correctly. Remember that Cursor will have limited functionality.

4. Commit

Commit both source and dist files:

git add source/ dist/
git commit -m "Add [command/skill name]"

Important: The dist/ directory is committed intentionally so end users can use files without building.

Build System Details

The build system (scripts/build.js) is a single ~170-line Node.js script with:

• Custom YAML frontmatter parser (no dependencies)
• Provider-specific transformation functions
• Automatic directory management
• Zero external dependencies (pure Node.js)

Key Functions

• parseFrontmatter(): Extracts YAML frontmatter and body
• readSourceFiles(): Recursively reads source files
• transformCursor(): Strips frontmatter for Cursor
• transformClaudeCode(): Keeps full format
• transformGemini(): Converts to TOML + modular skills
• transformCodex(): Full format + modular skills

Best Practices

Command Writing

1. Clear descriptions: Make purpose obvious
2. Meaningful argument names: Use descriptive names
3. Flexible prompts: Write prompts that work even without argument substitution (for Cursor compatibility)
4. Test across providers: Verify it works in multiple contexts

Skill Writing

1. Focused scope: One clear domain per skill
2. Clear instructions: LLM should understand exactly what to do
3. Include examples: Where they clarify intent
4. State constraints: What NOT to do as clearly as what to do

Reference Documentation

• Agent Skills Specification - Open standard
• Cursor Commands
• Cursor Rules
• Cursor Skills
• Claude Code Slash Commands
• Anthropic Skills (Claude Code)
• Gemini CLI Custom Commands
• Gemini CLI Skills
• Codex CLI Slash Commands
• Codex CLI Skills
• Pi Skills

Repository Structure

impeccable/
├── source/              # Edit these! Source of truth
│   ├── commands/        # Command definitions
│   │   └── normalize.md
│   └── skills/          # Skill definitions
│       └── frontend-design.md
├── dist/                # Generated (committed for users)
│   ├── cursor/
│   ├── claude-code/
│   ├── gemini/
│   ├── codex/
│   ├── agents/
│   ├── kiro/
│   ├── opencode/
│   └── pi/
├── scripts/
│   └── build.js         # Build system (~170 lines, zero deps)
├── package.json         # ESM project config
├── README.md            # User documentation
├── DEVELOP.md           # This file
└── .gitignore

Troubleshooting

Build fails with YAML parsing errors

• Check frontmatter indentation (YAML is indent-sensitive)
• Ensure --- delimiters are on their own lines
• Verify colons have spaces after them (key: value)

Output doesn't match expectations

• Check the transformer function for your provider in scripts/build.js
• Verify source file has correct frontmatter structure
• Run npm run rebuild to ensure clean build

Provider doesn't recognize the files

• Check installation path for your provider
• Verify file naming matches provider requirements
• Consult provider's documentation (links above)

Questions?

Open an issue or submit a PR!