md-twitter-dresser-skill

md-twitter-dresser

One command to dress your Markdown article — title + cover + inline images — ready to publish to X (Twitter) or anywhere else. No more hunting for stock images.

中文文档 · Detailed Guide

A Claude Code skill that auto-dresses a finished Markdown article — picks a title, generates a cover image, drops 2-3 inline images at smart insertion points — with two rounds of HTML-based human confirmation so you spend zero API budget on bad directions.

The problem

You finished writing a long-form article in Markdown. Before publishing it (to X/Twitter, your blog, a newsletter, WeChat, Substack, anywhere), you need to:

1. Pick a title that actually drives clicks
2. Generate a cover image
3. Find 2-3 good spots in the body for supporting illustrations
4. Design what each inline image should look like
5. Iterate on the images until they don't suck

Done manually this takes 30-90 minutes — and the real bottleneck is picking image directions blind while doing visual design work you're not actually good at, with mediocre results to show for it.

The solution

       article.md
           │
           ▼
   ┌──────────────┐
   │   Claude     │   reads article, picks slots, writes prompts,
   │   analyzes   │   drafts 3-5 candidate titles
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │  HTML review │   confirm prompts (ZERO API spend)
   │  round 1     │
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │  codex       │   auto-picks newest GPT image model,
   │  generates   │   Pillow center-crops to target ratio
   └──────┬───────┘
          ▼
   ┌──────────────┐
   │  HTML review │   per-image approval on the real outputs
   │  round 2     │
   └──────┬───────┘
          ▼
  article-dressed.md

Two HTML pages bridge the cost gap:

• Round 1 (dresser-prompts-review.html) — placeholder cards with proposed prompts. Edit, delete, or add slots before any API call.
• Round 2 (dresser-images-review.html) — the actual generated images. Approve individually, regenerate single failures, swap prompts per image.

State flows back to the conversation through clipboard-copied <dresser:*> blocks — no local server, no Claude-Code-specific integration. Hit "Export", Cmd+V into the chat, Claude reacts.

Key features

• 🤖 End-to-end automated image generation — Claude reads your article, picks insertion slots, writes bilingual prompts; codex auto-calls the image API and auto-crops to the target ratio. No tool switching, no manual drawing.
• 📐 Smart aspect ratios — cover always 5:2 (perfect for hero banners and social cards), inline images sized by content (16:9 / 1:1 / 9:16 / 4:3)
• 🎨 6 built-in style templates — 3 title voices (KOL-punchy / info-dense / curiosity-hook) × 3 image styles (tech-flat / editorial-photo / ink-wash). Drag-and-drop your own reference image to teach the skill a new style.
• 💰 Cost guardrail — prompts are confirmed BEFORE generation. Bad directions die at $0 instead of $0.04 each.
• 🔁 Self-upgrading backend — codex auto-picks the newest GPT image-generation model available on your account (tries gpt-image-2/N, falls back to gpt-image-1, last resort dall-e-3). No skill updates needed when OpenAI ships a new model.
• 🔌 Backend-agnostic — routes through codex exec, so swapping to Stable Diffusion / 即梦 / 可灵 is a natural-language change, not a code change.
• 📝 Standard CommonMark output — no platform-specific extensions. Pipe to any downstream tool.

Requirements

• Claude Code — installed and configured
• Codex CLI — npm i -g @openai/codex-cli or brew install codex (this skill delegates image generation to codex)
• Codex auth — pick one:
  • ChatGPT subscription (recommended) — if you have ChatGPT Plus / Pro / Business / Enterprise, just run codex login and authenticate with your ChatGPT account. No separate API key needed; image generation draws from your subscription.
  • OpenAI API key — alternatively, export OPENAI_API_KEY=sk-... and pay per token.
• Python 3.10+ — for the helper scripts (no Python dependencies; uses stdlib + Pillow when post-processing)
• A browser — any modern one; the HTML pages are pure file:// pages

Installation

Option 1 — Claude Code plugin (recommended)

/plugin install md-twitter-dresser@chrisduu/md-twitter-dresser-skill

Option 2 — Manual clone

git clone https://github.com/chrisduu/md-twitter-dresser-skill.git
mkdir -p ~/.claude/skills/
cp -r md-twitter-dresser-skill/skills/md-twitter-dresser ~/.claude/skills/

Verify:

ls ~/.claude/skills/md-twitter-dresser/SKILL.md

Usage

Just say any of these to Claude Code — the skill auto-triggers and Claude drives the pipeline. Between phases an HTML page opens in your browser; review, click a button, paste the exported block back into chat. That's it.

• "给这篇 md 文章配图加标题"
• "帮我准备一下这篇文章,加封面图和标题"
• "dress this markdown article for publishing"
• "add images and a title to my markdown"

Workflow at a glance

Aspect ratio rules

The cover is non-negotiable at 5:2. Inline ratios are picked per image by Claude based on the image's content, NOT by the style template. Style yaml controls visual look, slot json controls frame shape.

Built-in templates

Title styles (assets/templates/title-styles/):

Image styles (assets/templates/image-styles/):

Want your own? Drag a reference image into the template picker — Claude reads it with its vision capability and writes a new yaml.

Project structure

md-twitter-dresser-skill/
├── .claude-plugin/
│   └── plugin.json                   # Plugin metadata for Claude Code
├── skills/
│   └── md-twitter-dresser/
│       ├── SKILL.md                  # Main skill instructions
│       ├── LICENSE.txt
│       ├── scripts/
│       │   ├── analyze_md.py
│       │   ├── render_prompts_review.py
│       │   ├── gen_images.py
│       │   ├── render_images_review.py
│       │   ├── render_template_picker.py
│       │   ├── learn_style_from_image.py
│       │   ├── embed_images.py
│       │   └── lib/
│       │       ├── md_parser.py
│       │       ├── codex_runner.py
│       │       ├── html_helpers.py
│       │       └── filenames.py
│       ├── assets/
│       │   ├── templates/            # 3 title-styles + 3 image-styles
│       │   ├── prompts-review-template.html
│       │   ├── images-review-template.html
│       │   ├── template-picker.html
│       │   └── prompts/              # Analyzer system prompts
│       └── references/               # JSON schema, codex how-to, etc.
├── docs/
│   └── GUIDE.md                      # Detailed usage walkthrough
├── .gitignore
├── LICENSE                           # MIT
├── README.md                         # This file
└── README_CN.md                      # Chinese version

FAQ

Q: Can I use this on Windows? A: Yes. The Python scripts are cross-platform; the only platform-specific bit is opening the HTML in a browser (Darwin uses open, Linux uses xdg-open, Windows uses start). All handled.

Q: What if codex isn't installed? A: gen_images.py will exit cleanly with a message. You can run with --dry-run to test the whole pipeline without actually generating images.

Q: Can I swap to a non-OpenAI image API? A: Yes. Edit scripts/lib/codex_runner.py::_build_codex_prompt and add a branch for your backend — the natural-language prompt is forgiving as long as you name the provider, endpoint, and where the API key lives.

Q: How much does one article cost? A: 3-4 images per article. With the newest GPT image models that's around $0.10-0.20 per article. The Round-1 review exists specifically so you kill bad directions at $0.

Q: Is my Markdown article modified in place? A: No. The original article.md is read-only; the dressed version is written to article-dressed.md (or whatever --output you pass).

License

MIT — see LICENSE.

Acknowledgments

This skill's clipboard-copy + refresh-tab interaction pattern is a generalization of an approach that works well for AI-content review workflows where the LLM and the user need to exchange structured state without a local server.