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

> Integrate custom prompt templates with Awesome-GPT-Image-2 by adding markdown, registering metadata, placing images, and running a script. Enhance your image generation workflow today.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: how-to-guide
- Published: 2026-09-11

---

**To integrate custom prompt templates, add an anchored markdown section to [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md), register the metadata in [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md). The anchor name must exactly match the value you will specify in the JSON entry.

```markdown
<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`:

```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:

```bash
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`:

```js
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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) and [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/image25/App.jsx)) looks up templates by `id` in [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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.