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

The generate-style-skill.mjs script transforms 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.

Loading the JSON Source Data

The pipeline initiates by ingesting the master data file. The readJson() utility reads and parses data/style-library.json, which contains the complete schema including templates, categories, styles, scenes, and repository metadata.

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, 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.

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.

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().

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 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 as its single source of truth.
• Validation occurs before rendering to ensure every template anchor matches an entry in 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 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 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. 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.

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