Visual Atelier Skill

Visual Atelier is a Claude Code skill and TypeScript CLI for turning rough visual intent into image briefs, generated assets, edit requests, and QA reports. It supports editorial illustrations, product hero images, technical diagrams, framework visuals, thumbnails, icon packs, and controlled image refinement.

The CLI uses real provider APIs only. Gemini Nano Banana and OpenAI Images calls either run with valid credentials or fail clearly before a request is made.

What It Does

• Converts a short user request into a structured provider prompt with art direction, composition guidance, aspect ratio, output format, and a quality checklist.
• Provides reusable workflow templates for common production jobs.
• Generates or edits images through Gemini or OpenAI.
• Writes a JSON receipt beside each generated image with provider, model, prompt, workflow, timestamp, input image, and output path.
• Inspects local image outputs for MIME type, dimensions, file size, and receipt validity.
• Includes both a Claude skill (SKILL.md) and a CLI (atelier).

How the Skill Works

Claude uses SKILL.md as the operating guide. When the user asks for a visual asset, Claude should:

1. Choose the closest workflow from Workflows/ or by running atelier workflows.
2. Compile the user request into a production brief with atelier brief.
3. Generate a new image with atelier generate or refine an existing image with atelier edit.
4. Inspect the finished file with atelier inspect.
5. Use the sidecar receipt to keep track of how the output was created.

The CLI keeps the creative prompt logic in code, so the same workflow can be repeated consistently from Claude, a terminal, or CI smoke tests.

Repository Layout

.
├── SKILL.md                 # Claude skill instructions
├── Workflows/               # Human-readable production workflow notes
├── References/              # Provider and implementation notes
├── src/                     # TypeScript CLI and library code
├── tests/                   # Bun test suite
├── examples/                # Example invocations and briefs
├── outputs/                 # Runtime output folder, kept empty in git
└── package.json

Installation

bun install
bun run build

For local development, you can run the TypeScript source directly with Bun. After bun run build, the compiled CLI is available at dist/cli.js and the package binary is atelier.

Configuration

Create a local .env from .env.example and set the provider key you want to use.

cp .env.example .env

Required provider keys:

• GEMINI_API_KEY for Gemini generation and editing.
• OPENAI_API_KEY for OpenAI image generation and editing.

Optional model overrides:

• ATELIER_GEMINI_MODEL, default gemini-2.5-flash-image.
• ATELIER_GEMINI_PREMIUM_MODEL, documented premium option gemini-3-pro-image-preview.
• ATELIER_OPENAI_IMAGE_MODEL, default gpt-image-2.

The Gemini defaults follow the current Google Nano Banana API docs, which list gemini-2.5-flash-image and gemini-3-pro-image-preview.

CLI Usage

List available workflows:

bun src/cli.ts workflows

Compile a brief without calling an image provider:

bun src/cli.ts brief \
  --workflow product-hero \
  --topic "privacy-first analytics dashboard for security teams"

Generate a new image:

bun src/cli.ts generate \
  --workflow editorial-illustration \
  --prompt "AI reliability represented as an air traffic control room" \
  --provider gemini \
  --output outputs/ai-reliability.png

Edit an existing image:

bun src/cli.ts edit \
  --input /path/to/source-image.png \
  --prompt "clean up the background while preserving the product geometry" \
  --provider openai \
  --output outputs/product-refinement.png

Inspect an output and its sidecar receipt:

bun src/cli.ts inspect --image outputs/ai-reliability.png

Workflows

Visual Atelier includes eight production workflows:

• editorial-illustration: narrative visuals for reports, essays, and newsletters.
• technical-diagram: diagrams, schematics, architecture visuals, and explanatory flows.
• framework-matrix: 2x2s, funnels, ladders, flywheels, and business frameworks.
• product-hero: product renders, launch visuals, and feature hero images.
• social-thumbnail: YouTube, LinkedIn, X, and campaign thumbnails.
• icon-asset-pack: cohesive icons and small product assets.
• image-edit-refinement: controlled image edits that preserve source identity.
• visual-qa-report: diagnostic visuals and correction guidance.

Each workflow defines art direction, composition rules, aspect ratio, output format, and a quality checklist. The prompt compiler combines those workflow defaults with the user’s intent.

Metadata Receipts

Every successful provider run writes:

outputs/example.png
outputs/example.png.json

The receipt captures the provider, model, compiled prompt, workflow slug, creation timestamp, output path, and optional input image path. This makes generated assets easier to review and reproduce.

Testing

bun run typecheck
bun run test
bun run build

The test suite covers workflow loading, prompt compilation, provider configuration errors, sidecar writing, image inspection, and provider smoke tests. Smoke tests are skipped automatically unless GEMINI_API_KEY or OPENAI_API_KEY is present.

License

MIT