Apple appicon

apple-appicon

One source image in, HIG-correct icon sets out. Agent-agnostic: nothing here depends on a specific coding agent — only on a shell. Commands write <skill-dir> for this skill's directory; resolve it to wherever your agent installed the skill (Claude Code exposes it as ${CLAUDE_SKILL_DIR}; otherwise it is the directory containing this SKILL.md). The working directory is the user's project.

Requirements — check the platform first. The native toolchain is macOS: sips, iconutil, swift from Xcode Command Line Tools, no installs. Run uname -s (or equivalent) before promising anything, and on anything other than macOS tell the user up front, in plain terms, what works on their machine and what doesn't — then proceed with what does:

• macOS → everything below, natively.
• Linux / Windows (WSL or Git Bash) → Tauri projects keep full support: tauri icon is Rust and cross-platform, .icns included, and the margin fix routes through it (references/tauri.md). Asset-catalog PNGs and Contents.json files need ImageMagick 7 — command equivalents are in the "Non-macOS fallbacks" section of references/platform-recipes.md. A bare .icns outside a Tauri project is the one thing that genuinely needs png2icns, a Mac, or CI — say so rather than approximating.

Never discover a missing sips mid-run: state the limitation before generating, and never silently drop the macOS margin treatment because the native tool is absent.

Step 0 — establish source and targets

• Source: the image path from the arguments or conversation. No path → ask for one; never invent or generate artwork unless the user asks.
• Targets: --platform wins. Otherwise detect: src-tauri/tauri.conf.json → tauri; an .xcodeproj/Assets.xcassets → the Xcode platforms it targets; neither → ask, defaulting to all written under ./AppIcons/<platform>/. --out overrides the destination. ipados is the ios recipe (universal appiconset).

Step 1 — validate, then look at it (gate)

bash "<skill-dir>/scripts/validate-source.sh" <source>

Show the PASS/WARN/FAIL output. On FAIL (not square, <512px, unreadable): stop, present the fix commands the script printed (crop vs pad for aspect; re-export for resolution), apply the one the user picks, re-validate. Never generate from a failing source. WARNs are stated, not blocking.

Then, if your agent can view images, look at the source and check it against the design advisories in references/apple-hig.md: pre-rounded corners or baked shadows (double-masking risk), thin lines that die at 16px, text, photographic content. Report what you see in one or two sentences; advisory only. No image input? Say the visual advisories were skipped and ask the user to eyeball that list themselves.

Step 2 — generate per target

Read references/platform-recipes.md for the exact commands and asset-catalog templates; for Tauri read references/tauri.md. The shape rules that must never be mixed up:

Target	Output	Shape treatment
iOS / iPadOS	AppIcon.appiconset, 1024 single-size (+ dark/tinted)	full-bleed square; marketing icon flattened, alpha stripped
macOS (Xcode)	AppIcon.appiconset, 10 sizes	margined rounded-rect via appicon.swift macos
macOS (.icns)	icon.icns via iconutil	same margined treatment
visionOS	AppIcon.solidimagestack	full-bleed square layers; system applies circular mask
Tauri	full src-tauri/icons/ set	tauri icon for everything, then rebuild icon.icns margined

Square, system-masked platforms (iOS/iPadOS/visionOS) get no baked corners or margins; only legacy macOS .icns does. The scripts/appicon.swift modes — resize, flatten (opaque, alpha-stripped), pad (square-ify), macos (824/1024 rounded rect + margins + shadow) — cover every transform; sips is fine for plain resizes too.

Before overwriting an existing AppIcon.appiconset or src-tauri/icons/, say what will be replaced; back up or get a nod if the user didn't already ask for exactly that.

Step 3 — verify and report

• sips -g pixelWidth -g pixelHeight spot-checks; the iOS marketing icon must report hasAlpha: no; file icon.icns says "Mac OS X icon".
• If you can view images: open the finished macOS 1024 and one small size — margins present, corners clipped, artwork not visibly soft. Otherwise point the user at qlmanage -p / Finder Quick Look for the eyeball check.
• Report a table: file → pixel size → where it's wired (Contents.json, tauri.conf.json bundle.icon, ASSETCATALOG_COMPILER_APPICON_NAME), plus any HIG advisories from Step 1 worth acting on. For Tauri, suggest a tauri build to see the real Dock icon (dev mode uses the PNGs).

Scope

watchOS and tvOS are out of scope in v1 (geometry noted in references/apple-hig.md). Layered Liquid Glass .icon bundles are Icon Composer's job — generate the flat baseline and point the user there when relevant. Framework roadmap (Flutter, React Native, Ionic/Capacitor) and the interim answer for those users live at the end of references/tauri.md.

Sources

Apple HIG · App icons, Tauri v2 icon docs (both distilled in references/). Workflow shape inspired by brianlovin's favicon skill (validate → generate → wire up) and michaelboeding's icon-generation.