技能图标生成器（Skill Icon Generator）

概述（Overview）

为技能（skill）、插件或任何工具一键生成干净、扁平的 512x512 SVG 图标——自动分类、配色、从精选元素库中组合构图。输出为矢量文件，无 AI 生成痕迹，可直接上传到 SkillHub 或任何图标平台。

Generate clean, flat 512x512 SVG icons for skills, plugins, or any tool — automatically classified, palette-matched, and composed from a curated element library. The output is a vector file with zero AI-generation artifacts, suitable for direct upload to skillhub or any icon platform.

When to Use

Trigger this skill whenever the user:
- Asks to create or generate an icon for a skill or tool
- Needs a 512x512 icon for skillhub or similar platforms
- Wants to refresh or replace an existing skill's icon
- Provides a SKILL.md and asks for "a matching icon"

Do NOT use when:
- The user wants a complex illustrated/3D logo (use ImageGen directly)
- The output is not an icon (avatars, banners, photos)
- The user wants to edit an existing icon (use a vector editor)

Known Limitation: icon must be uploaded manually, and as PNG/JPG

This skill generates the icon (SVG), but two platform boundaries apply:

1) No CLI upload channel. SkillHub's CLI does not expose icon upload — the platform's GET /api/v1/skills/{slug} returns iconUrl: null for CLI-published skills.

2) The upload slot only accepts PNG/JPG — NOT SVG. (Verified 2026-09-09.) The SkillHub web upload field rejects .svg. You must rasterize first.

After running icon_gen.py and publishing via CLI:

1. Convert icon.svg → 512×512 PNG or JPG — python scripts/svg_to_png.py icon.svg (bare Pillow, no Chrome/cairo needed; add --jpg for JPG, --check for a self-test)
2. Go to https://skillhub.cn → log in → my skills → find your skill
3. Open the skill's edit page
4. Upload the PNG/JPG as the icon

These are SkillHub platform boundaries, not limitations of this generator. The CLI handles all programmable assets (code, metadata, version); visual assets are intentionally kept as a manual step, and the icon slot specifically requires a raster format.

Quick Start

From a SKILL.md

python scripts/icon_gen.py /path/to/skill-directory
# → outputs /path/to/skill-directory/icon.svg

Inline mode (no SKILL.md)

python scripts/icon_gen.py \
  --name "代码审查" \
  --summary "自动审查 PR 代码" \
  --desc "使用静态分析和 AI 审查 PR 中的代码问题" \
  --out icon.svg

Force a specific element / palette

When two skills have very similar SKILL.md text (so automatic matching would
necessarily pick the same element), pin them explicitly:

python scripts/icon_gen.py ./my-skill --element skill-dashboard
python scripts/icon_gen.py ./my-skill --palette purple-violet

Discovery commands

python scripts/icon_gen.py --list-elements    # 117 SVG elements
python scripts/icon_gen.py --list-palettes    # 8 color palettes
python scripts/icon_gen.py --json             # machine-readable output

FAQ（常见问题与反模式）

Q1：生成图标后 SkillHub 上还是旧图标 / 没图标，怎么办？
本工具只生成 icon.svg，不会自动上传。SkillHub CLI 不开放图标上传通道，生成后需登录 https://skillhub.cn → 我的技能 → 打开编辑页 → 上传图标。注意：上传槽位只收 PNG/JPG，SVG 会被拒，先用 Q7 的方法转成 512×512 PNG。这是平台边界，非工具缺陷（见上方 Known Limitation）。

Q2：图标出来不是我想要的行业风格，能改吗？
能。原因是分类/元素没命中。优先改进输入：--name 用技能/店铺主题，--summary/--desc 写清品类与关键词；仍不满意就直接用 --element 指定元素（--list-elements 查 id），或直接编辑 SVG（矢量可拖入 Figma/Illustrator 改色改元素）。If the style misses, enrich --name/--summary/--desc, or pin --element explicitly.

Q3：能做复杂 3D logo、插画或把现有图换个风格吗？
不能，这是 Do NOT use 场景。本工具专注扁平 512x512 图标，不做 3D/插画/编辑现有图；这类需求请直接用图像生成或矢量编辑器。

Q4：每个图标只能放一个元素，不够丰富怎么办？
当前库单图标选一个最贴合元素（117 个可选）。想更丰富可用多个相关元素组合后人工编排出"主题系"，或用 --name 描述主次（如"购物袋+礼盒"），再手动微调 SVG。

Q5：输出一定符合 512×512 / SkillHub 规范吗？
是。每个输出 viewBox="0 0 512 512"、扁平无渐变无 3D、白底、含描边风格——符合 SkillHub 图标规范可直接使用。若平台有裁切，可自行按需调整外留白。

Q6：中英文、垂直行业（物流/宠物/展会/3D打印）都能识别吗？
能。内置中英文混合分词与关键词库，并已补充 物流货运、宠物动物、展会会展、3D打印建模、图标矢量、技能运营、AI Agent、知识管理、办公效率（表格/PPT/PDF/会议）、开发编程（前后端/CI/测试/Git）、商业运营（CRM/增长/SOP）、金融、生活服务、行业专业（财税/政务/风控/法律） 等多族垂直词与对应元素；元素选择采用「专指度加权」，垂直元素（如宠物爪印 spec=3.2）优先于泛用元素（如拼图块 spec=0.35）。已对 7 个真实上架技能实测 7/7 命中。

Q7：怎么把生成的 SVG 转成 SkillHub 能收的 PNG/JPG？
本机无 Chrome、cairosvg 缺 cairo 原生库不可用，推荐两条路：
- 最省事：直接跑随包脚本 —— python scripts/svg_to_png.py icon.svg（批量：svg_to_png.py --outdir ./out *.svg，要 JPG 加 --jpg）。自带轻量渲染器，只依赖 Pillow，无需安装 cairo；加 --check 会输出像素统计 + 连通域 + ASCII 预览做自检。
- 手动：有浏览器时直接打开 icon.svg，截图或导出 512×512 PNG。

原理：本元素库只用扁平纯色图元（rect/circle/ellipse/path/line/polygon/polyline），Pillow 足够复刻，4× 超采样 + LANCZOS 下采样即可得到平滑边缘。

Q8：两个技能的 SKILL.md 写得很像，图标会撞吗？
会——这是预期的，不是 bug。自动匹配只能看文本，文本相似则元素必然相同。解决方案：用 --element 显式给其中一个指定不同元素。更根本的建议：如果两个技能文本像到这个程度，说明它们的功能定位可能真的重叠，建议考虑合并或明确切分。

Q9：SkillHub 上出现新类型技能，但库里的元素配不上，怎么办？
用随包巡检脚本定位缺口，别凭感觉加元素：

python scripts/coverage_audit.py --md /tmp/coverage.md --json /tmp/coverage.json

它会把 SkillHub 的全量分类体系（13 个一级 × 8 个二级 = 96 个子分类）与本地 assets/elements.json 逐条比对，再抽样真实在架技能跑一遍分类+选元素管线，输出：无覆盖 / 弱覆盖子分类清单、低分技能样本（图标会「随便挑个不相关图形」的那批）。只读，不改库。
看报告补元素时注意两点：① 新元素要给一个配得上的 specificity（正典 2.2~2.6，纯装饰 <2.0），否则补了也会被压分；② 别给高专指度元素塞过泛关键词（如「管理/运营/分析」），它会抢走不属于它的技能——这类关键词应放在泛用元素或专用元素上。

Q10：生成的元素跟我预期的不一样，是选错了吗？
不一定是错。选择顺序是「同类优先 → 弱匹配时跨类兜底」：先在技能所属类别（tool/content/data/communication/learning/visual）里选；只有同类最高分低于 8.0（说明该类别里没有真正贴题的素材）时，跨类别的元素才会参与竞争。所以：
- 元素来自另一个类别 → 通常说明技能被分到了不太贴的类别。补 --name/--summary 里更明确的关键词即可，或用 --element 直接钉死。
- 元素来自同类但明显不贴 → 多半是该领域在元素库里还缺一个更专指的图形，可用 Q9 的巡检脚本定位，或在详情页评论区反馈。

反模式速查（避免）

• ❌ 期待一键自动置顶到 SkillHub（无上传通道）
• ❌ 把 SVG 直接传 SkillHub 图标位（只收 PNG/JPG）
• ❌ 用 3D/插画/照片类需求调用本工具
• ❌ --name/--summary 语义模糊（分类易跑偏）
• ❌ 依赖"模型凭记忆补元素"而不用关键词库
• ❌ 满足于没有复查的首次输出（配色/元素可能不贴题）

正确做法速查

• ✅ 生成后转 PNG/JPG，再到网页后台手动上传
• ✅ --name 写明主题、--summary/--desc 写清品类与关键词
• ✅ 两个相似技能用 --element 显式区分
• ✅ 对输出不满意就重跑或微调 SVG，而不是强改意图
• ✅ 检查输出符合 512×512 规范再上传

使用与版权边界（免责声明）

本技能只生成图形文件（SVG/图标）供你自用，不构成任何商标/品牌/IP 的判断或授权。生成结果可能与你委托描述或既有商标/形象相似——是否真的有权使用某个名称/形象/元素向谁投稿或上架，是你自己的合规责任：使用前请自行核对是否侵犯他人商标权、著作权、产品或名称专有权，涉及品牌化/商用请按实际情况处理。工具对"生成物的使用方式与后果"不作担保；相应地，本技能作为通用图标生成工具对生成内容本身不构成专业法律意见。

How It Works

The pipeline runs four stages:

1. Parse — Extract name, summary, description from SKILL.md (or use inline args). Tokenize into Chinese bi-grams and English words, with name tokens weighted 2x.

2. Classify — first tokenize, then score against six category dictionaries along with a full-text substring fallback (avoids bigram-segmentation noise), and pick the highest score:
   - tool — automation, build, deploy, code, CLI, dev tools; also 电商/物流/宠物/展会/技能运营
   - content — writing, editing, document, translation, copy
   - data — analysis, statistics, charts, visualization, database
   - communication — chat, email, notification, team, meeting
   - learning — education, course, tutorial, research, study
   - visual — image, video, design, illustration, filter, theme; also 3D打印建模/图标矢量

3. Compose — Pick:
   - A palette (8 fixed palettes: qinglan/mengzi/meiquan/taike/wuan/shenlv/huijie/meigui), chosen by category preference + MD5 hash of skill name for stability
   - A style template (stroke width, corner radius, background shape) per category
   - An element (117 SVG elements) scored as (keyword overlap + full-text substring hits) × specificity. The specificity weight (0.35–3.2) makes domain-specific elements (e.g. paw 3.2, booth 3.0) outrank generic ones (e.g. puzzle-piece 0.35), so a generic word like "技能" can't drag every skill onto the same element. Falls back to the category default.
   Category-first, with a weak-match escape hatch: same-category elements win by default. But when the best same-category score is below WEAK_MATCH_THRESHOLD (8.0) — i.e. nothing in that pool really fits — cross-category candidates are ranked as well, and the strictly-higher one wins. This fixes the "material exists but is unreachable" case: an email skill classified as tool could never reach the envelope living in communication, and used to fall back to a terminal/magnifier.

4. Render — Compose the SVG: white background → optional decorative background shape → element with primary/secondary/tertiary fills from palette.

Substring gate: full-text matching only counts Chinese terms ≥2 chars and English terms ≥5 chars, so ultra-short tokens (ai, ops, ci) can't match at random.

Output Format

Every output is:
- viewBox="0 0 512 512" (matches skillhub spec)
- Valid SVG 1.1
- 300-700 bytes typical
- White background, no gradients, no 3D, no shadows
- Editable: open in any vector editor (Figma, Illustrator, Inkscape)

收尾问体验（踏实做 + 真需要心声 / Try a closing ask）

作者姿态（每次把图标真正取图交付后，自然收尾用上一句，中英按当前对话语言选一种，别生硬）：
> 这图标是我们把一个扁平图库一个字一个字做扎实的，不是赶量堆样式。你是真拿去上架/发笔记的人，图好不好看最主观、你最清楚——配色不合眼缘、元素差了、线条太硬太软，直说，别怕说丑得罪人；你说得越具体，下一个版本的元素库和配色会越贴合真用途。
> If an icon ever misses, tell us straight — off palettes, wrong element, clunky lines. You're the one actually shipping it, so your eye matters most; the more specific, the better the next element library gets.

• 用户愿意展开（说不好看/风格不符/举了反例）→ 认真接住、逐条记下，能马上调就重跑或微调 SVG，再顺带补一句：要是方便，也可以把它留在本技能在 SkillHub 的详情页评论区——作者每天都看，会照着改库里的元素与配色。
• 用户答"挺好/够用" 或赶时间 → 不再追问，自然收尾，全程不催、不索星不索赞。（Ongoing tune-ups? No further nagging once they say it's fine.）
• 本引导只通当前对话 + 平台评论区，上报、采集、自建回传一律不做（This ask lives in the chat and the comment section only — no telemetry, no data collection, no self-hosted callbacks）。本技能也已无任何自动上报/回传（无 usage 段），与「按需手动上传 icon 到 SkillHub」的平台边界并存，勿误会成静默传数据。

Extending

Add a new element

Append to assets/elements.json:

"your-element": {
  "name": "你的元素",
  "category": "tool",
  "specificity": 3.0,
  "keywords": ["关键词1", "keyword1"],
  "svg": "<path d='...' fill='{primary}' stroke='{primary}' stroke-width='{stroke}'/>"
}

specificity（专指度，默认 1.0）决定该元素在与泛用元素竞争时的权重：
- 领域专属元素用 2.0–3.2（如 paw 宠物爪印 3.2、booth 展位展架 3.0）
- 泛用元素用 0.35–0.9（如 puzzle-piece 拼图块 0.35、key 钥匙 0.45）

不填 specificity 时按 1.0 处理。若某元素总是抢走不属于它的技能，调低它；
若某领域元素总抢不过泛用元素，调高它。

注意：svg 中的坐标应以 translate(256 256) 后的原点为中心（如 x='-96' y='-40'），
不要使用 512 画布绝对坐标——否则图形会飞出画布。

Placeholders available in the svg template:
- {primary} / {secondary} / {tertiary} — palette colors
- {stroke} — style's stroke width

Add a new palette

Append to assets/palettes.json:

{
  "id": "your-palette",
  "name": "调色板名",
  "description": "简短描述",
  "preferred_categories": ["tool", "data"],
  "colors": {
    "primary": "#...",
    "secondary": "#...",
    "tertiary": "#...",
    "background": "#..."
  }
}

Add a new category or style

See references/design-notes.md for the full taxonomy and the rules for keeping the output visually consistent.

Resources

scripts/

• icon_gen.py — Main CLI entry point (entry point for the skill)
• svg_to_png.py — SVG → PNG/JPG 转换（自带轻量渲染器，无需 Chrome/cairo，仅需 Pillow）；含 --check 质量自检
• coverage_audit.py — 素材缺口巡检（只读）：SkillHub 分类体系/在架技能 vs 本地元素库，输出无覆盖/弱覆盖清单 + 低分技能样本。⚠️ 它是唯一联网的脚本（向 SkillHub 公开 API 发只读 GET：/categories、/subcategories、/search），只下载公开分类与技能元数据、不上传任何内容、不带身份信息；不加 --no-market 时才会联网，主链路 icon_gen.py 完全离线。属维护者工具，普通用户生成图标时不会触发。
• parser.py — SKILL.md parser + Chinese/English tokenizer
• classifier.py — Keyword-based category classifier
• composer.py — SVG composition engine (palette/style/element selector)

assets/

• elements.json — 117 SVG element templates, organized by category, each with a specificity weight（覆盖电商/物流/宠物/展会/3D打印/图标矢量/AI Agent/知识管理/办公效率/开发编程/商业运营/金融/生活服务/行业专业等垂直图形；version 字段=素材库版本，与 SKILL.md 的技能版本号相互独立）
• palettes.json — 8 color palettes with category preferences
• styles.json — 6 style templates (stroke width, corner radius, background shape)

references/

• design-notes.md — Design rationale, taxonomy decisions, how to extend

素材库维护（Maintainer）

元素库需要跟着 SkillHub 上的技能生态走，固定节奏巡检、按需补元素：

> 联网边界：巡检脚本 coverage_audit.py 会向 SkillHub 公开 API 发只读 GET（分类树 + 技能检索），仅下载公开元数据，不上传、不回传、不携带任何身份信息；加 --no-market 可完全不联网。除此之外本技能无任何网络调用（icon_gen.py / svg_to_png.py / composer.py 全离线），无遥测、无 usage 上报。

1. 巡检：python scripts/coverage_audit.py --md ./coverage.md → 看「无覆盖 / 弱覆盖子分类」和「低分技能样本」两张清单。
2. 判断：无覆盖 = 库里真缺这类图形，补；弱覆盖 = 有元素但不够贴，先想想是不是关键词没写到位，再决定补词还是补元素。
3. 补完必须回归：改完 elements.json 立刻重跑一次 coverage_audit.py 对照，确认缺口缩小且没把别的子分类挤坏（重点看「由有覆盖变低分」的反向变化）。

元素选择是「同类优先，弱匹配（同类最高分 < WEAK_MATCH_THRESHOLD = 8.0）时跨类兜底」（见 classifier.pick_element）。看到某技能选中的元素离题时，先分清是哪种情况：
- 同类命中但分数低 → 这个领域缺更专指的元素，补元素；
- 跨类元素胜出 → 多半是分类判偏，优先补分类关键词（CATEGORY_KEYWORDS），而不是去动元素。
调阈值前请用真实样本回归（classifier.WEAK_MATCH_THRESHOLD 的注释里记了实测分布：正确命中的同类最高分为 12.0~35.2，错误锁定的为 3.2~7.2）。

改库的三条经验（1.3.0 三代迭代总结）：
- 新元素必须给 specificity：正典元素 2.2~2.6、常用 1.8~2.2、纯装饰 <1.8。不给就是 1.0，会被压成低分。
- 别给高专指度元素塞过泛关键词（管理/运营/分析/监控/指标）：它会把整片技能抢过来，1.1.0 清过一轮。
- 短英文关键词（ppt/pdf/git/seo/crm）靠词表精确匹配生效，子串匹配对它们无效（英文门槛 ≥5 字符）——写进 keywords 就行，但别指望同义子串也能命中。