How to Integrate Custom Prompt Templates with the Awesome-GPT-Image-2 System

To integrate custom prompt templates, add an anchored markdown section to docs/templates.md, register the metadata in data/style-library.json, place a cover image in data/images/, and run scripts/generate-style-skill.mjs to validate the integration and regenerate the reference documentation.

The Awesome-GPT-Image-2 repository separates human-readable prompt definitions from structured machine metadata. This two-file architecture enables automated validation through scripts/generate-style-skill.mjs, ensuring that every template ID maps to valid content and that documentation stays synchronized with the data model.

Understanding the Two-Component Architecture

The template system relies on two tightly-coupled sources of truth:

• docs/templates.md – Contains the full prompt text, usage examples, and "avoid-pitfalls" sections, each marked with an HTML anchor like <a name="tpl-custom"></a>.
• data/style-library.json – Stores the machine-readable index with IDs, categories, style tags, scene tags, cover image paths, and the anchor reference that links back to the markdown file.

During the build process, scripts/generate-style-skill.mjs reads the JSON file, verifies that every anchor exists in the markdown, checks that cover images are present, and enforces uniqueness constraints on IDs and tags. It then renders the final reference file at agents/skills/gpt-image-2-style-library/references/style-library.md.

Step-by-Step Workflow to Integrate Custom Prompt Templates

Step 1: Create the Markdown Section in docs/templates.md

Add a new anchored section to docs/templates.md. The anchor name must exactly match the value you will specify in the JSON entry.

<a name="tpl-custom"></a>

### 🧩 Custom UI Prompt

```text
为[产品类型]生成一张[平台]界面图，包含[功能点]，颜色使用[主色]，比例[9:16]。

Avoid pitfalls

• Never leave the platform unspecified.
• Always lock the aspect-ratio.

Step 2: Register the Template in data/style-library.json

Insert a new object into the templates array in data/style-library.json:

{
  "id": "custom-ui-01",
  "title": { "en": "Custom UI Prompt", "zh": "自定义 UI 提示词" },
  "anchor": "tpl-custom",
  "cover": "/images/custom-ui.png",
  "category": "ui",
  "styles": ["realistic", "minimal"],
  "scenes": ["commerce"],
  "tags": ["ui", "custom"],
  "exampleCases": [999],
  "useWhen": {
    "en": "When the user wants a specialised UI mock-up that isn’t covered by the built-in UI templates.",
    "zh": "当用户需要一种不在现有 UI 模板中的专属 UI 设计时。"
  },
  "guidance": {
    "en": ["Specify platform, layout and colour palette.", "Lock aspect ratio."],
    "zh": ["明确平台、布局和配色。", "固定比例。"]
  },
  "pitfalls": {
    "en": ["Leaving platform vague will cause the model to output a generic screenshot."],
    "zh": ["平台描述不明确会导致生成通用截图。"]
  }
}

Step 3: Provide the Cover Image

Place the image file in data/images/:

data/images/custom-ui.png

The validator checks file existence using existsSync(cover), ensuring every template has a preview asset.

Step 4: Regenerate the Reference File

Execute the build script to validate and update the skill reference:

node scripts/generate-style-skill.mjs

This updates agents/skills/gpt-image-2-style-library/references/style-library.md and fails fast if any validation check does not pass.

Validation Logic in scripts/generate-style-skill.mjs

The build script enforces data integrity through three strict checks:

Anchor Consistency – The script extracts all anchors from docs/templates.md using regex matching and stores them in a Set:

const templateText = readFileSync(templatesFile, 'utf8');
const templateAnchors = new Set(
  [...templateText.matchAll(/<a name="([^"]+)"><\/a>/g)].map(m => m[1])
);
if (!templateAnchors.has(template.anchor)) {
  throw new Error(`template anchor not found in docs/templates.md: ${template.anchor}`);
}

Cover Image Validation – The script verifies that the file referenced by the cover field exists on disk. Missing images cause immediate build failures.

Uniqueness Constraints – The assertUnique function forces template IDs, category values, style values, and scene values to be unique across the entire library, preventing ambiguous lookups when the application selects templates by ID.

Summary

• Integrate custom prompt templates by updating both docs/templates.md and data/style-library.json in tandem.
• Use HTML anchors like <a name="tpl-custom"></a> in markdown to enable cross-referencing from the JSON index.
• Place cover images in data/images/ and reference them with the /images/ path prefix in the JSON cover field.
• Run node scripts/generate-style-skill.mjs to validate anchor existence, image presence, and uniqueness before the changes go live.
• The generated file at agents/skills/gpt-image-2-style-library/references/style-library.md provides the runtime documentation consumed by the skill system.

Frequently Asked Questions

What happens if the anchor in JSON does not match any anchor in the markdown?

The validation script in scripts/generate-style-skill.mjs throws a hard error: template anchor not found in docs/templates.md: ${template.anchor}. This prevents dead links and ensures every JSON entry points to valid content.

Where must cover images be stored for the validation to pass?

Cover images must be placed in the data/images/ directory. The script checks existsSync() against the local file system, and the JSON cover field should use the format /images/filename.png to resolve correctly relative to the data directory.

How does the front-end access the new template after regeneration?

The front-end (such as components in src/image25/App.jsx) looks up templates by id in data/style-library.json. Once validated and regenerated, the new entry appears in the skill reference without requiring additional code changes in the UI layer.

Can I add templates without running the generation script temporarily?

No, the generation step is mandatory. It serves as the validation gate that ensures anchor consistency and image availability. Skipping this step would result in a broken reference file and potential runtime errors when the skill system attempts to resolve template anchors.

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