Design & Motion · yang0/handraw-style
handdraw-style-prompter
Turn a 001–261 hand-drawn style number and image theme into bilingual prompts, or generate an image with a model-capability-aware decision about whether the matching numbered image is needed as a style reference.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
The core capability is "indexing styles into numbers": 261 style entries (index number + original reference name + generation name + core visual traits) are parsed from the root styles_200_reorganized.md to generate references/styles.json, which is then used by build_library.py to generate an offline, searchable gallery HTML.
handdraw-style-prompter/SKILL.md
Users can browse `gallery/index.html` for the numbered contact sheets. The authoritative style content is `../styles_200_reorganized.md`; `references/styles.json` is a generated index and must be refreshed with `python scripts/build_library.py` after the Markdown changes.
What is happening here: Allowing users to simply remember a number (from the original README: 'This style library turns "selecting images by feeling" into "remembering a number".'). build_library.py uses `^\|\s*(\d{3})\s*·\s*([^|]+)\|\s*([^|]+)\|\s*(.*)\|\s*$` to parse Markdown table rows and synchronously generate gallery/index.html. Local verification: styles.json has exactly 261 entries, consecutively numbered 001–261.
The output contract is minimalist and strict: a fixed four-section output (selected style / Chinese prompt / English prompt / one-line explanation), requiring the prompt body to begin with `风格名称：#{编号} · {generation_name}。` and `Style name: #{number} · {generation_name}.`.
handdraw-style-prompter/SKILL.md
For a valid request, return these four parts: 1. Selected style: number and generated style name. Do not output a core-visual-traits field by default for ordinary prompt-only requests. 2. Chinese prompt: begin the copyable prompt itself with `风格名称：#{编号} · {generation_name}。`; describe only the user's theme and constraints explicitly provided by the user, and always include the indexed author/style name as a short `参考作者/风格名称` label. Do not append core traits, the fixed style anchor, extra style adjectives, generic composition advice, quality claims, or negative prompts. 3. English prompt: begin the copyable prompt itself with `Style name: #{number} · {generation_name}.`; describe only the same theme and user-provided constraints, and always include the indexed author/style name as `Reference author/style name`. Do not append visual-trait prose, generic composition advice, quality claims, negative prompts, or the fixed style anchor. 4. A brief note: the prompt can be pasted into any image AI; generation is controlled by that AI.
What is happening here: Anchoring "style name + number" as a reproducible identifier in the prompt header, while strictly prohibiting appended core traits, fixed style anchors, extra style adjectives, generic composition tips, quality statements, and negative words—output discipline itself is the key distinction between this skill and "casually asking a model to write prompts".
No images are generated by default; image generation mode is triggered only when the user explicitly requests generation/rendering/preview, resolving the current image model's capability against the full transmitted text (indexed artist name + generation style name), rather than relying on artist fame or living status.
handdraw-style-prompter/SKILL.md
When the user explicitly requests image generation, first resolve the current image model (or model family) against `references/model_capabilities.json` or the equivalent runtime capability metadata. The decision uses the complete text that will be sent to the model: the indexed author name plus the generated style name. It is not based on the author's fame or life status.
Three-tier decision logic: name_activation=strong → send only artist name + style name + subject; otherwise traits_activation=strong and core traits exist → append only positive, concrete visual traits; if neither holds → transmit the corresponding numbered reference image. Unknown models fall back safely to unknown, requiring an image upload.
Model capability lists are data-driven rather than hard-coded: references/model_capabilities.json uses a schema_version/description/default/models structure to specify whether a given model can activate a number purely by name, defaulting strictly to unknown + requiring reference image upload.
handdraw-style-prompter/references/model_capabilities.json
"description": "Model-specific ability to activate a numbered style from its name. Unknown models must use the image fallback.", "default": { "name_activation": "unknown", "use_reference_image": true, "note": "No verified model capability is available. Pass the numbered image."
Local verification: default.name_activation='unknown', use_reference_image=true. Currently contains one evaluation round for gpt-image-2 (123 numbered entries: 78 name_activation=strong, 45 none); remaining numbers automatically fall back to traits or reference-image branches—missing data does not produce errors, but gracefully degrades to the safer image-upload path.
Decision logic is implemented via scripts and is reproducible: resolve_reference.resolve() validates number ranges and value domains (ALLOWED = strong/weak/none/unknown), returning activation_source (name+style / name+style+traits / reference-image) and filtered prompt_traits.
handdraw-style-prompter/scripts/resolve_reference.py
return "；".join(kept) def get_reference_path(number: str) -> str: reference_grid = grid_path(number) return str(reference_grid if reference_grid.exists() else single_path(number)) def resolve(model: str, style: str, policy: dict | None = None) -> dict:
What is happening here: Turning "whether to upload a reference image" into a deterministic decision that outputs printable JSON, preventing the model from improvising arbitrarily each time. Note that positive_traits() strips clauses containing "avoid/do not/must not" (matching requirements on line 29 of SKILL.md). The script cannot run currently due to missing root scripts/ modules; see the discrepancy item in verification.second_pass.
When uploading a reference image, a "reference image isolation block" must be injected: specified in bilingual Chinese/English to extract only style traits such as lines, brushwork, medium, texture, and color tendencies, explicitly barring replication of subject, characters, clothing, props, poses, scenes, composition, text, or story, with the user theme as the sole content source.
handdraw-style-prompter/SKILL.md
- When an image is passed, inject the following reference-isolation block into the actual image-generation prompt. It is required for every reference-image generation and is not added to ordinary prompt-only output: Chinese: `所附图片仅用于参考画风。只提取参考图的风格特征，例如线条、笔触、媒介、材质、色彩倾向和整体视觉语言；不要使用、复制或延续参考图中的任何主体、人物、动物、服装、道具、动作、姿态、场景、背景、构图、布局、文字或故事。最终画面内容完全以用户提供的主题为准。` English: `Use the attached image only as a style reference. Extract only its stylistic qualities, such as linework, brushwork, medium, material texture, color tendencies, and overall visual language. Do not use, copy, or carry over any subject, person, animal, clothing, prop, action, pose, setting, background, composition, layout, text, or story from the reference image. The user's written theme is the sole source for the image content.` - The user's theme is the sole source for subjects and narrative; the reference image must never override or add content to the theme.
This directly counters the practical failure mode where image-to-image locks down reference image content; lines 24/26 of SKILL.md provide ready-to-paste bilingual blocks and mandate injection only when an image is actually uploaded, excluding it from standard prompt-only outputs.
Session initialization relies on the host MCP: opens the local gallery (file:///E:/handraw-style/handdraw-style-prompter/gallery/index.html) as a visual index during the first invocation in a Codex task/thread, falls back to a local link upon failure, and avoids duplicate opens or writing state files.
handdraw-style-prompter/SKILL.md
1. If this task has not already displayed the gallery, call `mcp__codex_app__open_in_codex` with `target: { type: "browser", url: "file:///E:/handraw-style/handdraw-style-prompter/gallery/index.html" }` so the rendered gallery opens in the in-app browser. 2. Continue with the user's request after the browser call; opening the gallery must not block prompt generation or an explicitly requested image-generation follow-up. 3. Do not repeat the browser call on later turns in the same task/thread. Use the conversation context (not a persistent state file) to determine whether initialization already happened. 4. If the browser call is unavailable or fails, provide this fallback link: [打开手绘风格编号画廊](file:///E:/handraw-style/handdraw-style-prompter/gallery/index.html), then continue normally.
What is happening here: Front-loading gallery browsing to session startup reduces the user's overhead in describing styles. Line 39 explicitly specifies using conversation context rather than persistent files ('Use the conversation context (not a persistent state file) to determine whether initialization already happened'), avoiding disk pollution.
Resource resolution rules are built-in: a 4-grid reference image for a given number takes precedence over a single image, with paths bucketed per 200 numbers (e.g., 201-400); if images are missing, report limitations and fall back to text-only prompts, never fabricating or substituting reference images.
handdraw-style-prompter/SKILL.md
- If the numbered image is missing or cannot be passed, report that limitation and provide the normal text prompts; never invent or substitute a reference image.
Local verification: images/individual/001-200 contains 200 individual images, 201-400 contains 61 images (201–261), plus 45 *_grid.jpg files (numbers 217–261); Windows absolute paths in SKILL.md (E:\handraw-style\…) differ from actual relative repository paths, reflecting author-specific local paths.
2Core Capabilities
01Number 001–261 → bilingual prompts (Chinese starts with 「风格名称：#编号 · 生图名。」, English starts with 「Style name: …」, both labeled with reference artist/style name)
02Offline numbered gallery: single-file HTML filterable by number/style name/original reference name, with images pointing to repository collages
03Model-capability-aware reference image strategy (three-tier name+style → name+style+traits → reference-image + unknown fallback to image upload)
04Mandatory injection of reference image isolation block (bilingual EN/ZH) to prevent reference content from locking down the subject
05Deterministic CLI drafting: prompt_style.py prints four-section bilingual prompts directly from number + subject (the only functional CLI locally)
06Index rebuilding and invariant validation scripts: build_library.py (writes styles.json + gallery) and validate_library.py (checks sequential numbering, 018 mapping, deceased sources, capability domains, unknown model image requirements)
07First-invocation session initialization opening the local gallery (host MCP browser), falling back to local links upon failure
08Negative trait filtering: retains only positive visible traits when using traits, stripping clauses containing "avoid/do not/must not"
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| api | 宿主 MCP 工具 mcp__codex_app__open_in_codex（在 Codex 应用内浏览器打开本地 file:// 画廊；skill 自身不含网络调用） |
| api | 外部图像生成工具（由宿主/用户提供；传参考图时使用其 referenced_image_paths 参数）——skill 只产出提示词与路径建议，不调用任何图像 API |
| cli | python3（运行 build_library.py / prompt_style.py；split_contact_sheets.py 另需 Pillow/PIL） |
| package | Pillow（PIL）——仅 split_contact_sheets.py 用于切分拼图为编号单图；非运行提示词所需 |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Executes local scripts or commands: scripts/build_library.py (rebuilds styles.json and gallery/index.html — writes to referenc
- 本地工作目录: File read/write and artifact output: build_library.py overwrites handdraw-style-prompter/references/styles.json and handd
Audit Notes: The skill consists of Markdown instructions and local Python tools: no network calls, no credential reading, and file writes are restricted to repository artifacts (styles.json, gallery/index.html, sliced individual images). The only external interaction is the host MCP opening a local file:// gallery in-app and passing paths to external imaging tools. Classified as Blue (local tools / local read-write only) rather than Green, as it contains executable scripts and performs local writes.
5Second-Pass Verification
- [ok] style 索引与编号连续性 — styles.json 261 条，首条 001 Gemma Correll / Playful Deadpan Doodle，末条 261 OscarAI；validate_library.py 亦硬断言 [number] == 连续 001–261 且 018 必须映射 'Minimal Deadpan Dialogue Cartoon'。
- [ok] 画廊离线自足 — gallery/index.html 中 http(s):// 字面量 0 命中，img/button data-src 全部为 ../../images/<sheet>.png 相对路径，无 CDN/字体/统计外链。
- [discrepancy] SKILL.md 的 Utilities 命令可运行性 — `python scripts/resolve_reference.py --model <model> --style <number>` 实跑报 ModuleNotFoundError: No module named 'style_asset_paths'（脚本把仓库根 <repo>/scripts 插入 sys.path，但该目录与模块不存在，git ls-tree 全仓库无该文件）。同一缺失还被 split_contact_sheets.py 与 validate_library.py 引用（后者另需 contact_sheet_registry）。故 SKILL.md「Utilities」5 条命令中，仅 build_library.py 与 prompt_style.py 当前可运行；这是仓库在 pin commit 上的真实缺陷，非本报告的定位问题。
- [ok] 模型能力清单的覆盖面 — model_capabilities.json 仅 gpt-image-2 一轮清单、123 条编号条目（strong 78 / none 45）；未列编号走 resolve() 的 entry 继承 default（unknown + 传图），即保守回退。SKILL.md 第 12-19 行的三级决策与代码分支逐条对应（name+style / name+style+traits / reference-image）。
- [ok] 「与作者名气无关」的声明与代码一致 — 决策只读 name_activation/traits_activation 两个字段，代码中不存在任何依赖 attribution.json（名气/在世状态）的分支；attribution 仅被 validate_library.py 用于「deceased 必须带 source」的完整性断言。
- [discrepancy] 图片资产覆盖与文档一致性 — 实跑 find 统计：images/ 下 19 张分组拼图 + 单图 200 张（001–200 桶）+ 61 张（201–400 桶 = 201–261）+ 45 张 *_grid.jpg（编号 217–261），合计 325 个受控图片文件＝git ls-files 中 images/ 的条目数。但 MANIFEST.md 的「已收录图片」只登记 16 张拼图（止于 G_201-216.png），且仍写「images/individual/201-400/201.png–217.png：201–217 的编号单图」「风格编号覆盖：001–217」「当前无缺失编号段」，README/SKILL.md 已按 001–261 描述。判定：MANIFEST.md 为滞后文档，能力面以 261 为准。
- [discrepancy] 路径可移植性 — SKILL.md 第 21 行把参考图根写死为 `E:\handraw-style\images\individual\{bucket}\{number}.png`，第 37/40 行画廊链接为 `file:///E:/handraw-style/...`；这两处只在作者本机成立（本仓库实际位置为 <repo>/images/individual/...）。跨平台使用需按仓库根改写这三处。
- [ok] 无网络外发与凭证读取 — 对 5 个脚本与 SKILL.md/agents/openai.yaml 扫描 http/fetch/requests/urllib/socket/api_key/token/secret：脚本侧 0 命中；SKILL.md 唯一外部动作为宿主 MCP 打开 file:// 本地文件与把路径交给图像工具。resolve_reference 的能力数据来自本地 JSON，不需要联网查询模型能力。
6Verdict & Scenarios
Best for: Ideal for creators managing art styles by index numbers and seeking stable bilingual prompts (WeChat Official Accounts, Xiaohongshu, short videos, branded content); ideal for Codex users capable of calling mcp__codex_app__open_in_codex (for startup gallery initialization); ideal for skill authors looking to study data-driven style libraries and capability-table-driven reference image strategies.
Not for: Not suitable for pipelines requiring out-of-the-box automated validation (3 Utilities commands currently fail due to missing modules and require root scripts/ modules first); not suitable for non-Windows environments unwilling to modify hard-coded absolute paths; not suitable for commercial use requiring explicit open-source licensing (missing LICENSE); not suitable for users expecting direct image generation (produces prompts by default, requiring external tools for rendering); not suitable for users outside Codex expecting automated gallery initialization.
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload handdraw-style-prompter.tar.gz
sha256:
Option B · Copy Guide for Agentb025e1b5b2a3616d…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 70bf51d6b4.