icon-composer

Icon Composer Skill

The icon-composer plugin — tools to create, validate, and render Apple Icon Composer .icon packages. The same package installs three ways: as a Claude Code plugin, a Codex plugin, or a standalone skill via gh skill.

Install

Published at https://github.com/giginet/apple-icon-composer-skill. Pick the host you use — each path installs the same compose-app-icon skill.

Prerequisite: uv on your PATH (the skill runs its bundled Python CLIs through it) — brew install uv.

Claude Code

/plugin marketplace add giginet/apple-icon-composer-skill
/plugin install icon-composer@icon-composer

Then run /reload-plugins once and confirm with / — you should see /icon-composer:compose-app-icon. The @icon-composer suffix names the marketplace declared in .claude-plugin/marketplace.json, disambiguating it from any other marketplaces you have installed.

Codex

codex plugin marketplace add giginet/apple-icon-composer-skill
# then open the plugin directory in Codex, pick the "Icon Composer" marketplace, and install

Backed by the repo marketplace at .agents/plugins/marketplace.json with the manifest at plugins/icon-composer/.codex-plugin/plugin.json. Codex sets CLAUDE_PLUGIN_ROOT for compatibility, so the skill's ${CLAUDE_PLUGIN_ROOT}/skills/compose-app-icon/scripts/... references work unchanged.

GitHub CLI (gh skill)

Requires GitHub CLI v2.90.0+.

# Browse and pick interactively
gh skill install giginet/apple-icon-composer-skill

# Or install it directly for a given host
gh skill install giginet/apple-icon-composer-skill compose-app-icon --agent claude-code

The skill is self-contained: its scripts/ directory is a uv project bundling create_icon.py, validate_icon.py, icon-schema.json, and uv.lock, so gh skill copies the whole working toolset — not just the instructions. Outside a plugin host, ${CLAUDE_PLUGIN_ROOT} is unset, so run the CLIs from the installed skill's scripts/ directory (the SKILL.md explains this); uv is still required.

Skill

One skill, compose-app-icon, covers authoring, validation, and rendering:

Triggers on	What it does
"make an icon", "change the icon's dark-mode color", authoring or editing any icon.json property	Creates a fresh .icon via the bundled create_icon.py CLI, or edits an existing icon.json in place and re-validates. Covers all schema categories — fills, blend modes, shadows, translucency, LiquidGlass, layouts, specializations.
"check this icon", "why won't Icon Composer open this"	Runs jsonschema against icon.json via validate_icon.py, cross-checks referenced assets against Assets/ on disk, and explains failures in terms of the schema.
"render this icon", "show me the dark/tinted variant", "does Icon Composer actually open this"	On macOS with Xcode, renders any platform/appearance to a PNG with ictool (bundled in Icon Composer.app, located via xcode-select -p). A failed render is the ground-truth signal that Icon Composer can't open the package — catching engine-level issues the schema can't, like the scale-only position bug.

The skill shells out to two small Python CLIs bundled in its scripts/ directory (a uv project); its preflight stops with an error if uv is not on PATH. The optional ictool rendering/ground-truth step needs macOS with Xcode (Icon Composer 1.5+) and is skipped elsewhere — validate_icon.py is the portable check.

Repo layout