# How the Template Engine in awesome-gpt-image-2 Works: A Deep Dive

> Discover how the awesome-gpt-image-2 template engine transforms markdown prompt recipes into plain text or JSON. Understand its regex placeholder substitution for efficient prompt generation.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: deep-dive
- Published: 2026-09-10

---

**The template engine in awesome-gpt-image-2 is a lightweight, markdown-driven system that converts human-readable prompt recipes stored in [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) into ready-to-use plain-text strings or structured JSON objects through regex-based placeholder substitution.**

The repository provides a complete pipeline for managing GPT-4o image generation prompts. Understanding how the template engine in awesome-gpt-image-2 works reveals a three-layer architecture that bridges human-readable documentation and machine-consumable agent skills.

## How the Template Engine Works

The engine operates through a clear separation of concerns: human writers maintain prompts in markdown, a Node.js parser handles variable injection, and a JSON library distributes the final templates to AI agents.

### Source Templates in docs/templates.md

All prompt recipes originate in **[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)**. This single source of truth uses markdown headers as anchors to organize templates by category.

Each section follows a strict naming convention with anchors like `#tpl-ui` or `#tpl-infographic`. Within these sections, templates exist in two formats:

- **Plain-text templates** containing placeholder tokens inside square brackets—e.g., `为[产品类型]生成一张[平台]界面图。`
- **JSON "advanced" templates** designed for automated agents, containing structured fields like `type`, `platform`, `layout`, and `style`

This dual-format approach allows both manual copy-paste workflows and programmatic agent consumption from the same source file.

### Parsing and Variable Substitution

The transformation logic lives in **`scripts/generate-style-skill.mjs`**. This script reads [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md), extracts sections using the anchor headers, and builds a mapping of template names to template strings.

The engine identifies placeholder tokens using the regular expression `\[(.+?)\]`. When processing a request, it performs simple string replacement:

- For plain-text templates, it substitutes every bracketed token with the corresponding value from the request object
- For JSON templates, it injects supplied values into specific JSON fields while preserving the overall schema structure

This parsing step converts the static markdown documentation into a dynamic, programmable interface.

### Export as an Agent Skill

Processed templates compile into **[`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json)**, a compact JSON representation mapping categories to template lists. The `generate-style-skill.mjs` script then bundles this JSON with a runtime shim and publishes the **`gpt-image-2-style-library`** npm package.

The published skill exposes a simple API for AI agents. According to the documentation in **[`agents/skills/gpt-image-2-style-library/SKILL.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md)**, integration works as follows:

```typescript
import { getTemplate } from "gpt-image-2-style-library";

const prompt = getTemplate("ui", { 
  product: "Fitness App", 
  platform: "iOS" 
});

```

This allows installation in Claude Code, Cursor, or any AI-agent framework that supports npm packages.

## Working with Templates: Code Examples

### Plain-Text Usage

Fill a UI template manually by passing an object with keys matching the bracketed placeholders:

```javascript
// Assume `engine` is the exported parser
const template = engine.getPlainTemplate('tpl-ui');
const result = engine.fill(template, {
  产品类型: '健身应用',
  平台: 'iOS',
  功能点A: '计步',
  功能点B: '卡路里跟踪',
  颜色: '蓝色',
});

console.log(result);
// Output: 为健身应用生成一张iOS界面图。
//   核心功能：计步、卡路里跟踪。
//   视觉风格：极简，主色蓝色，...

```

### JSON Usage for Agents

Retrieve a ready-to-send JSON payload structured for automated image generation:

```javascript
import { getJSONTemplate } from "gpt-image-2-style-library";

const uiPrompt = getJSONTemplate('tpl-ui', {
  type: "UI Screenshot",
  platform: "iOS",
  product: "Fitness App",
  layout: "Card-based feed with bottom tab bar",
  style: { 
    theme: "Dark Mode", 
    primary_color: "Neon Green", 
    typography: "Clean sans-serif" 
  },
  content: {
    header: "Today's Activity",
    cards: [{ title: "Running", data: "5.2 km", button: "Start" }]
  },
  constraints: "High fidelity, readable text, 9:16 aspect ratio"
});

console.log(JSON.stringify(uiPrompt, null, 2));

```

### Generating the Skill Package

Build and install the npm package locally using the generator script:

```bash

# Build the npm package containing the full style library

node scripts/generate-style-skill.mjs

# Install it globally (or locally) for an agent

npm install -g gpt-image-2-style-library

# Then use it inside a Claude Code or Cursor session

```

## Key Files and Architecture

| File | Role |
|------|------|
| **[`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md)** | Human-written source of truth containing both plain-text and JSON templates organized by anchor headers. |
| **`scripts/generate-style-skill.mjs`** | Parser that scans templates, replaces placeholders using `\[(.+?)\]`, and builds the distribution files. |
| **[`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json)** | Compiled, machine-readable library output that agents consume at runtime. |
| **[`agents/skills/gpt-image-2-style-library/SKILL.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/agents/skills/gpt-image-2-style-library/SKILL.md)** | API documentation and integration guide for the published npm skill. |
| **[`package.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/package.json)** | Defines the `gpt-image-2-style-library` package metadata and entry points for npm distribution. |

## Summary

- The **template engine in awesome-gpt-image-2** transforms markdown documentation into executable prompt generators through a three-stage pipeline.
- **Source control** happens in [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md), using bracketed placeholders like `[产品类型]` for variable substitution.
- **Parsing logic** in `scripts/generate-style-skill.mjs` uses the regex `\[(.+?)\]` to identify and replace tokens with runtime values.
- **Distribution** occurs through [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) and the `gpt-image-2-style-library` npm package, enabling agent frameworks to consume templates programmatically.
- The system supports both **human-friendly plain-text** workflows and **structured JSON** outputs for automated image generation pipelines.

## Frequently Asked Questions

### How does the template engine handle variable substitution?

The engine scans template strings using the regular expression `\[(.+?)\]` to identify placeholder tokens enclosed in square brackets. When `engine.fill()` or `getTemplate()` is called, it performs a direct key-value replacement, substituting each bracketed token with the corresponding value from the provided options object.

### What is the difference between plain-text and JSON templates in the repository?

Plain-text templates produce human-readable prompt strings suitable for direct copying into ChatGPT or similar interfaces—they contain bracketed placeholders like `[平台]` that get replaced with simple string values. JSON templates return structured objects with nested fields for `style`, `content`, and `constraints`, designed specifically for programmatic consumption by AI agents and automated workflows.

### Where does the compiled template library get stored after processing?

After `scripts/generate-style-skill.mjs` runs, the compiled templates are stored in **[`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json)**. This file serves as the bundled artifact that gets packaged into the `gpt-image-2-style-library` npm module, allowing agents to import templates without parsing raw markdown at runtime.

### Can I use the template engine outside of Claude Code or Cursor?

Yes. Because the system publishes a standard npm package (`gpt-image-2-style-library`), you can install it in any Node.js environment. The package exports functions like `getTemplate()` and `getJSONTemplate()` that work in standard JavaScript runtimes, CI/CD pipelines, or custom agent frameworks, provided you have the [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) available or install the published package.