How the GPT-Image2 Skill Handles Multiple Plausible Template Options

When the GPT-Image2 skill encounters multiple suitable templates, it presents 2-3 candidate options with specific rationales and defers the final selection to the user rather than making an arbitrary choice.

The gpt-image-2-style-library skill in the freestylefly/awesome-gpt-image-2 repository implements a deterministic workflow for resolving ambiguity in template selection. This approach ensures that users maintain creative control while the skill provides structured guidance through its curated style library.

Deterministic Template Matching Hierarchy

The skill follows a strict priority order when evaluating user requests against the template database defined in agents/skills/gpt-image-2-style-library/references/style-library.md.

Category-Based Matching

First, the skill attempts to match the request by template category. This primary filter checks if the user's intent aligns with high-level classifications such as poster layouts, UI dashboards, or product photography styles. The category matching logic evaluates the request against the structured taxonomy defined in data/style-library.json.

Fallback Tag Matching

If category matching yields no single clear result, the skill falls back to visual-style tags and then scene tags. According to agents/skills/gpt-image-2-style-library/SKILL.md (lines 26-27), this secondary analysis examines descriptive attributes like "minimalist," "cyberpunk," or "studio lighting" to narrow the candidate pool. The system cross-references these tags against the auto-generated index in the reference file to identify potentially compatible templates.

Resolving Ambiguity Through User Choice

When the matching algorithm identifies multiple templates with equal relevance scores, the skill explicitly avoids probabilistic selection.

Presenting Candidate Templates

Instead of guessing, the skill presents 2-3 candidate templates, each accompanied by a concise rationale explaining its suitability (SKILL.md, lines 27-28). For example, a request for a product promotion might return:

• poster-layout-system with the reason "强大的版式结构，适合商业海报" (strong layout structure suitable for commercial posters)
• product-commerce-visual with the reason "突出产品细节和包装展示" (highlights product details and packaging display)

The askUserChoice flag is set to true, pausing the workflow until the user selects their preferred direction.

Final Prompt Assembly

After the user selects a template via the finalize() method, the skill constructs the final GPT-Image2 prompt using the selected template name, example case IDs, and standard prompt blocks (SKILL.md, lines 29-35). These blocks include subject definition, composition guidelines, style parameters, text placement rules, aspect ratio constraints, and technical constraints specific to the chosen template.

Code Implementation Examples

The skill exposes a programmatic interface that integrates with agent-based architectures.

JavaScript Integration

Developers interact with the skill through the agent's skill registry:

// Initialize the skill
const skill = await agent.useSkill('gpt-image-2-style-library');

// Request template options
const response = await skill.run({
  request: '生成一个适合产品宣传的海报',
  language: 'zh'  // Language detection is automatic
});

// Response contains multiple options for user selection
{
  options: [
    { id: 'poster-layout-system', reason: '强大的版式结构，适合商业海报' },
    { id: 'product-commerce-visual', reason: '突出产品细节和包装展示' }
  ],
  askUserChoice: true
}

// Finalize after user selection
await skill.finalize({ chosenId: 'poster-layout-system' });

Agent Configuration

The skill is registered declaratively in agents/openai.yaml with explicit instructions for handling ambiguity:

name: gpt-image-2-style-library
description: |
  Choose a GPT-Image2 visual style / template from the style library.
  If several templates are plausible, present 2-3 options with short reasons
  and ask the user to choose before generating the final prompt.

The build script scripts/generate-style-skill.mjs automatically regenerates both SKILL.md and the reference documentation whenever the underlying data/style-library.json is updated, ensuring the selection logic remains synchronized with the latest template definitions.

Summary

• The skill uses a three-tier matching system: template category first, then visual-style tags, then scene tags.
• When faced with multiple plausible matches, the skill explicitly refuses to guess and instead surfaces 2-3 curated options.
• Each candidate includes a specific rationale explaining its relevance to the user's request.
• The workflow pauses for explicit user confirmation via the finalize() method before constructing the final GPT-Image2 prompt.
• All template definitions and matching logic are sourced from data/style-library.json and documented in references/style-library.md.

Frequently Asked Questions

What happens if only one template matches the request?

If the deterministic matching process yields a single clear candidate, the skill bypasses the selection dialog and proceeds directly to final prompt construction using the matched template's specifications.

How does the skill determine which templates are "plausible"?

The skill evaluates templates against the request using weighted criteria defined in the style library schema. A template becomes a candidate when it meets threshold scores for either category alignment, tag intersection, or a combination of both visual-style and scene descriptors.

Can the skill automatically select a template without user input?

No. According to the source code in agents/skills/gpt-image-2-style-library/SKILL.md, when multiple templates are equally suitable, the skill is explicitly configured to set askUserChoice: true and wait for user confirmation. This design prevents arbitrary selections that might not align with the user's specific creative intent.

Where are the template definitions stored?

The canonical template data resides in data/style-library.json, which powers the auto-generated reference file at agents/skills/gpt-image-2-style-library/references/style-library.md. The scripts/generate-style-skill.mjs build script synchronizes these files with the skill's selection logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}