prompt-to-asset
AGENTS.md18 starsChanged 7 months agoMITView on GitHub
This repo exposes a prompt-to-asset MCP server (stdio). When generating software assets, follow the rule below and prefer the asset_* MCP tool surface over ad-hoc image generation. When the user asks for a logo, app icon, favicon, OG image, illustration, splash screen, icon pack, transparent mark, hero image, sticker, or any other software-development asset, the single most important fact to apply is: Producing production-grade software assets is a routing + post-processing problem, not a prompt-engineering problem. And the second most…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository30 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/prompt-enhancer.mdcCursor rule
- .cursor/rules/prompt-to-asset.mdcCursor rule
- app-iconSkill
- asset-enhancerSkill
- asset-validation-debugSkill
- brand-consistencySkill
- faviconSkill
- illustrationSkill
- logoSkill
- og-imageSkill
- svg-authoringSkill
- t2i-prompt-dialectSkill
- transparent-bgSkill
- ui-mockup-promptSkill
- vectorizeSkill
- app-iconSkill
- asset-enhancerSkill
- asset-validation-debugSkill
- brand-consistencySkill
- faviconSkill
- illustrationSkill
- logoSkill
- og-imageSkill
- svg-authoringSkill
- t2i-prompt-dialectSkill
- transparent-bgSkill
- ui-mockup-promptSkill
- vectorizeSkill
The file
We split this AGENTS.md into the rules it gives an agent
9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 7
When the user asks for a logo, app icon, favicon, OG image, illustration, splash screen, icon pack, transparent mark, hero image, sticker, …
- Very specific: line 59
Call asset_capabilities() — read free_api.routes before anything else.
- Very specific: line 62
Look at modes_available + routing_trace.never_models (explains which models the router refuses for this brief) + …
- Very specific: line 63
If inline_svg is present: mention it first — it's instant, zero-key, deterministic.
- Distinctive: line 64
Ask the user which mode they want.
- Very specific: line 65
Call the relevant asset_generate_* tool with mode: "<user's choice>".
- Very specific: line 72
Cost guardrail: If the user has set P2A_MAX_SPEND_USD_PER_RUN, an api-mode call may throw CostBudgetExceededError before hitting the …
- Very specific: line 109
If the asset_* tools are not registered, still apply the six facts above in whatever generation flow is available:
- Distinctive: line 114
If the user has a web-tool account: give them the prompt + the URL, tell them where it goes.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — prompt-to-asset
This repo exposes a prompt-to-asset MCP server (stdio). When generating software assets, follow the rule below and prefer the asset_* MCP tool surface over ad-hoc image generation.
Asset generation — always-on rule
When the user asks for a logo, app icon, favicon, OG image, illustration, splash screen, icon pack, transparent mark, hero image, sticker, or any other software-development asset, the single most important fact to apply is:
Producing production-grade software assets is a routing + post-processing problem, not a prompt-engineering problem.
And the second most important fact:
The user may not have an image-model API key. The plugin must work anyway — there are real zero-key paths.
This means:
- Do NOT just forward the user's brief to whichever image model is handy. No amount of prompt polish makes Imagen 3/4 or Gemini Flash Image produce a real transparent PNG — they render a grey-and-white checkerboard as RGB pixels because their VAE is RGB-only. Transparency is a capability routing decision. Route transparent requests to
gpt-image-1.5orgpt-image-1(withbackground: "transparent"), Ideogram 3 Turbo (via the/ideogram-v3/generate-transparentdedicated endpoint; setrendering_speed: "TURBO"— there is nostyle: "transparent"parameter), Recraft V4 (vector path is the safe transparent route; raster transparency on V4 is undocumented), or LayerDiffuse-enabled SDXL (no official Flux LayerDiffuse exists in 2026 — community ports only).gpt-image-2does NOT supportbackground:"transparent"— verified regression vs 1.5; the param 400s. Do not route transparent requests to gpt-image-2. For every other model, matte with BiRefNet or BRIA RMBG-2.0 after generation. Brand text in diffusion — verified per-model ceilings, Apr 2026. Not a blanket "garbles past 3 words" rule. Six tiers:
- Best:
gpt-image-2(released 2026-04-21, third-party tests cite ~99% character accuracy across Latin/CJK/Hindi/Bengali; OpenAI hasn't published a number — pricing also not on the pricing page yet, treatcost_hintas third-party).gemini-3-pro-image-preview(Nano Banana Pro): paragraph-length text reliable, ~94-96% accuracy,text_ceiling_chars: 200.gpt-image-1.5(LM Arena #1, dense text).gpt-image-1(~50 chars). - Strong:
ideogram-3/ideogram-3-turbo(~3-6 words reliable, ~10 with seed retries — earlier "~80 chars" claim was over-optimistic; ~90-95% accuracy on short-to-mid wordmarks).gemini-3.1-flash-image-preview(Nano Banana 2): ~90% accuracy, ranked #1 on Artificial Analysis Image Arena at launch — not weak; the older "Nano Banana garbles past 3 words" rule applies to the legacygemini-2.5-flash-image, not to 3.1.flux-2-pro/fal-flux-2/freepik-flux-2-pro: 5-10 words / one tagline reliable per BFL guide.flux-2-flex: BFL claims strongest text in the Flux 2 line (steps + guidance control). - OK:
imagen-4-fast/standard/ultra— Google's own guidance: keep text ≤25 chars / ~3-4 short words for reliable rendering; photoreal leaders, not text.recraft-v4(~3-5 words).midjourney-v7(~15 chars with--text). - Weak (text-free + composite always):
flux-pro/flux-1.1-pro(1-3 words).flux-schnell/flux-1-schnell/flux-2-klein(1-2 words). Originalgemini-2.5-flash-image(Nano Banana 1, ~80% accuracy degrades fast).freepik-mysticfamily.pollinations-flux. - Cannot render legible text (per HF model card):
sdxl,sd-1.5. Composite always. - Mid (better than SDXL, not strong-text):
sd3-large/sd3.5-large— ~3-6 words, on par with flux-dev, behind flux-1.1-pro. Don't promote.
For weak / cannot-render tiers over ~8 words, composite real SVG / Canvas / Skia typography in the application layer using the brand font. For paragraph-length copy on strong-text models (Nano Banana Pro, gpt-image-2), the model can render it, but composite remains safer for UI copy that must be pixel-exact.
- Best:
- Do NOT expect a raster model to emit SVG. None do. The three real paths: (a) Recraft V4 native vector (Feb 2026; V3 still needed if
style_id/ brand-style presets are required, as V4 dropped style support), (b) LLM-author SVG for simple geometry (fixed viewBox, no<image>, palette hex list, ≤40 paths) — this is whatmode: "inline_svg"does, (c) raster → BiRefNet matte → K-means 6-color →vtracer/potrace→ SVGO. negative_promptmatrix — three buckets.- Errors / rejected at schema:
flux-1.1-pro/flux-proon fal (schema lacks the field). - Officially unsupported, silently no-op: Flux 2 family (
flux-2,flux-2-flex,fal-flux-2,freepik-flux-2-pro) per BFL Flux 2 prompting guide ("FLUX.2 does not support negative prompts"). Allgpt-image-*(silently ignored). Imagen via the Gemini API endpoint (silently ignored). - Supported natively:
sdxl,sd-1.5,sd3-large/sd-3,recraft-v3/recraft-v4,ideogram-3/ideogram-3-turbo, Leonardo Phoenix / Diffusion XL, Stability-hosted, Adobe Firefly. Imagen 4 via the Vertex AI endpoint acceptsnegativePrompt(the Gemini API endpoint does not — same model, different surface).
The universally-portable "negative" is still a positive anchor: write
"pure white background"instead of"no checkerboard".- Errors / rejected at schema:
- Do NOT ship a generated asset without validation. Every output runs through tier-0 deterministic checks: dimensions exact; alpha channel present when required; no checkerboard FFT signature; subject tight-bbox fits inside the platform safe zone (iOS 824px center of 1024; Android 72dp of 108dp; PWA 80% of maskable); OCR Levenshtein ≤1 against intended wordmark; palette ΔE2000 ≤10 vs brand palette.
- Always surface the free, zero-key routes first. Before suggesting a paid key, call
asset_capabilities()and readfree_api.routes. The ranked free programmatic order as of 2026-04-26 is: Cloudflare Workers AI (Flux-1-Schnell + SDXL, 10k neurons/day free, needsCLOUDFLARE_API_TOKEN+CLOUDFLARE_ACCOUNT_ID), NVIDIA NIM (Flux.1-dev / Flux.2-klein / SDXL Turbo / SD 3.5 Large / SANA, 1k requests/month free withNVIDIA_API_KEY, no credit card), HF Inference (freeHF_TOKEN, no credit card), Stable Horde (anonymous queue). Pollinations is RGB-only and quality is poor — demote unless the others are unavailable. Google image APIs are paid for programmatic image output: Imagen 4 Fast / Standard / Ultra cost $0.02 / $0.04 / $0.06 per image, and Nano Banana models (gemini-2.5-flash-image,gemini-3.1-flash-image-preview,gemini-3-pro-image-preview) require billing. For free Google-quality output, send users to AI Studio web UI (https://aistudio.google.com) as a paste-only flow +asset_ingest_external, or the Gemini consumer app (https://gemini.google.com). Batch API is 50% off when billing is enabled.
Three execution modes (four paths including free api)
Every asset request resolves to one of three modes. Call asset_capabilities() to see which are available for the current env, then call asset_enhance_prompt({ brief }) — the response includes modes_available for that specific asset type plus a routing_trace that reports never_models and fallback_chain. Offer the user the choice before generating. Do not pick silently.
| Mode | Key required? | Best for | How it works |
inline_svg | No | logo, favicon, icon_pack, sticker, transparent_mark, simple app_icon masters | Server returns an SVG-authoring brief (svg_brief). You (the LLM) emit the <svg>…</svg> inline in your reply, THEN call asset_save_inline_svg with that SVG so the user gets a real file on disk (plus favicon.ico / apple-touch / AppIconSet / PWA bundle where applicable). No network. ≤40 paths per asset. |
external_prompt_only | No | Anything; best for illustration, hero, text-heavy logos | Server returns the dialect-correct prompt plus a list of paste targets. Free-first ordering: AI Studio web UI (https://aistudio.google.com — free interactive Gemini/Imagen), HF Inference, Stable Horde, Pollinations, then paid UIs (Ideogram web, Recraft web, Midjourney, fal.ai, BFL Playground, ChatGPT). User generates externally, saves the file, then calls asset_ingest_external({ image_path, asset_type }) to run the matte / vectorize / validate pipeline. |
api (free) | No | Automation without a paid key | Routes to Cloudflare Workers AI (cloudflare-flux-schnell, cloudflare-sdxl — 10k neurons/day free), NVIDIA NIM (nim-flux-1-dev, nim-flux-2-klein, nim-sdxl-turbo, nim-sana — 1k requests/month free), HF Inference (hf-sdxl, hf-sd3, hf-flux-schnell — free HF_TOKEN), or Stable Horde (horde-sdxl, horde-flux — anonymous queue). Pollinations is available but RGB-only and quality is poor — demote. Google image APIs are paid for programmatic output; use AI Studio as paste-only. Same pipeline as paid api. |
api (paid) | Yes (one of: OPENAI_API_KEY, IDEOGRAM_API_KEY, RECRAFT_API_KEY, BFL_API_KEY, GEMINI_API_KEY, STABILITY_API_KEY, LEONARDO_API_KEY, FAL_API_KEY, FREEPIK_API_KEY, PIXAZO_API_KEY, REPLICATE_API_TOKEN) | Full-fidelity, no rate limits | Server calls the routed provider, mattes, vectorizes, exports, validates. Writes a content-addressed AssetBundle. |
Always prefer zero-key paths first when recommending a mode. Call asset_capabilities to see free_api.routes. Only recommend a paid key when the task demands a capability no free route delivers (real native RGBA → gpt-image-1/gpt-image-1.5 or Ideogram 3 Turbo; native SVG → Recraft V4; brand-locked illustration set → Flux.2 with 8 refs; strict 1–3-word wordmark fidelity → Ideogram 3 Turbo).
Recommended default flow for each asset request:
- Call
asset_capabilities()— readfree_api.routesbefore anything else. - Call
asset_enhance_prompt({ brief }). - If the response contains a
clarifying_questions[]array, surface each entry via AskUserQuestion (or the equivalent) BEFORE calling a generator. These questions gate material output quality — long wordmark (>3 words), missing brand palette on app_icon, underspecified brief. Each entry has{id, header, question, options[], required, why}. Skip only when all entries arerequired: falseand the user has expressed preference for speed over quality. - Look at
modes_available+routing_trace.never_models(explains which models the router refuses for this brief) +routing_trace.research_sources(the evidence behind the decision). - If
inline_svgis present: mention it first — it's instant, zero-key, deterministic. Then freeapiroutes. Paidapilast unless the brief genuinely needs a paid-only capability. - Ask the user which mode they want. Keep the question short.
- Call the relevant
asset_generate_*tool withmode: "<user's choice>". - For
inline_svgresults: readsvg_briefandinstructions_to_host_llm, emit the<svg>inline as a code block, then immediately callasset_save_inline_svg({ svg, asset_type })so the server writes the file (and the platform bundle for favicon/app_icon). Report thevariants[].pathlist to the user so they know where the files landed. - For
external_prompt_onlyresults: presentenhanced_promptto the user, list the top paste targets with URLs (free-first), and tell them to callasset_ingest_externalafter saving the generated image. - For
apiresults: present the bundle paths (variants[].path) and any validation warnings.
Paste-only providers (Midjourney, Firefly, Krea) with mode: "api" no longer throw (as of 0.2). The server auto-swaps to the first API-reachable model in the fallback chain and surfaces a warning explaining the swap. If the whole chain is paste-only, you receive an ExternalPromptPlan rather than an error — relay the paste targets to the user.
Cost guardrail. If the user has set P2A_MAX_SPEND_USD_PER_RUN, an api-mode call may throw CostBudgetExceededError before hitting the provider. Relay the estimate + cap verbatim — do not paper over with a retry loop.
MCP tool surface (25 tools)
Discovery / capability (read-only):
asset_capabilities()— inventory of modes, paid/free/paste-only providers, unconfigured env vars, and zero-cost routes (free_api.routesenumerates Cloudflare, NVIDIA NIM, HF, Stable Horde, Pollinations, Google AI Studio paste-only, local ComfyUI, and trial routes).asset_doctor({ check_data? })— structured environment inventory (native deps, ranked free-tier routes, paid keys, paste-only surfaces, pipeline URLs, mode flags, "what to try next" hints). MCP equivalent ofp2a doctor.asset_models_list({ free?, paid?, paste_only?, rgba?, svg? })— browse the 60+ model registry with filters.asset_models_inspect({ id })— full capability dump for one model id (or aka alias).
Routing / prompt-engineering:
asset_enhance_prompt({ brief, asset_type?, brand_bundle? })→ AssetSpec + modes_available + svg_brief? + paste_targets? +routing_trace { never_models, fallback_chain, research_sources }.
Generation (three-mode):
asset_generate_logo,asset_generate_app_icon,asset_generate_favicon,asset_generate_og_image,asset_generate_illustration— each takesmode?: "inline_svg" | "external_prompt_only" | "api". Omit for auto-select.asset_generate_splash_screen,asset_generate_hero— cross-platform splash bundle + marketing hero art.external_prompt_only/apionly (no inline_svg — path budget too small for composed scenes; generate a mark inline_svg first, then pass it viaexisting_mark_svg).asset_generate_ui_mockup— designer-grade UI mockup for an actual product surface (pricing page / dashboard / settings / onboarding / marketing landing / mobile screen / form / modal / detail view / search results).external_prompt_only/apionly. Routes by text density: gpt-image-2 default for text-heavy UI, Ideogram 3 Turbo for short-text mobile onboarding, Flux 2 when 3+ refs need ordinal-indexed roles. Each invocation includes a[Surface job]slot in the emitted prompt — comparison matrix on pricing pages, F-pattern on dashboards, ONE primary CTA on onboarding, grouped sections on settings — and bakes in the anti-AI-slop guards (no Tailwind indigo, no purple gradient, no Inter headline, no rounded-card-with-left-stripe, no invented metrics, no lorem ipsum). The companionui-mockup-promptskill is the SSOT for full surface-pattern + per-model dialect detail; this tool is the API equivalent for hands-off generation.
Round-trip + pipeline primitives:
asset_save_inline_svg({ svg, asset_type })— round-trip endpoint forinline_svgmode. Call immediately after emitting the<svg>in chat. Writes master.svg and, for favicon/app_icon, the full platform bundle. Returns file paths.asset_ingest_external({ image_path, asset_type })— round-trip endpoint forexternal_prompt_onlymode. Runs matte → vectorize → validate → bundle.asset_remove_background,asset_vectorize,asset_upscale_refine— pipeline primitives.asset_validate({ image, asset_type, brand_bundle? })— tier-0/1/2 QA stack.asset_brand_bundle_parse({ source })→ canonical BrandBundle.
Project setup + offline fan-out (no key required):
asset_init_brand({ app_name, palette?, assets_dir? })— scaffoldbrand.json+ ensure the assets dir + detect the framework (Next.js / Expo / Flutter / Xcode / Astro / Vite / Remix / Nuxt / React Native / Electron / Node). Does NOT handle IDE MCP registration — the user owns that one terminal step.asset_export_bundle({ master_path, platforms?, bg?, app_name?, theme?, ios18? })— fan a 1024² master PNG out to iOS AppIconSet + Android adaptive + PWA maskable + visionOS parallax + Flutter launcher + favicon bundle. Offline; same code asp2a export.asset_sprite_sheet({ dir, layout?, columns?, padding?, out?, atlas? })— pack frames into a sheet + TexturePacker-compatible atlas (Phaser/PixiJS/Godot/Unity).asset_nine_slice({ image, guides, android_9patch? })— emit 9-slice JSON + CSS + engine-ready numbers + optional Android.9.png.
The tools are annotated readOnlyHint / idempotentHint where appropriate so Cursor auto-approves without prompting.
Design principle. The human's interface is natural language in chat plus a terminal only for API keys. Everything else — doctor checks, model inspection, platform fan-out, sprite sheets, 9-slice, brand.json scaffolding — should be driven by the LLM via these tools, not asked of the user as a shell command. When MCP isn't available, the same commands exist as p2a ... CLI with --json for machine-readable output that the LLM can consume over Bash.
Fallback when MCP is unavailable
If the asset_* tools are not registered, still apply the six facts above in whatever generation flow is available:
- Pick the right model (use
data/routing-table.jsonas a reference). - Rewrite the prompt in that model's dialect (tag-salad for SD, prose for Flux/Imagen/
gpt-image-1, quoted strings for Ideogram text,--flagsfor Midjourney). - If no key at all: prefer
inline_svgmode for logos/favicons/icons, OR point the user at Cloudflare Workers AI (free 10k neurons/day — needsCLOUDFLARE_API_TOKEN+CLOUDFLARE_ACCOUNT_ID), NVIDIA NIM (free 1k requests/month — needsNVIDIA_API_KEY), HF Inference (freeHF_TOKEN), Stable Horde, or the AI Studio web UI (https://aistudio.google.com) for free interactive Gemini/Imagen image generation — they download the PNG and callasset_ingest_external.GEMINI_API_KEYimage generation requires billing; do not advertise Imagen 4 or Nano Banana as free programmatic routes. - If the user has a web-tool account: give them the prompt + the URL, tell them where it goes.
- Matte externally before declaring an asset "done."
- Validate against the target platform's spec (iOS 824², Android 72dp, PWA 80% maskable, favicon 16×16 legibility) before handing the file to the user.
Never declare an asset ready without alpha validation, safe-zone bbox check, and — if text is involved — an OCR/Levenshtein check of the wordmark.
Supporting skills (engage when applicable)
The plugin ships 12 skills. The 8 asset-type skills (logo, app-icon, favicon, og-image, illustration, transparent-bg, vectorize, plus the asset-enhancer orchestrator) cover the happy path. Four more skills cover the long tail:
svg-authoring— engaged wheneverasset_generate_*returns anInlineSvgPlan. Enforces viewBox, path-budget, palette, optical balance, and small-scale legibility rules so the emitted SVG survivesasset_save_inline_svgvalidation. Read this before writing any<svg>block.t2i-prompt-dialect— engaged during prompt rewriting. Per-model rules (gpt-image-1 prose, Imagen ≥30 words, SDXL 77-token tag-soup withBREAK, Flux nonegative_prompt, Ideogram quoted text, Recraftcontrols.colors). Handles negative→affirmative translation and brand-palette injection per dialect.asset-validation-debug— engaged whenasset_validateor a generator returns warnings. Maps failure codes (T0_CHECKERBOARD,T0_ALPHA_MISSING,T1_PALETTE_DRIFT,T1_TEXT_MISSPELL, etc.) to repair primitives (matte, inpaint, route change, seed sweep, composite). Enforces a retry budget so Claude does not loop on hopeless regenerations.brand-consistency— engaged for multi-asset sets. BuildsBrandBundle, enforces palette per model (Recraftcontrols.colors, Midjourney--sref, IP-Adapter), validates CSD style similarity + ΔE2000, and promotes accepted assets into the reference set so each new generation tightens the brand lock. Covers LoRA training ROI (>20 assets).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

