| name | mouse-pointer-theme-maker |
| description | Use when a user wants a custom macOS or Windows mouse pointer theme from a reference image, original mascot, or named character/IP. Create eight original artworks, expand them into 51 macOS Mousecape cursor IDs or 15 Windows cursor roles, show a high-resolution PNG preview before packaging, and provide guided installation. Support retro-pixel, chibi-anime, and abstract-expression visual styles. |
Mouse Pointer Theme Maker
Create a polished, consistent dual-platform cursor theme from a reference image or a named character/IP and a style direction. Prioritize clear, correct interaction over decorative detail. Create eight distinct artworks, then expand them to the macOS exact-ID coverage set and, whenever the user requests Windows or cross-platform output, the 15 Windows cursor roles. The expansion reuses appropriate approved art for aliases; it does not ask the user to create or choose 51 separate images.
首次使用提问
On the first invocation of this skill, ask the user for these three inputs before generating art or creating files. If the user already supplied an item, acknowledge it and ask only for the missing items.
- 电脑平台：
macOS or Windows 10/11. This determines which package will be produced; never silently create both.
- 视觉风格：introduce all three choices in plain Chinese:
retro-pixel 复古像素风：16/32 位游戏感、像素轮廓、鲜明色块。chibi-anime Q 版二次元风：大表情、圆润比例、可爱的角色配件。abstract-expression 抽象表达风：用夸张、视觉隐喻、超现实幽默、民俗插画感或表情包反应表达主题，不局限于恶搞。
- 主题/角色与鼠标皮肤样式：询问想做的 IP/角色、参考图、配色和整体感觉；可以只说角色名，也可以上传图片。说明要做的是“角色融入鼠标功能”的整套皮肤，而不是把人物图片直接贴在箭头上。
回答示例：
电脑：macOS
风格：abstract-expression 抽象表达风
主题/角色：甄嬛传，用夸张宫斗动作和表情包节奏表现；正常、输入、点击、不可用、忙碌、移动、左右调整、上下调整这 8 个状态都要有。主色想要米白、朱红和玉绿色。
Collect input
Ask for a theme name only if absent. Accept either a user-provided character reference image or a named character/IP; do not require both. Treat a named IP as a visual brief, never claim the generated result is official. Default to chibi-anime if no style is given. Use a safe identifier such as com.example.<theme-name>.
Read references/styles.md before creating art. Offer these three styles:
| Style | Direction |
|---|
retro-pixel | Detailed 16-bit/32-bit pixel UI, character expressions and readable pixel silhouettes |
chibi-anime | Q-version anime mascot, lively expressions and cohesive accessories |
abstract-expression | Exaggeration, visual metaphor, surreal humor, folk-art energy, or meme-like reactions |
Generate the eight original artworks
Use image generation with the reference image and a transparent background. Create these eight states as separate square images with the same palette, line weight, proportions, and character treatment. For built-in image generation, request a flat chroma-key background and remove it with the installed imagegen helper before normalization.
| Use | State |
|---|
| ordinary selection | normal |
| text entry | text |
| button or link | action |
| unavailable action | forbidden |
| busy | busy |
| pan canvas | open_hand |
| horizontal resize | resize_horizontal |
| vertical resize | resize_vertical |
Read references/full-states.md for each visual cue, identifier, and hotspot rule. Then read references/standard-coverage.md: macOS picks precise cursor IDs, so this reference defines how the eight original artworks are expanded into the 51 supported IDs. For Windows or cross-platform output, also read references/windows-installation.md. Read references/complete-tutorial.md before the final delivery: it is the mandatory beginner-facing installation, verification, troubleshooting, and restore guide. Treat the hotspot as a non-negotiable interaction contract: it must sit on the arrow tip, I-beam centre, fingertip, or symbol centre as specified. Keep it free of faces, decorations, text, effects, and props. For character art, place the character behind or beside the functional cue; do not replace an arrow, I-beam, hand, or resize arrow with a portrait.
Generate larger working images if needed. For every state, export four internal Retina representations from the original artwork: 32×32, 64×64, 160×160, and 320×320 PNGs (1x, 2x, 5x, 10x). These are automatic display-density resources for one cursor, not user-facing skin variants: never ask the user to choose a scale. Do not upscale the 32×32 result; render or resample each representation directly from the larger source. Keep the intended hot point free of decorative parts.
After cropping each source image, inspect all four edges at 100% before resizing. A crop is invalid if an adjacent cell, guide, border, or isolated 裁剪边缘残留线条 appears on any edge; recrop within the single cell and regenerate all four representations. Never ship a cursor with crop-edge residue, even if the line is only one pixel wide or is reused by an alias state.
macOS applications choose cursor types; Mousecape does not identify semantic controls such as a close button when an application still requests the normal arrow. Map close-like or unavailable treatment only to the forbidden state.
Preview approval gate
Before packaging, make a single 卡片式 PNG/JPG preview sheet. It must show exactly the eight agreed states as a 4×2 themed card grid: theme title, Chinese state name, state identifier, large cursor art, and a red hotspot cross on every card. The user-facing image must be at least 2440×1388. Render the large card art from the approved 10x Retina representation and downsample it for display; never enlarge the 32×32 1x PNG, which makes detailed art look blurry. The hotspot must still use the 32×32 coordinate ratio. Use theme.preview_style in the manifest (retro-pixel, chibi-anime, or abstract-expression) so the card palette matches the requested art direction. The preview is an approval artifact, not a raw engineering contact sheet: keep generous card spacing, clear hierarchy, and no extra alias states.
**交付顺序必须固定：**先发送 PNG/JPG 预览图给用户确认，确认前不得发送 .cape、压缩包、Mousecape 下载地址或安装教程。preview.svg 只作为内部可编辑源文件（preview.svg 只作为内部），不作为用户确认图。只有用户明确回复“可以”“确认”“就这样”等同意词后，才生成并发送安装文件，再给安装教程（确认后再发送）。Do not build a .cape before approval. 若用户要求修改，只改指定状态并重新输出 PNG/JPG 预览，不进入打包步骤。
预览阶段使用独立渲染命令，不会生成安装包：
python3 scripts/render_preview.py --manifest <theme-dir>/artwork-manifest.json --output <theme-dir>/preview.png --svg-output <theme-dir>/preview.svg
Show preview.png to the user and wait for explicit approval. PNG 使用 2x 卡片画布与 10x 状态资源缩放，确保文字、角色线稿和热点十字清晰。
render_preview.py 和 build_cape.py 会自动检查最大 Retina 图的 safe transparent border：四边任一处的非透明像素贴到裁剪边缘时，必须拒绝生成预览和安装包。此时从未裁切的原图重新取图、保留透明边距，并重新生成四个尺寸；不要通过缩放或忽略报错绕过检查。
红色十字是预览专用的热点校准标记，只用于让用户检查箭头尖端、I-beam 中心或手指点击点；它以及任何红色框选/标注都不得写入状态 PNG、.cape 或 Windows .cur 文件。安装后的鼠标只显示角色与功能图形。
For a public GitHub gallery, use the same complete high-resolution 4×2 PNG preview rather than a raw sprite sheet. Keep one curated example for each supported style, use repository-relative image paths, and never include user source references, generated install archives, or third-party application binaries. A gallery example must pass the same hotspot, safe-border, clipping, and crop-residue review as a user delivery.
Package after approval
先确认用户平台
The platform should already be recorded during 首次使用提问. If it is still missing when the user approves the preview, ask one concise question before creating any install archive: “你使用的是 macOS 还是 Windows？” Do not guess from the conversation or package both platforms automatically. Record the answer as macos or windows and build only that platform. If the user explicitly needs both, create two separately named packages and two separately named archives; 不要把 macOS 与 Windows 打进同一个压缩包. The platform question must happen before writing a .cape or running the Windows builder.
-
Copy assets/essential-theme-manifest.json into one output directory as artwork-manifest.json. Replace the template theme fields with the user’s name and author, set theme.preview_style to the chosen art style, then set each path and representations list to its PNG filenames. The list must contain the 1x, 2x, 5x, and 10x files in that order.
-
Run scripts/prepare_cursor.py for every representation. Use --scale 1, --scale 2, --scale 5, and --scale 10; use --resize only when a source has the wrong dimensions. Preserve its alpha channel.
-
Build the macOS package after the PNG/JPG preview is approved:
python3 scripts/expand_standard_coverage.py --manifest <theme-dir>/artwork-manifest.json --output <theme-dir>/manifest.json
python3 scripts/build_cape.py --manifest <theme-dir>/manifest.json --output <theme-dir>/<theme-name>.cape --preview <theme-dir>/preview.svg
-
If the confirmed platform is Windows, build its 15-role package from the same approved artwork-manifest.json:
python3 scripts/build_windows_cursor.py --manifest <theme-dir>/artwork-manifest.json --output <theme-dir>/windows
Do not run the generated PowerShell script yourself. Deliver it only after the user has reviewed the art. Read references/windows-installation.md before describing installation.
-
Verify the macOS package:
python3 scripts/validate_cape.py <theme-dir>/<theme-name>.cape
python3 scripts/validate_hotspots.py --manifest <theme-dir>/manifest.json --preview <theme-dir>/hotspot-preview.svg
If validation fails, repair only the reported state and rerun the build. Do not overwrite an existing .cape file unless --force is intentional.
Install-ready delivery
Deliver only the confirmed platform. For macOS, include the .cape, all Retina PNG representations, manifest.json, the user-facing preview.png, and hotspot-preview.svg. Keep preview.svg only as an optional internal/editable source; never present it as the approval preview. For Windows, include the 15 .cur files, install-current-user.ps1, restore-default.ps1, and README-Windows.md. Inspect the hotspot preview before delivery; if a cross is not on the intended functional point, repair that state instead of shipping it. Verify a macOS cape has HiDPI: true and four PNG representations per cursor at 32, 64, 160, and 320 pixels.
After preview approval, platform confirmation, and packaging, always give a complete tutorial in the final response. Follow references/complete-tutorial.md exactly: state the actual delivered filenames first, then give the confirmed platform’s “from download to apply”, immediate verification, troubleshooting, and restore steps. Do not merely say “see the README”, do not make the user guess which file to open, and do not combine platform archives. The tutorial must explicitly distinguish common states (arrow, text, action, window-edge resizing) from low-frequency states (busy, unavailable, handwriting), so a user does not mistake app-specific cursor behavior for a broken skin.
Describe the four core states (normal, text, action, forbidden) as the reliable package baseline. State that the package also maps exact directional resize, wait, drag, zoom, help, and system-arrow aliases. Explain the remaining boundary precisely: macOS apps request cursor types independently, and apps that draw their own cursor or keep using the normal arrow cannot be overridden by Mousecape. A disabled button or close button commonly remains an arrow because it has not requested forbidden.
For modern macOS, direct the user to the official upstream Mousecape SwiftUI Releases page instead of the obsolete Mousecape 1813 build. Never download Mousecape into the generated theme directory, bundle it in a delivery archive, mirror it, or redistribute its application binary. Mousecape has its own non-commercial/no-redistribution license; users must obtain it from the upstream project and review those terms themselves. Never claim the app is installed or applied unless it actually was. Explain Gatekeeper recovery (control-click → Open) only if macOS blocks the app. If an install step fails, report the exact screen message and proceed with the corresponding troubleshooting section in the installation reference.
Mention that Mousecape uses non-public macOS APIs, so compatibility can vary after a macOS update. Also explain that apps choose cursor types: a close button can still show the normal arrow if the app never asks for the forbidden cursor.
For Windows, target Windows 10 and 11 only. Explain that users must extract the package somewhere permanent, then voluntarily right-click install-current-user.ps1 and choose Run with PowerShell. The script writes only current-user cursor values (HKCU\\Control Panel\\Cursors) and does not require administrator permission. Give the restoration step (restore-default.ps1) in the same answer. Do not promise every Windows application will show low-frequency Busy, AppStarting, No, or handwriting states.
