How to Regenerate the Style Library Markdown from JSON in awesome-gpt-image-2

Run npm run generate:style-skill to regenerate the style-library markdown from the JSON source in awesome-gpt-image-2, which validates data/style-library.json and writes the formatted output to agents/skills/gpt-image-2-style-library/references/style-library.md.

The awesome-gpt-image-2 repository maintains its visual style definitions in a structured JSON file rather than static markdown. When you modify this data, you must regenerate the style library markdown from JSON to keep the reference documentation synchronized with the source definitions.

The Generation Pipeline

The repository implements a single source of truth pattern where the JSON file serves as the master definition. The generation pipeline reads this file, enforces data integrity through validation, and produces a human-readable markdown reference that agents can consume.

Input Source: data/style-library.json

The file data/style-library.json defines all templates, categories, styles, and scenes. This is the only file you should edit when modifying the visual library. The JSON structure includes unique identifiers, anchor names, and cover image references that must remain consistent across the dataset.

Validation Logic

Before rendering any output, the script executes validateLibrary(library) to ensure data quality. This validation layer checks for unique IDs, anchors, and cover images using helper functions like assertUnique(items, field, label). If validation fails, the script throws an error and halts, preventing corrupted data from reaching the markdown output.

Output Target: style-library.md

The rendered markdown lands at agents/skills/gpt-image-2-style-library/references/style-library.md. This file is completely overwritten during each regeneration, ensuring the documentation always reflects the current state of the JSON source code.

Step-by-Step Regeneration Process

Follow these steps to synchronize the markdown documentation after editing the JSON source.

Install Dependencies

Ensure Node.js dependencies are installed before running the generator.

npm install

Run the NPM Script

The package.json defines a convenient shortcut in the scripts section. Execute this command from the repository root to trigger the full regeneration pipeline.

npm run generate:style-skill

This command internally maps to node scripts/generate-style-skill.mjs as configured in the npm scripts.

Execute the Script Directly

If you prefer to bypass npm, invoke the Node.js script directly.

node scripts/generate-style-skill.mjs

Understanding the Core Script Mechanics

The file scripts/generate-style-skill.mjs orchestrates the entire transformation process from JSON to markdown.

First, the script resolves absolute paths relative to its own location using fileURLToPath and dirname:

// scripts/generate-style-skill.mjs
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const root = dirname(dirname(fileURLToPath(import.meta.url)));
const libraryFile   = join(root, 'data', 'style-library.json');
const referenceFile = join(
  root, 'agents', 'skills', 'gpt-image-2-style-library',
  'references', 'style-library.md'
 );

// Load and validate the JSON
const library = JSON.parse(readFileSync(libraryFile, 'utf8'));
validateLibrary(library);

// Render the markdown reference
const markdown = renderReference(library);

// Ensure the output directory exists and write the file
mkdirSync(dirname(referenceFile), { recursive: true });
writeFileSync(referenceFile, markdown);

The validation layer uses assertUnique to enforce data integrity by preventing duplicate entries across critical fields:

function assertUnique(items, field, label) {
  const seen = new Set();
  for (const item of items) {
    const value = item[field];
    if (!value) throw new Error(`${label} is missing ${field}`);
    if (seen.has(value)) throw new Error(`${label} has duplicate ${field}: ${value}`);
    seen.add(value);
  }
}

Summary

• Never edit the markdown directly: The file at agents/skills/gpt-image-2-style-library/references/style-library.md is auto-generated and overwritten during regeneration.
• Source of truth: Always modify data/style-library.json to update style definitions.
• Validation enforced: The script validates uniqueness of IDs and anchors using validateLibrary and assertUnique before writing output.
• Simple execution: Run npm run generate:style-skill to synchronize the markdown reference with the JSON source.

Frequently Asked Questions

Can I edit the style-library.md file directly?

No. The markdown file is auto-generated and completely overwritten when you run the generation script. Always modify data/style-library.json and execute the regeneration command to update the reference documentation properly.

What validation checks does the script perform?

The script validates uniqueness of template IDs, anchors, and cover images using the assertUnique helper function. It throws descriptive errors if required fields are missing or if duplicate values exist across the library definitions, preventing invalid data from propagating to the output.

Do I need to create the output directory manually?

No. The script automatically creates any missing directories in the path using mkdirSync with the recursive: true option before attempting to write the markdown file. You only need write permissions in the repository.

Where is the npm script defined?

The command generate:style-skill is defined in package.json within the scripts section. It maps to node scripts/generate-style-skill.mjs, providing a convenient shorthand for the regeneration process without requiring you to remember the full file path.

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