Readme Generator

node_modules/
package-lock.json
*.html
!templates/*.html
results.tsv

MIT License

Copyright (c) 2026 geekjourneyx

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

{
  "name": "readme-generator",
  "version": "1.1.0",
  "description": "AI Agent Skill for creating portfolio-grade GitHub READMEs with story-driven writing, visual assets, and metadata recommendations",
  "scripts": {
    "screenshot": "node scripts/gen_infographic.mjs",
    "showcase": "node scripts/render_showcase_assets.mjs",
    "compress": "node scripts/compress_png_assets.mjs",
    "webp": "node scripts/convert_webp_assets.mjs"
  },
  "keywords": [
    "readme",
    "github-readme",
    "agent-skill",
    "codex",
    "image-generation",
    "portfolio",
    "infographic",
    "seo"
  ],
  "author": "geekjourneyx",
  "license": "MIT",
  "type": "module",
  "dependencies": {
    "playwright": "^1.59.1"
  }
}

#!/usr/bin/env node
/**
 * Losslessly recompress PNG IDAT chunks with Node's built-in zlib.
 *
 * This is intentionally dependency-free so README asset generation can always
 * run after Playwright screenshots or Codex Image Gen output is copied in.
 */

import { readFileSync, statSync, writeFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { deflateSync, inflateSync } from 'node:zlib';

const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
const DEFAULT_FILES = [
  'assets/banner.png',
  'assets/features.png',
];

const files = process.argv.slice(2);
const targets = files.length ? files : DEFAULT_FILES;

const crcTable = new Uint32Array(256);
for (let n = 0; n < 256; n += 1) {
  let c = n;
  for (let k = 0; k < 8; k += 1) {
    c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
  }
  crcTable[n] = c >>> 0;
}

function crc32(buffer) {
  let c = 0xffffffff;
  for (const byte of buffer) {
    c = crcTable[(c ^ byte) & 0xff] ^ (c >>> 8);
  }
  return (c ^ 0xffffffff) >>> 0;
}

function makeChunk(type, data) {
  const typeBuffer = Buffer.from(type, 'ascii');
  const length = Buffer.alloc(4);
  const crc = Buffer.alloc(4);
  length.writeUInt32BE(data.length, 0);
  crc.writeUInt32BE(crc32(Buffer.concat([typeBuffer, data])), 0);
  return Buffer.concat([length, typeBuffer, data, crc]);
}

function optimizePng(path) {
  const input = readFileSync(path);
  if (!input.subarray(0, 8).equals(PNG_SIGNATURE)) {
    throw new Error(`${path} is not a PNG file`);
  }

  const passthroughChunks = [];
  const idatChunks = [];
  let offset = 8;

  while (offset < input.length) {
    const length = input.readUInt32BE(offset);
    const type = input.subarray(offset + 4, offset + 8).toString('ascii');
    const data = input.subarray(offset + 8, offset + 8 + length);
    const rawChunk = input.subarray(offset, offset + 12 + length);
    offset += 12 + length;

    if (type === 'IDAT') {
      idatChunks.push(data);
      continue;
    }

    if (type === 'IEND') {
      const inflated = inflateSync(Buffer.concat(idatChunks));
      const recompressed = deflateSync(inflated, { level: 9 });
      const output = Buffer.concat([
        PNG_SIGNATURE,
        ...passthroughChunks,
        makeChunk('IDAT', recompressed),
        rawChunk,
      ]);
      writeFileSync(path, output);
      return;
    }

    passthroughChunks.push(rawChunk);
  }

  throw new Error(`${path} has no IEND chunk`);
}

for (const file of targets) {
  const path = resolve(file);
  const before = statSync(path).size;
  optimizePng(path);
  const after = statSync(path).size;
  const saved = Math.max(0, before - after);
  console.log(`${file}: ${before} -> ${after} bytes (${saved} saved)`);
}

#!/usr/bin/env node
/**
 * Convert README visual assets to WebP using cwebp.
 *
 * WebP keeps README image loading lightweight. This script intentionally uses
 * the local cwebp binary instead of adding a heavy image dependency.
 */

import { execFileSync } from 'node:child_process';
import { existsSync, statSync } from 'node:fs';
import { resolve } from 'node:path';

const DEFAULT_JOBS = [
  ['assets/banner.png', 'assets/banner.webp'],
  ['assets/features.png', 'assets/features.webp'],
];

const args = process.argv.slice(2);
const quality = '86';

function parseJobs() {
  if (!args.length) return DEFAULT_JOBS;
  if (args.length % 2 !== 0) {
    throw new Error('Usage: node scripts/convert_webp_assets.mjs [input.png output.webp]...');
  }

  const jobs = [];
  for (let i = 0; i < args.length; i += 2) {
    jobs.push([args[i], args[i + 1]]);
  }
  return jobs;
}

function ensureCwebp() {
  try {
    execFileSync('cwebp', ['-version'], { stdio: 'ignore' });
  } catch {
    throw new Error('cwebp is required to convert README assets to WebP.');
  }
}

ensureCwebp();

for (const [inputFile, outputFile] of parseJobs()) {
  const input = resolve(inputFile);
  const output = resolve(outputFile);

  if (!existsSync(input) && existsSync(output)) {
    console.log(`${outputFile}: already converted`);
    continue;
  }

  if (!existsSync(input)) {
    throw new Error(`${inputFile} does not exist`);
  }

  execFileSync('cwebp', ['-q', quality, input, '-o', output], { stdio: 'inherit' });

  const before = statSync(input).size;
  const after = statSync(output).size;
  const saved = Math.max(0, before - after);
  console.log(`${outputFile}: ${before} -> ${after} bytes (${saved} saved)`);
}

#!/usr/bin/env node
/**
 * gen_infographic.mjs
 * Playwright screenshot utility for README infographic generation.
 *
 * Usage:
 *   node scripts/gen_infographic.mjs <input.html> <output.png> [width] [height]
 *
 * Examples:
 *   node scripts/gen_infographic.mjs /tmp/banner.html assets/banner.png 1920 1080
 *   node scripts/gen_infographic.mjs /tmp/features.html assets/features.png
 */

import { chromium } from 'playwright';
import { resolve } from 'path';
import { existsSync } from 'fs';

const [,, inputHtml, outputPng, width = '1920', height = '1080'] = process.argv;

if (!inputHtml || !outputPng) {
  console.error('Usage: node gen_infographic.mjs <input.html> <output.png> [width] [height]');
  process.exit(1);
}

const inputPath = resolve(inputHtml);
if (!existsSync(inputPath)) {
  console.error(`Input file not found: ${inputPath}`);
  process.exit(1);
}

const w = parseInt(width, 10);
const h = parseInt(height, 10);

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.setViewportSize({ width: w, height: h });
  await page.goto(`file://${inputPath}`);
  // Wait for fonts (Google Fonts CDN) and any CSS transitions
  await page.waitForTimeout(2500);
  await page.screenshot({
    path: resolve(outputPng),
    clip: { x: 0, y: 0, width: w, height: h },
  });
  await browser.close();
  console.log(`✅ ${outputPng} (${w}×${h})`);
})();

#!/usr/bin/env node
/**
 * Render this skill's own README showcase assets from the HTML templates.
 *
 * The generic screenshot utility stays in gen_infographic.mjs. This script only
 * fills the templates with this repository's current story and calls the utility.
 */

import { execFileSync } from 'node:child_process';
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';

const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const tmpDir = '/private/tmp/readme-generator-showcase';

mkdirSync(tmpDir, { recursive: true });

const common = {
  PROJECT_NAME: 'GitHub README Generator',
  TAGLINE: '把项目 README 做成一份可以展示的作品。',
  PRIMARY_COLOR: '#c8a15a',
  CATEGORY: 'Portfolio README Design',
  PLATFORM: 'Codex',
  LANGUAGE: 'Markdown',
  VERSION_INFO: 'Story-driven · Image Gen ready',
};

const techCards = `
<div class="tech-card">
  <div class="tech-icon">01</div>
  <div>
    <div class="tech-name">Story</div>
    <div class="tech-desc">先提炼项目为什么存在，而不是先堆功能。</div>
  </div>
</div>
<div class="tech-card">
  <div class="tech-icon">02</div>
  <div>
    <div class="tech-name">Visual</div>
    <div class="tech-desc">封面可用 Codex Image Gen，说明图保持清晰准确。</div>
  </div>
</div>
<div class="tech-card">
  <div class="tech-icon">03</div>
  <div>
    <div class="tech-name">Delivery</div>
    <div class="tech-desc">输出 README、视觉资产和 GitHub 元信息建议。</div>
  </div>
</div>`;

const featureCards = `
<article class="card featured">
  <div>
    <div class="card-tag">Story</div>
    <h3 class="card-title">讲清项目为什么存在</h3>
    <p class="card-desc">把背景、对象和结果压缩成读者能快速判断的叙事。</p>
  </div>
  <div>
    <div class="rule"></div>
    <div class="card-icon">01</div>
  </div>
</article>
<article class="card">
  <div>
    <div class="card-tag">Visual</div>
    <h3 class="card-title">让 README 像作品被看见</h3>
    <p class="card-desc">用封面、海报和留白建立第一印象，避免小字信息堆叠。</p>
  </div>
  <div>
    <div class="rule"></div>
    <div class="card-icon">02</div>
  </div>
</article>
<article class="card">
  <div>
    <div class="card-tag">Signal</div>
    <h3 class="card-title">保留真正有用的信息</h3>
    <p class="card-desc">快速开始、可信结果、作者和许可证，其他噪音交给 docs。</p>
  </div>
  <div>
    <div class="rule"></div>
    <div class="card-icon">03</div>
  </div>
</article>`;

const jobs = [
  {
    template: 'banner.html',
    html: `${tmpDir}/banner.html`,
    png: `${tmpDir}/banner.png`,
    webp: `${root}/assets/banner.webp`,
    vars: { ...common, TECH_CARDS: techCards },
  },
  {
    template: 'features.html',
    html: `${tmpDir}/features.html`,
    png: `${tmpDir}/features.png`,
    webp: `${root}/assets/features.webp`,
    vars: { ...common, FEATURE_CARDS: featureCards, FEATURE_COUNT: '3' },
  },
];

for (const job of jobs) {
  let html = readFileSync(`${root}/templates/${job.template}`, 'utf8');
  for (const [key, value] of Object.entries(job.vars)) {
    html = html.replaceAll(`{{${key}}}`, value);
  }
  writeFileSync(job.html, html);
  execFileSync(
    process.execPath,
    [`${root}/scripts/gen_infographic.mjs`, job.html, job.png, '1920', '1080'],
    { stdio: 'inherit' },
  );
}

execFileSync(
  process.execPath,
  [
    `${root}/scripts/convert_webp_assets.mjs`,
    `${tmpDir}/banner.png`,
    `${root}/assets/banner.webp`,
    `${tmpDir}/features.png`,
    `${root}/assets/features.webp`,
  ],
  { stdio: 'inherit' },
);

<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=1920, height=1080">
<style>
  * { margin: 0; padding: 0; box-sizing: border-box; }
  :root {
    --accent: {{PRIMARY_COLOR}};
    --paper: #050505;
    --ink: #f3efe7;
    --muted: rgba(243, 239, 231, 0.58);
    --line: rgba(243, 239, 231, 0.14);
  }
  body {
    width: 1920px;
    height: 1080px;
    overflow: hidden;
    background: var(--paper);
    font-family: Georgia, "Times New Roman", "Noto Serif SC", "Songti SC", serif;
    color: var(--ink);
  }
  .page {
    width: 100%;
    height: 100%;
    padding: 92px 120px 78px;
    display: grid;
    grid-template-columns: 1fr 540px;
    gap: 96px;
    position: relative;
  }
  .page::before {
    content: "";
    position: absolute;
    inset: 42px;
    border: 1px solid var(--line);
    background-image: linear-gradient(115deg, rgba(255,255,255,0.035), transparent 34%, rgba(200,161,90,0.04));
    pointer-events: none;
  }
  .page::after {
    content: "";
    position: absolute;
    right: 0;
    top: 0;
    width: 42%;
    height: 100%;
    background: linear-gradient(180deg, #050505 0%, #090806 100%);
    z-index: 0;
  }
  .hero,
  .side {
    position: relative;
    z-index: 1;
  }
  .kicker {
    display: flex;
    align-items: center;
    gap: 24px;
    margin-bottom: 88px;
    font-family: "Avenir Next", "Helvetica Neue", Arial, sans-serif;
    font-size: 24px;
    font-weight: 700;
    letter-spacing: 0.18em;
    text-transform: uppercase;
    color: var(--accent);
  }
  .kicker::before {
    content: "";
    width: 96px;
    height: 3px;
    background: var(--accent);
  }
  h1 {
    max-width: 940px;
    font-size: 104px;
    line-height: 1;
    letter-spacing: -0.035em;
    font-weight: 700;
  }
  .statement {
    max-width: 870px;
    margin-top: 56px;
    font-family: "Avenir Next", "Helvetica Neue", Arial, "PingFang SC", sans-serif;
    font-size: 29px;
    line-height: 1.42;
    color: var(--muted);
    font-weight: 600;
  }
  .meta {
    display: flex;
    gap: 18px;
    margin-top: 76px;
    font-family: "Avenir Next", "Helvetica Neue", Arial, sans-serif;
  }
  .pill {
    min-width: 132px;
    border: 1px solid rgba(243,239,231,0.16);
    padding: 18px 22px;
    font-size: 22px;
    font-weight: 700;
    color: rgba(243,239,231,0.62);
    background: rgba(255,255,255,0.02);
    text-align: center;
  }
  .side {
    height: 100%;
    padding: 86px 0 58px;
    display: flex;
    flex-direction: column;
    justify-content: space-between;
    color: #f2efe8;
  }
  .side-title {
    font-family: "Avenir Next", "Helvetica Neue", Arial, sans-serif;
    font-size: 24px;
    line-height: 1.35;
    color: rgba(242,239,232,0.62);
    max-width: 440px;
  }
  .side-title strong {
    color: #fffaf0;
    font-weight: 800;
  }
  .tech-list {
    display: grid;
    gap: 18px;
  }
  .tech-card {
    border-top: 1px solid rgba(242,239,232,0.18);
    padding-top: 22px;
    display: grid;
    grid-template-columns: 78px 1fr;
    gap: 22px;
    align-items: start;
  }
  .tech-icon {
    font-family: Georgia, "Times New Roman", serif;
    font-size: 36px;
    line-height: 1;
    color: var(--accent);
  }
  .tech-name {
    font-family: "Avenir Next", "Helvetica Neue", Arial, sans-serif;
    font-size: 25px;
    font-weight: 800;
    color: #fffaf0;
  }
  .tech-desc {
    margin-top: 8px;
    font-family: "Avenir Next", "Helvetica Neue", Arial, "PingFang SC", sans-serif;
    font-size: 20px;
    line-height: 1.35;
    color: rgba(242,239,232,0.62);
  }
  .version-tag {
    font-family: "Avenir Next", "Helvetica Neue", Arial, sans-serif;
    font-size: 22px;
    font-weight: 700;
    color: rgba(242,239,232,0.48);
  }
</style>
</head>
<body>
<main class="page">
  <section class="hero">
    <div class="kicker">{{CATEGORY}}</div>
    <h1>{{PROJECT_NAME}}</h1>
    <p class="statement">{{TAGLINE}}</p>
    <div class="meta">
      <div class="pill">MIT</div>
      <div class="pill">{{PLATFORM}}</div>
      <div class="pill">{{LANGUAGE}}</div>
    </div>
  </section>
  <aside class="side">
    <div class="side-title"><strong>README is the first gallery wall.</strong><br>Make the project understandable before making it exhaustive.</div>
    <div class="tech-list">
      {{TECH_CARDS}}
    </div>
    <div class="version-tag">{{VERSION_INFO}}</div>
  </aside>
</main>
</body>
</html>

<!DOCTYPE html>
<html lang="zh">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=1920, height=1080">
<style>
  * { margin: 0; padding: 0; box-sizing: border-box; }
  :root {
    --accent: {{PRIMARY_COLOR}};
    --paper: #050505;
    --ink: #f3efe7;
    --muted: rgba(243, 239, 231, 0.58);
    --line: rgba(243, 239, 231, 0.14);
  }
  body {
    width: 1920px;
    height: 1080px;
    overflow: hidden;
    background: var(--paper);
    color: var(--ink);
    font-family: "Avenir Next", "Helvetica Neue", Arial, "PingFang SC", sans-serif;
  }
  .page {
    width: 100%;
    height: 100%;
    padding: 86px 120px 94px;
    display: flex;
    flex-direction: column;
  }
  .header {
    display: grid;
    grid-template-columns: 1fr auto;
    align-items: end;
    padding-bottom: 42px;
    border-bottom: 1px solid var(--line);
  }
  .eyebrow {
    font-size: 23px;
    font-weight: 800;
    color: var(--accent);
    letter-spacing: 0.12em;
    text-transform: uppercase;
    margin-bottom: 20px;
  }
  h2 {
    font-family: Georgia, "Times New Roman", "Noto Serif SC", "Songti SC", serif;
    font-size: 68px;
    line-height: 1.02;
    letter-spacing: -0.035em;
  }
  .count {
    font-size: 25px;
    color: var(--muted);
    font-weight: 700;
  }
  .grid {
    flex: 1;
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    gap: 1px;
    margin-top: 74px;
    background: var(--line);
    border: 1px solid var(--line);
  }
  .card {
    background: #090909;
    min-height: 600px;
    padding: 58px 54px 52px;
    display: flex;
    flex-direction: column;
    justify-content: space-between;
    position: relative;
  }
  .card.featured {
    background: #0f0d08;
    color: #fffaf0;
    outline: 2px solid var(--accent);
    outline-offset: -2px;
  }
  .card-icon {
    font-family: Georgia, "Times New Roman", serif;
    font-size: 64px;
    line-height: 1;
    color: rgba(243,239,231,0.16);
  }
  .featured .card-icon {
    color: rgba(255,250,240,0.32);
  }
  .card-tag {
    font-size: 22px;
    font-weight: 800;
    letter-spacing: 0.08em;
    color: var(--accent);
    text-transform: uppercase;
  }
  .featured .card-tag {
    color: rgba(255,250,240,0.78);
  }
  .card-title {
    margin-top: 34px;
    font-family: Georgia, "Times New Roman", "Noto Serif SC", "Songti SC", serif;
    font-size: 44px;
    line-height: 1.05;
    letter-spacing: -0.025em;
    color: var(--ink);
  }
  .featured .card-title {
    color: #fffaf0;
  }
  .card-desc {
    margin-top: 30px;
    font-size: 25px;
    line-height: 1.45;
    font-weight: 600;
    color: var(--muted);
    max-width: 430px;
  }
  .featured .card-desc {
    color: rgba(255,250,240,0.84);
  }
  .rule {
    width: 100%;
    height: 2px;
    background: var(--line);
    margin-top: 48px;
  }
  .featured .rule {
    background: rgba(255,250,240,0.34);
  }
</style>
</head>
<body>
<main class="page">
  <header class="header">
    <div>
      <div class="eyebrow">What the reader remembers</div>
      <h2>三个结果，足够了</h2>
    </div>
    <div class="count">{{FEATURE_COUNT}} core outcomes</div>
  </header>
  <section class="grid">
    {{FEATURE_CARDS}}
  </section>
</main>
</body>
</html>