[codex] Refactor skills into focused references (#135)

* docs: add runtime-neutral User Input Tools convention across skills Introduce docs/user-input-tools.md as the author-side canonical source and inline the tool-selection rule into every SKILL.md that prompts the user. Also add Skill Self-Containment and User Input Tools sections to CLAUDE.md and the copy-verbatim template to docs/creating-skills.md, so skills stay portable across Claude Code, Codex, Hermes, and other runtimes. * feat: runtime-neutral image generation convention across skills - Introduce inline `## Image Generation Tools` rule in every rendering SKILL.md so skills delegate backend choice instead of hard-coding one; author-side canonical copy lives in docs/image-generation-tools.md. - Add `## Reference Images` support (`--ref`, frontmatter `references:` with direct/style/palette usage) to all seven image-rendering skills. - Move build-batch.ts (with ref propagation into batch JSON) from baoyu-article-illustrator to baoyu-imagine so non-backend skills don't own backend-specific scripts; update baoyu-image-gen stub in sync and relax the CLAUDE.md deprecation note accordingly. * refactor: slim heavy SKILL.md files and move detail to references/ Trim the four largest active skills and move presets, option tables, and confirmation scripts into per-skill references/ so SKILL.md stays focused on the decision flow. - baoyu-slide-deck: 761→258, + styles-gallery.md, confirmation.md - baoyu-image-cards: 657→280, + gallery.md, confirmation.md - baoyu-post-to-wechat: 518→267, + multi-account.md, api-setup.md - baoyu-imagine: 500→230, + providers/, usage-examples.md Also un-deprecate baoyu-image-gen (drop stub warning) so it stays functional alongside baoyu-imagine, and update CLAUDE.md to reflect that both superseded skills are kept in sync rather than stubbed. * refactor: slim four medium SKILL.md files into references/ Continue the P2 pattern on the next tier of skills — move option catalogs, per-provider/adapter detail, and repeated EXTEND.md path boilerplate into their own references so SKILL.md stays focused on the decision flow. - baoyu-comic: 380→297 (art/tone/preset tables → auto-selection.md; Step 7 expanded detail → workflow.md) - baoyu-infographic: 312→207 (layouts/styles/combinations/keywords → gallery.md; ASCII box tables → markdown tables) - baoyu-format-markdown: 376→296 (title + summary generation → title-summary.md; ASCII box tables → markdown tables) - baoyu-url-to-markdown: 334→169 (quality gate + recovery → quality-gate.md; adapters + media download → adapters.md) * chore: sync deprecated skills with their replacements Per project policy, baoyu-xhs-images and baoyu-image-gen are kept functional alongside the active skills they were superseded by. Sync their SKILL.md bodies and references/ to the slimmed baoyu-image-cards and baoyu-imagine versions respectively, so cross-cutting fixes stay consistent. Only the frontmatter (name, description, version, homepage) differs — content is identical. - baoyu-xhs-images: 657→281 (synced with baoyu-image-cards + new confirmation.md, gallery.md) - baoyu-image-gen: 408→231 (synced with baoyu-imagine + new providers/, usage-examples.md) * refactor: collapse EXTEND.md boilerplate into priority tables Replace the dual bash/powershell existence-check blocks and ASCII box art with a single markdown priority table across nine SKILL.md files. The runtime-neutral phrasing removes shell-specific snippets without losing the priority semantics. * fix: address refactor-skills branch review findings - image-gen: restore EXTEND.md paths to baoyu-image-gen (were pointing at baoyu-imagine) and mark descriptions of both deprecated skills as [Deprecated]. - xhs-images: sync neon/warm palettes with image-cards to add the "do not render color names/hex as visible text" safety sentence. - infographic: restore Layout Gallery (21), Style Gallery (21), Recommended Combinations, and Keyword Shortcuts inline (previous refactor split them out but SKILL.md still depended on them), and add the missing references/config/first-time-setup.md + preferences-schema.md. - image-cards / xhs-images / slide-deck / format-markdown: restore the sections that got over-slimmed into references/ (galleries, presets, dimensions, auto-selection, style x layout matrix, title/summary flow) and drop the now-empty shell files. - docs/image-generation-tools.md: note that backend skills themselves (baoyu-imagine, baoyu-image-gen, baoyu-danger-gemini-web) are exempt from the ## Image Generation Tools section requirement. * feat(image-gen): sync Z.AI GLM-Image provider from baoyu-imagine Add Z.AI as a full provider in the deprecated baoyu-image-gen skill so it stays in sync with baoyu-imagine's provider list. - new scripts/providers/zai.ts + zai.test.ts (verbatim port; test factory trimmed to match image-gen's CliArgs shape). - types.ts: "zai" added to Provider union and default_model. - main.ts: rate-limit defaults, provider help text, env var help, --provider validation, loadProviderModule, detectProvider auto-detect chain, getModelForProvider, YAML parser allow-lists. - references/config: Q2e Z.AI model question + zai slot in the preferences schema and batch.provider_limits. Scope is intentionally limited to the Z.AI chain; unrelated drift between image-gen and imagine (OpenAI image-API dialect, aspectRatioSource, imageSizeSource) is left alone. * docs: align inline-convention wording and note backend-skill exemption - docs/user-input-tools.md: fix stale "links here" wording so it matches the inline convention already enforced everywhere else. - CLAUDE.md §Image Generation Tools: inline the backend-skill exemption so readers don't need to cross-reference docs/image-generation-tools.md.
2026-08-02 23:29:47 +08:00 · 2026-04-19 00:48:44 -05:00
parent 5b20f9a746
commit 2c800c670a
58 changed files with 3895 additions and 3269 deletions
@@ -11,6 +11,34 @@ metadata:

 Analyze articles, identify illustration positions, generate images with Type × Style × Palette consistency.

+## User Input Tools
+
+When this skill prompts the user, follow this tool-selection rule (priority order):
+
+1. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
+2. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
+3. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.
+
+Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
+
+## Image Generation Tools
+
+When this skill needs to render an image:
+
+- **Use whatever image-generation tool or skill is available** in the current runtime — e.g., Codex `imagegen`, Hermes `image_generate`, `baoyu-imagine`, or any equivalent the user has installed.
+- **If multiple are available**, ask the user **once** at the start which to use (batch with any other initial questions).
+- **If none are available**, tell the user and ask how to proceed.
+
+**Prompt file requirement (hard)**: write each image's full, final prompt to a standalone file under `prompts/` (naming: `NN-{type}-[slug].md`) BEFORE invoking any backend. The backend receives the prompt file (or its content); the file is the reproducibility record and lets you switch backends without regenerating prompts.
+
+Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) above are examples — substitute the local equivalents under the same rule.
+
+## Reference Images
+
+Users may supply reference images via `--ref <files...>` or by providing file paths / pasting images in conversation. Refs guide style, palette, composition, or subject for specific illustrations.
+
+Full detection, storage, and processing rules are in [references/workflow.md](references/workflow.md) (Step 1.0 saves to `references/NN-ref-{slug}.{ext}`; Step 5.3 processes per-illustration usage `direct | style | palette`). When the chosen backend supports batch input, `direct`-usage entries in each prompt file's `references:` frontmatter should be propagated into its batch payload so backends can pass them through (e.g. `baoyu-imagine` accepts `ref` per task).
+
 ## Three Dimensions

 | Dimension | Controls | Examples |
@@ -53,20 +81,13 @@ See [references/styles.md](references/styles.md) for Core Styles, full gallery,

 **1.5 Load Preferences (EXTEND.md) ⛔ BLOCKING**

-```bash
-# macOS, Linux, WSL, Git Bash
-test -f .baoyu-skills/baoyu-article-illustrator/EXTEND.md && echo "project"
-test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-article-illustrator/EXTEND.md" && echo "xdg"
-test -f "$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md" && echo "user"
-```
+Check EXTEND.md in priority order — the first one found wins:

-```powershell
-# PowerShell (Windows)
-if (Test-Path .baoyu-skills/baoyu-article-illustrator/EXTEND.md) { "project" }
-$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
-if (Test-Path "$xdg/baoyu-skills/baoyu-article-illustrator/EXTEND.md") { "xdg" }
-if (Test-Path "$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md") { "user" }
-```
+| Priority | Path | Scope |
+|----------|------|-------|
+| 1 | `.baoyu-skills/baoyu-article-illustrator/EXTEND.md` | Project |
+| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-article-illustrator/EXTEND.md` | XDG |
+| 3 | `$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md` | User home |

 | Result | Action |
 |--------|--------|
@@ -118,18 +139,18 @@ Full template: [references/workflow.md](references/workflow.md#step-4-generate-o

 ### Step 5: Generate Images

-⛔ **BLOCKING: Prompt files MUST be saved before ANY image generation.**
-
-**Execution strategy**: When multiple illustrations have saved prompt files and the task is now plain generation, prefer `baoyu-imagine` batch mode (`build-batch.ts` → `--batchfile`) over spawning subagents. Use subagents only when each image still needs separate prompt iteration or creative exploration.
+⛔ **BLOCKING: Prompt files MUST be saved before ANY image generation.** This is a hard requirement regardless of which backend is chosen — the prompt file is the reproducibility record.

 1. For each illustration, create a prompt file per [references/prompt-construction.md](references/prompt-construction.md)
 2. Save to `prompts/NN-{type}-{slug}.md` with YAML frontmatter
 3. Prompts **MUST** use type-specific templates with structured sections (ZONES / LABELS / COLORS / STYLE / ASPECT)
 4. LABELS **MUST** include article-specific data: actual numbers, terms, metrics, quotes
 5. **DO NOT** pass ad-hoc inline prompts to `--prompt` without saving prompt files first
-6. Select generation skill, process references (`direct`/`style`/`palette`)
-7. Apply watermark if EXTEND.md enabled
-8. Generate from saved prompt files; retry once on failure
+6. Select the backend via the `## Image Generation Tools` rule at the top: use whatever is available; if multiple, ask the user once. Do this once per session before any generation.
+7. **Execution strategy**: When multiple illustrations have saved prompt files and the task is now plain generation, prefer the chosen backend's batch interface (if it offers one) over spawning subagents. Use subagents only when each image still needs separate prompt iteration or creative exploration. If the backend has no batch interface, generate sequentially.
+8. Process references (`direct`/`style`/`palette`) per prompt frontmatter
+9. Apply watermark if EXTEND.md enabled
+10. Generate from saved prompt files; retry once on failure

 Full procedures: [references/workflow.md](references/workflow.md#step-5-generate-images)

@@ -331,7 +331,7 @@ Prompt Files:
 **DO NOT** pass ad-hoc inline text to `--prompt` without first saving prompt files. The generation command should either use `--promptfiles prompts/NN-{type}-{slug}.md` or read the saved file content for `--prompt`.

 **Execution choice**:
- If multiple illustrations already have saved prompt files and the task is now plain generation, prefer `baoyu-imagine` batch mode (`build-batch.ts` -> `main.ts --batchfile`)
+- If multiple illustrations already have saved prompt files and the task is now plain generation, prefer the chosen backend's batch interface (if it offers one); otherwise generate sequentially
 - Use subagents only when each illustration still needs separate prompt rewriting, style exploration, or other per-image reasoning before generation

 **CRITICAL - References in Frontmatter**:
@@ -1,85 +0,0 @@
-import assert from "node:assert/strict";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-import test from "node:test";
-
-const execFileAsync = promisify(execFile);
-const repoRoot = path.resolve(import.meta.dirname, "..", "..", "..");
-const scriptPath = path.join(repoRoot, "skills", "baoyu-article-illustrator", "scripts", "build-batch.ts");
-
-async function makeFixture(): Promise<{
-  root: string;
-  outlinePath: string;
-  promptsDir: string;
-  outputPath: string;
-}> {
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "baoyu-article-illustrator-build-batch-"));
-  const outlinePath = path.join(root, "outline.md");
-  const promptsDir = path.join(root, "prompts");
-  const outputPath = path.join(root, "batch.json");
-
-  await fs.mkdir(promptsDir, { recursive: true });
-  await fs.writeFile(
-    outlinePath,
-    `## Illustration 1
-**Position**: demo
-**Purpose**: demo
-**Visual Content**: demo
-**Filename**: 01-demo.png
-`,
-  );
-  await fs.writeFile(path.join(promptsDir, "01-demo.md"), "A demo prompt\n");
-
-  return { root, outlinePath, promptsDir, outputPath };
-}
-
-async function runBuildBatch(args: string[]): Promise<void> {
-  await execFileAsync(process.execPath, ["--import", "tsx", scriptPath, ...args], {
-    cwd: repoRoot,
-  });
-}
-
-test("build-batch omits default model so baoyu-imagine can resolve env or EXTEND defaults", async () => {
-  const fixture = await makeFixture();
-
-  await runBuildBatch([
-    "--outline",
-    fixture.outlinePath,
-    "--prompts",
-    fixture.promptsDir,
-    "--output",
-    fixture.outputPath,
-  ]);
-
-  const batch = JSON.parse(await fs.readFile(fixture.outputPath, "utf8")) as {
-    tasks: Array<Record<string, unknown>>;
-  };
-
-  assert.equal(batch.tasks.length, 1);
-  assert.equal(batch.tasks[0]?.provider, "replicate");
-  assert.equal(Object.hasOwn(batch.tasks[0]!, "model"), false);
-});
-
-test("build-batch preserves explicit model overrides", async () => {
-  const fixture = await makeFixture();
-
-  await runBuildBatch([
-    "--outline",
-    fixture.outlinePath,
-    "--prompts",
-    fixture.promptsDir,
-    "--output",
-    fixture.outputPath,
-    "--model",
-    "acme/custom-model",
-  ]);
-
-  const batch = JSON.parse(await fs.readFile(fixture.outputPath, "utf8")) as {
-    tasks: Array<Record<string, unknown>>;
-  };
-
-  assert.equal(batch.tasks[0]?.model, "acme/custom-model");
-});
@@ -1,157 +0,0 @@
-import path from "node:path";
-import process from "node:process";
-import { readdir, readFile, writeFile } from "node:fs/promises";
-
-type CliArgs = {
-  outlinePath: string | null;
-  promptsDir: string | null;
-  outputPath: string | null;
-  imagesDir: string | null;
-  provider: string;
-  model: string | null;
-  aspectRatio: string;
-  quality: string;
-  jobs: number | null;
-  help: boolean;
-};
-
-type OutlineEntry = {
-  index: number;
-  filename: string;
-};
-
-function printUsage(): void {
-  console.log(`Usage:
-  npx -y tsx scripts/build-batch.ts --outline outline.md --prompts prompts --output batch.json --images-dir attachments
-
-Options:
-  --outline <path>     Path to outline.md
-  --prompts <path>     Path to prompts directory
-  --output <path>      Path to output batch.json
-  --images-dir <path>  Directory for generated images
-  --provider <name>    Provider for baoyu-imagine batch tasks (default: replicate)
-  --model <id>         Explicit model for baoyu-imagine batch tasks (default: resolved by baoyu-imagine config/env)
-  --ar <ratio>         Aspect ratio for all tasks (default: 16:9)
-  --quality <level>    Quality for all tasks (default: 2k)
-  --jobs <count>       Recommended worker count metadata (optional)
-  -h, --help           Show help`);
-}
-
-function parseArgs(argv: string[]): CliArgs {
-  const args: CliArgs = {
-    outlinePath: null,
-    promptsDir: null,
-    outputPath: null,
-    imagesDir: null,
-    provider: "replicate",
-    model: null,
-    aspectRatio: "16:9",
-    quality: "2k",
-    jobs: null,
-    help: false,
-  };
-
-  for (let i = 0; i < argv.length; i++) {
-    const current = argv[i]!;
-    if (current === "--outline") args.outlinePath = argv[++i] ?? null;
-    else if (current === "--prompts") args.promptsDir = argv[++i] ?? null;
-    else if (current === "--output") args.outputPath = argv[++i] ?? null;
-    else if (current === "--images-dir") args.imagesDir = argv[++i] ?? null;
-    else if (current === "--provider") args.provider = argv[++i] ?? args.provider;
-    else if (current === "--model") args.model = argv[++i] ?? args.model;
-    else if (current === "--ar") args.aspectRatio = argv[++i] ?? args.aspectRatio;
-    else if (current === "--quality") args.quality = argv[++i] ?? args.quality;
-    else if (current === "--jobs") {
-      const value = argv[++i];
-      args.jobs = value ? parseInt(value, 10) : null;
-    } else if (current === "--help" || current === "-h") {
-      args.help = true;
-    }
-  }
-  return args;
-}
-
-function parseOutline(content: string): OutlineEntry[] {
-  const entries: OutlineEntry[] = [];
-  const blocks = content.split(/^## Illustration\s+/m).slice(1);
-
-  for (const block of blocks) {
-    const indexMatch = block.match(/^(\d+)/);
-    const filenameMatch = block.match(/\*\*Filename\*\*:\s*(.+)/);
-    if (indexMatch && filenameMatch) {
-      entries.push({
-        index: parseInt(indexMatch[1]!, 10),
-        filename: filenameMatch[1]!.trim(),
-      });
-    }
-  }
-  return entries;
-}
-
-async function findPromptFile(promptsDir: string, entry: OutlineEntry): Promise<string | null> {
-  const files = await readdir(promptsDir);
-  const prefix = String(entry.index).padStart(2, "0");
-  const match = files.find((f) => f.startsWith(prefix) && f.endsWith(".md"));
-  return match ? path.join(promptsDir, match) : null;
-}
-
-async function main(): Promise<void> {
-  const args = parseArgs(process.argv.slice(2));
-  if (args.help) {
-    printUsage();
-    return;
-  }
-
-  if (!args.outlinePath) {
-    console.error("Error: --outline is required");
-    process.exit(1);
-  }
-  if (!args.promptsDir) {
-    console.error("Error: --prompts is required");
-    process.exit(1);
-  }
-  if (!args.outputPath) {
-    console.error("Error: --output is required");
-    process.exit(1);
-  }
-
-  const outlineContent = await readFile(args.outlinePath, "utf8");
-  const entries = parseOutline(outlineContent);
-
-  if (entries.length === 0) {
-    console.error("No illustration entries found in outline.");
-    process.exit(1);
-  }
-
-  const tasks = [];
-  for (const entry of entries) {
-    const promptFile = await findPromptFile(args.promptsDir, entry);
-    if (!promptFile) {
-      console.error(`Warning: No prompt file found for illustration ${entry.index}, skipping.`);
-      continue;
-    }
-
-    const imageDir = args.imagesDir ?? path.dirname(args.outputPath);
-    const task: Record<string, unknown> = {
-      id: `illustration-${String(entry.index).padStart(2, "0")}`,
-      promptFiles: [promptFile],
-      image: path.join(imageDir, entry.filename),
-      provider: args.provider,
-      ar: args.aspectRatio,
-      quality: args.quality,
-    };
-    if (args.model) task.model = args.model;
-    tasks.push(task);
-  }
-
-  const output: Record<string, unknown> = { tasks };
-  if (args.jobs) output.jobs = args.jobs;
-
-  await writeFile(args.outputPath, JSON.stringify(output, null, 2) + "\n");
-  console.log(`Batch file written: ${args.outputPath} (${tasks.length} tasks)`);
-}
-
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});