blueprint-extractor

Turn a public website URL into an agent-ready DESIGN.md.

blueprint-extractor is an installable skill for Codex, Codex App, and Claude Code. After installation, you can ask your agent to inspect a public website and write a grounded design brief for future UI implementation.

The generated DESIGN.md helps an agent reuse observed colors, typography, layout rules, component patterns, and responsive behavior instead of guessing from a rough screenshot impression.

This is a skill-first package. It is not a hosted scraping service, not a design token API, and not a tool for cloning websites as runnable code.

Quick Start

1. Install the skill for your agent.
2. Restart the agent so it can discover the skill.
3. Ask the agent to extract a design brief:

/extract https://example.com

If the slash command does not appear, ask directly:

Use the blueprint-extractor skill to create DESIGN.md from https://example.com

By default, the skill writes evidence to .blueprint-extractor/<site-slug>/ and writes the final DESIGN.md in your current project.

Prerequisites

Required:

• Codex CLI, Codex App, or Claude Code
• Node.js 20+ and npm
• Git, if you use the manual git clone install path

Optional, but recommended:

• Playwright Chromium for desktop/mobile screenshots and computed browser styles

The npx skills add ... commands below use npm's npx. You do not need to install the skills CLI globally first. If npx skills add fails in your environment, use the manual fallback for your agent.

Install

Claude Code

Install with the skills CLI:

npx skills add bishoe01/blueprint-extractor --global --agent claude-code

Manual fallback:

mkdir -p ~/.claude/skills
git clone https://github.com/bishoe01/blueprint-extractor.git ~/.claude/skills/blueprint-extractor

Restart Claude Code, then use:

/extract https://example.com

Codex CLI

Install with the skills CLI:

npx skills add bishoe01/blueprint-extractor --global --agent codex

Manual fallback:

mkdir -p ~/.codex/skills
git clone https://github.com/bishoe01/blueprint-extractor.git ~/.codex/skills/blueprint-extractor

Restart Codex or start a new Codex session, then use:

/extract https://example.com

Codex App

Codex App uses the same local skill folder as Codex CLI:

~/.codex/skills/blueprint-extractor

Install with the skills CLI:

npx skills add bishoe01/blueprint-extractor --global --agent codex

Manual fallback:

mkdir -p ~/.codex/skills
git clone https://github.com/bishoe01/blueprint-extractor.git ~/.codex/skills/blueprint-extractor

Quit and reopen Codex App. In a project chat, use:

/extract https://example.com

If the UI does not surface the slash command yet, use a direct natural-language request:

Use the blueprint-extractor skill to create DESIGN.md from https://example.com

Optional Browser Setup

The skill works best when Playwright Chromium is available. This lets the agent capture desktop/mobile screenshots and read computed browser styles.

For Codex CLI or Codex App manual installs:

cd ~/.codex/skills/blueprint-extractor
npm install
npx playwright install chromium

For Claude Code manual installs:

cd ~/.claude/skills/blueprint-extractor
npm install
npx playwright install chromium

If Playwright is not installed, the skill can still use public HTML and CSS, but the result may include lower-confidence visual guidance.

Usage Examples

/extract https://example.com

Extract a DESIGN.md from https://example.com

이 링크 디자인 따서 agent가 쓸 수 있는 DESIGN.md 만들어줘: https://www.toss.im

Output

For each target site, the skill creates an evidence bundle:

.blueprint-extractor/<site-slug>/
  blueprint.json
  sources.json
  screenshot-desktop.png
  screenshot-mobile.png
  DESIGN.md

The root DESIGN.md is the main document your coding agent should read before building UI. The .blueprint-extractor/<site-slug>/ folder stores supporting evidence, source metadata, and screenshots when available.

The final DESIGN.md follows this 9-section contract:

1. Visual Theme & Atmosphere
2. Color Palette & Roles
3. Typography Rules
4. Component Stylings
5. Layout Principles
6. Depth & Elevation
7. Do's and Don'ts
8. Responsive Behavior
9. Agent Prompt Guide

Concrete design values must be traceable to blueprint.json. If the evidence is incomplete, the skill should mark findings as qualitative instead of inventing exact tokens.

The source site is treated as a visual reference, not a product replacement. Generated guidance should preserve the target project's domain, information architecture, and workflows while transferring visual language such as color, typography, spacing, shape, density, surface treatment, and interaction feel.

Safety Boundaries

The skill rejects requests that are unsafe or outside scope:

• non-HTTPS URLs
• localhost, private IPs, link-local hosts, and private hostnames
• auth-gated, paywalled, or user-specific pages
• non-HTML responses
• requests to bypass login, submit forms, perform checkout actions, or scrape private dashboards
• requests to clone a website as runnable production code

It extracts publicly observable design patterns for implementation guidance. It does not claim to produce official brand guidelines.

Troubleshooting

If /extract does not appear, restart your agent first. In Codex App, quit and reopen the app. If the command still does not appear, use the direct prompt:

Use the blueprint-extractor skill to create DESIGN.md from https://example.com

If npx skills add ... fails, use the manual git clone fallback for your agent.

If screenshots are missing, install Playwright Chromium from the skill folder. The skill can still run without it, but visual confidence may be lower.

Update Or Uninstall

Update with the same install command you used originally:

npx skills add bishoe01/blueprint-extractor --global --agent codex

or:

npx skills add bishoe01/blueprint-extractor --global --agent claude-code

For manual installs, remove the skill folder and clone it again.

Codex CLI or Codex App:

rm -rf ~/.codex/skills/blueprint-extractor

Claude Code:

rm -rf ~/.claude/skills/blueprint-extractor

Project Structure

SKILL.md                         agent-facing extraction workflow
references/DESIGN_TEMPLATE.md    required DESIGN.md section contract
references/EXTRACTION_SCHEMA.md  blueprint.json and sources.json schema
references/QUALITY_CHECKLIST.md  release-quality review checklist
references/FAILURE_MODES.md      fallback and blocked-extraction guidance
scripts/extract-blueprint.mjs    optional evidence extraction helper
scripts/validate-design-md.mjs   optional DESIGN.md validator
examples/fixtures/               example prompts and generated fixtures
agents/openai.yaml               agent metadata

Development

From a local checkout:

npm install
npx playwright install chromium
npx skills add . --yes --global --agent codex

For Claude Code local development:

npx skills add . --yes --global --agent claude-code

Run a smoke extraction:

npm run extract -- https://example.com

Validate an example DESIGN.md:

npm run validate-design -- examples/fixtures/example-com-DESIGN.md --blueprint .blueprint-extractor/example-com/blueprint.json

Before publishing examples or release candidates, check:

• concrete tokens are grounded in blueprint.json
• screenshot-only observations stay qualitative
• component guidance is reusable, not a token dump
• source-domain objects are not imported unless the user explicitly asks for that product structure
• confidence warnings stay outside the final DESIGN.md
• the final document does not include unsupported brand claims

License

MIT