gmchocolate/poster-genome

Poster Genome · Reference-First Creation

Goal: Learn the works users truly like, and let those real visual references participate in the next creation.

The design genome is a transferable design decision; the user's private Taste Library is a collection of reference posters that can be reopened, observed, and used for image creation. A textual description of the genome cannot replace the actual reference image. Both must work together.

This is a behavioral instruction for the Agent, not a standalone image generation software. All relative script paths start from the skill directory where this SKILL.md is located. After installation, user data is stored in ~/.poster-genome on the running machine, not in the skill folder or a public GitHub repository.

1. Identify the User's Mode

What the user says	Mode	What to deliver
"Learn this poster" "Why is it good"	LEARN	Visible evidence, design inferences, transferable rules, applicable conditions & counterexamples
"I like this, save it to my style library"	LEARN → LIBRARY	First analyze liked/disliked details from the image, then save the real image + preference record to the user's local storage
"Make a poster from these photos in my favorite style"	CREATE	Retrieve relevant reference images, attach real images, create, and verify
"This layout is too rigid" "Don't change the person"	REFINE	Compare against reference images, accurately point out defects, preserve user materials, and make targeted modifications
"Organize/delete/rate reference images"	LIBRARY	Only modify the local image library or public genomes under explicit user authorization

If the user has already provided images, purpose, and copy, do not ask again. Ask at most three truly impactful questions per round; allow the user to say "You decide the rest."

2. Highest Priority Constraints

1. Real visual references first. For creation, prioritize retrieving 1–3 real images from the private image library. Metadata or genome JSON alone is insufficient to claim "reference-driven" creation.
2. Clearly distinguish the role of the two image types. User-uploaded content images are responsible for the subject's identity, quantity, clothing, objects, brand, and facts; liked posters serve as style references, responsible only for fonts, colors, layout rhythm, and atmosphere. Do not merge them into a single image.
3. Actually pass in images. A path string, prompt, or summary does not automatically send the image to an image model. The file content must be transmitted through the host's actually supported image reading/attaching interface; if not supported, explain honestly, do not pretend the image has been referenced.
4. Fidelity before aesthetics. Preserve the user-specified faces, pets, products, accurate text, and quantities; do not omit a single baby, or fabricate dates, weather, camera parameters, credits, discounts, or endorsements.
5. Learn the method, don't copy the work. Do not reconstruct the entire unique layout, trademarks, and original copy of a third-party work. Do not use unauthorized materials.
6. Local saving requires authorization. The user uploading a reference poster for viewing does not equal permission for permanent storage. Only write to the local environment when the user explicitly requests "add to style library/save as reference" or agrees. Do not upload to GitHub, cloud drives, or other servers without consent.
7. Distinguish observation, inference, and unknowns. Visual effect interpretation is not the designer's intent. Do not guess at unidentifiable specific fonts, original authors, parameters, or rights.
8. Tool capabilities must be honest. Without visual tool access, you cannot claim to have seen an image. Without image generation tools, you cannot claim to have completed an image. Without access to local files, you cannot claim to have read or saved an image library on the user's computer.

3. LEARN: Derive Actionable Aesthetic Judgments

Deconstruct following the Poster Analysis Method. The order is:

1. Observe image type, theme, canvas ratio, subject count, background, graphics, copy, brand information. Mark anything unclear.
2. Reconstruct the viewing order: first glance, second glance, final glance. Analyze composition, proportions, font contrast, whitespace, layers, color, and the role of decorative elements.
3. For each conclusion, write clearly: "Visual evidence → possible visual effect → transferable rule → applicable conditions → failure conditions." Avoid just saying "looks premium."
4. If multiple images share a similar style, distill the common skeleton and potential variation branches; do not mechanically add a new genome for each image.
5. Clarify user preferences: what they liked most and what should not be replicated; when the user hasn't specified, the Agent may propose candidates but cannot pretend the user has confirmed a preference.
6. Present candidate genomes and their applicable scenarios. After user agreement, the original image can be saved to the local Taste Library; public genome files can only be submitted to the repository with additional authorization.

Learning and local saving are two distinct actions: analysis does not automatically mean saving.

4. LIBRARY: Accumulate Each User's Independent Visual Taste

The preferred operation is "add visual references to the user's personal reference image library," not saving user photos to a public repository. See Personal Taste Library.

The local CLI should be run from the skill directory. First-time use requires Pillow:

python -m pip install -r requirements-library.txt
python scripts/taste_library.py add \
  --image "/path/to/reference.jpg" \
  --title "My favorite photography journal style" \
  --genome playful-sky-editorial \
  --tag everyday \
  --like "Bold heading alternating with light handwritten text" \
  --avoid "Original author's brand logo and fictional dates" \
  --rating 5

It saves a metadata-cleaned copy of the image and aesthetic record to ~/.poster-genome, without automatically uploading to the internet. Supports list, select, feedback, remove, and prepare.

Do not save source photos to the public skills/poster-genome/ directory. Local saving and cloud generation have different permissions; user authorization for local saving does not imply the images can be sent to a remote generation service without disclosure.

When the Agent runs in the cloud and cannot access the user's machine, the user must provide images to an Agent-accessible workspace, or use private persistent storage with user consent. Do not refer to the cloud workspace as the user's local folder.

Public genomes remain in genomes/ and must conform to schemas/genome.schema.json; new styles should be compared against existing genomes first, avoiding redundant categories. Genomes that have not passed tests may be kept as drafts.

5. CREATE: Make a New Poster with Real Style Reference Images

See the full workflow in Reference-First Creation Workflow and Poster Creation Guide.

1. Understand the current materials. Count the user's source images and subjects in each image. List faces, clothing, photo count, text, and dimensions that cannot be changed. Two photos of babies must both appear unless the user explicitly allows one to be omitted.
2. Find real reference images. Read the user's local image library, select 1–3 images by style genome, material tags, user rating, and liked_for. Actually open the images to judge layout relationships. Prioritize references explicitly specified by the user.
3. No reference image? Be honest. By default, ask the user if they want to add a liked poster, or allow "original attempt without visual reference." Do not substitute textual rules for real visual images.
4. A generation list is not a poster. The CLI can separate user images and style reference images into different roles, outputting clear local file paths:

python scripts/taste_library.py prepare \
  --source "/path/to/user-photo-a.jpg" \
  --source "/path/to/user-photo-b.jpg" \
  --genome playful-sky-editorial \
  --tag portrait \
  --headline "Twin Adventure Diary" \
  --top 2

5. Actually pass the reference and source images to the image tool. Call a multimodal creation/editing tool that supports image input, using the selected reference images as style references and user source photos as content sources. Placing only absolute paths in the prompt does not count as completing the input; confirm the tool can actually receive them. Calling remote services with user-sensitive images must comply with user permissions and service privacy requirements.
6. Separate design and fidelity. Learn fonts, color blocks, edge decorations, and spatial rhythm from the reference, not copying the original work. For critical accuracy requirements (faces, brands, numbers, Chinese text), prioritize creating backgrounds/graphics with the tool, then use controlled editing to composite real photos and text. Do not regenerate the user's baby's face for visual effect.
7. Check the output. Verify that all required subjects from the content image are present, text is accurate, the layout inherits the liked visual characteristics, and no fictional shooting parameters are present. Even if the style meets standards but a subject is missing, it is still an unqualified result.
8. Feedback improves Taste. After user feedback, suggest saving preferences; only write to the local library via feedback with user consent; do not record secretly.

The matching script scripts/match_genomes.py can only do metadata heuristic ranking; it cannot replace visual reference retrieval. The reference library CLI's select is also not a visual vector search: the Agent should actually look at the images before determining the style.

6. REFINE: Move Modifications Toward the User's Preferred Reference

• Simultaneously compare the user's original materials, the user-specified reference images, and the generated output. Prioritize pointing out 1–3 obvious defects.
• Separate errors (typos, missing people, distorted faces, fabricated data) from aesthetic differences (fonts lacking dynamism, elements too rigid).
• When making targeted modifications, write clearly: "what to borrow / what not to copy / what original content must not be changed."
• If an image editing tool is available, actually use it to edit. If re-generation is required and risks damaging faces, prioritize controlled compositing.
• Do not create private profiles without user authorization to save results or preferences.

7. Failure Branches and Boundaries

• Local library empty: Ask the user to add a reference or authorize a reference-free original attempt; do not falsely claim "style comes from reference images."
• Only JSON, no images: A design plan can be proposed, but it must be marked as "based on text genome," not image-conditioned generation.
• Reference found but host cannot read it: Do not treat the file path as an image; explain the tool limitation and ask the user to attach the image or switch tools.
• User requires precise preservation of two people: Do not generate only one; if it fails, continue fixing or be transparent.
• No factual source: Do not invent specific dates, temperatures, camera parameters, credits, barcode meanings.
• Private photos or third-party works: Do not default to public sharing, syncing, or uploading.
• The current output is already satisfactory: Allow suggesting to keep it as-is; do not force a re-layout.

Read As Needed

• Reference-First Creation Workflow — The full process of actually using images for generation and fidelity
• Personal Taste Library — Local library CLI, authorization, privacy, feedback
• Poster Analysis Method — Boundary between observation and inference
• Design Genome Selection and Management — Selection, merging, and versioning of general rules
• Interaction Protocol — Ask fewer, more critical questions
• Poster Creation Guide — Canvas, layers, text, and output
• Poster Quality Rubric — Check fidelity first, then aesthetics
• Rights and Provenance — Personal storage and third-party copyright

This project does not include its own vision model, AI image generation model, or cloud image library synchronization service in any environment.