# How Agent Reference Markdown Is Generated from the Style Library JSON in Awesome GPT-Image 2

> Discover how agent reference markdown is generated from style library JSON in Awesome GPT-Image 2. Learn about the four-stage pipeline: loading, validation, rendering, and output.

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

---

**The `generate-style-skill.mjs` script transforms [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) into structured agent reference markdown through a four-stage pipeline: JSON loading, data validation, template rendering, and file output.**

The `freestylefly/awesome-gpt-image-2` repository automates documentation synchronization to ensure agent skills always reference current template definitions. This guide explains exactly how the **agent reference markdown is generated from the style library JSON** using the deterministic build pipeline implemented in Node.js.

## The Generation Pipeline

The process centers on `scripts/generate-style-skill.mjs`, which executes four distinct phases to produce the self-contained reference 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).

### Loading the JSON Source Data

The pipeline initiates by ingesting the master data file. The `readJson()` utility reads and parses [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json), which contains the complete schema including templates, categories, styles, scenes, and repository metadata.

```javascript
const libraryFile = join(root, 'data', 'style-library.json');

function readJson(file) {
  return JSON.parse(readFileSync(file, 'utf8'));
}

const library = readJson(libraryFile);

```

### Validating Library Integrity

Before rendering begins, `validateLibrary()` enforces strict data integrity constraints. It verifies that template anchors exist in [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md), checks for unique identifiers across all collections, and confirms that referenced image files are present. The function throws descriptive errors if any validation rule fails.

```javascript
function validateLibrary(library) {
  // Ensure template anchors exist in docs/templates.md
  const templateText = readFileSync(templatesFile, 'utf8');
  const templateAnchors = new Set(
    [...templateText.matchAll(/<a name="([^"]+)"><\/a>/g)].map(m => m[1])
  );

  // Unique identifier checks
  assertUnique(library.templates, 'id', 'templates');
  assertUnique(library.categories, 'value', 'categories');
  // ... more checks for covers, images, etc.
}

```

### Rendering the Markdown Content

The `renderReference()` function constructs the markdown string iteratively. It builds hierarchical sections including selection rules, template indices with bilingual titles (`label()`), categorized style lists, and scene tags. The function uses `linkForTemplate()` to generate GitHub source URLs pointing to specific anchors in [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md).

```javascript
function renderReference(library) {
  const lines = [
    '# GPT-Image2 Style Library Reference',

    '',
    'Generated from `data/style-library.json`. Use this file as the detailed index for choosing GPT-Image2 prompt templates, visual styles, categories, and scene tags.',
    '',
    '## Selection Rules',

    '',
    '- Match explicit product types to template categories first …',
    // Template loop
    ...library.templates.map(template => [
      `### ${label(template.title, 'en')} / ${label(template.title, 'zh')}`,

      '',
      `- ID: \`${template.id}\``,
      `- Category: ${template.category}`,
      `- Styles: ${list(template.styles)}`,
      `- Scenes: ${list(template.scenes)}`,
      `- Tags: ${list(template.tags)}`,
      `- Cover: \`${template.cover}\``,
      `- Template source: ${linkForTemplate(library, template)}`,
      `- Example cases: ${list((template.exampleCases || []).map(id => \`case ${id}\`))}`,
      '',
      'Use when:',
      `- EN: ${label(template.useWhen, 'en')}`,
      `- ZH: ${label(template.useWhen, 'zh')}`,
      '',
      'Guidance:',
      bulletList(template.guidance?.en, 'en'),
      bulletList(template.guidance?.zh, 'zh'),
      '',
      'Pitfalls:',
      bulletList(template.pitfalls?.en, 'en'),
      bulletList(template.pitfalls?.zh, 'zh'),
      '',
    ].flat()),
    // Categories, Styles, Scenes sections follow similarly
  ];

  return `${lines.join('\n')}\n`;
}

```

### Writing the Reference File

Finally, the script persists the rendered content to the agent's skill directory. It creates parent directories recursively if needed and writes the complete markdown string using `writeFileSync()`.

```javascript
const referenceFile = join(skillDir, 'references', 'style-library.md');
mkdirSync(dirname(referenceFile), { recursive: true });
writeFileSync(referenceFile, renderReference(library));

```

## Key Implementation Functions

Several specialized utilities handle specific transformation logic within `scripts/generate-style-skill.mjs`:

- **`readJson(file)`**: Parses the style library JSON into a JavaScript object using `JSON.parse()`.
- **`validateLibrary(library)`**: Cross-references template anchors against [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) and asserts uniqueness constraints via `assertUnique()`.
- **`label(value, language)`**: Extracts localized strings from bilingual objects (defaulting to English) for rendering multilingual documentation.
- **`linkForTemplate(library, template)`**: Constructs GitHub URLs pointing to specific template definition anchors.
- **`renderReference(library)`**: Orchestrates the entire markdown assembly process line-by-line.

## Summary

- The generation script lives at `scripts/generate-style-skill.mjs` and consumes [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) as its single source of truth.
- **Validation occurs before rendering** to ensure every template anchor matches an entry in [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md) and all identifiers remain unique across templates, categories, and styles.
- The `renderReference()` function produces bilingual markdown with hierarchical sections for templates, categories, styles, and scenes.
- Final output is written to [`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) for direct consumption by the GPT-Image2 agent.
- The deterministic pipeline guarantees that any JSON modification is immediately reflected in the reference documentation upon script execution.

## Frequently Asked Questions

### What triggers the markdown regeneration?

The script executes at build time or when invoked manually. Any modification to [`data/style-library.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/data/style-library.json) requires rerunning `generate-style-skill.mjs` to synchronize the agent reference markdown with the updated style definitions.

### How does the script handle multiple languages?

The `label()` function extracts localized values from bilingual fields (typically `en` and `zh` keys), defaulting to English when a specific translation is missing. This ensures the generated markdown supports international usage without breaking the document structure.

### What happens if a template references a missing anchor?

The `validateLibrary()` function throws a runtime error during the validation phase if a template's anchor cannot be located in [`docs/templates.md`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/docs/templates.md). This prevents the generation of broken source links in the final reference documentation.

### Can I customize the output format?

Yes. By modifying the `renderReference()` function in `scripts/generate-style-skill.mjs`, you can adjust header hierarchies, bullet styles, section ordering, or add new metadata fields. The function builds the markdown using standard template literals, making structural changes straightforward.