{"id":50419922,"url":"https://github.com/giginet/apple-icon-composer-skill","last_synced_at":"2026-06-06T14:01:01.432Z","repository":{"id":361521470,"uuid":"1254781717","full_name":"giginet/apple-icon-composer-skill","owner":"giginet","description":"Create and validate Apple Icon Composer .icon packages — installable as a Claude Code plugin, a Codex plugin, or a gh skill.","archived":false,"fork":false,"pushed_at":"2026-05-31T07:56:54.000Z","size":484,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T10:28:36.328Z","etag":null,"topics":["agent-skills","appicon","apple","claude-code","codex","icon-composer"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giginet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T02:01:03.000Z","updated_at":"2026-06-02T06:30:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/giginet/apple-icon-composer-skill","commit_stats":null,"previous_names":["giginet/apple-icon-composer-skill"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/giginet/apple-icon-composer-skill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giginet%2Fapple-icon-composer-skill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giginet%2Fapple-icon-composer-skill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giginet%2Fapple-icon-composer-skill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giginet%2Fapple-icon-composer-skill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giginet","download_url":"https://codeload.github.com/giginet/apple-icon-composer-skill/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giginet%2Fapple-icon-composer-skill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33860971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","appicon","apple","claude-code","codex","icon-composer"],"created_at":"2026-05-31T08:01:48.999Z","updated_at":"2026-06-03T11:00:28.126Z","avatar_url":"https://github.com/giginet.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Icon Composer Skill\n\n[![CI](https://github.com/giginet/apple-icon-composer-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/giginet/apple-icon-composer-skill/actions/workflows/ci.yml)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-plugin-D97757?logo=anthropic\u0026logoColor=white)](#claude-code)\n[![Codex](https://img.shields.io/badge/Codex-plugin-10A37F?logo=openai\u0026logoColor=white)](#codex)\n[![gh skill](https://img.shields.io/badge/gh_skill-install-1F2328?logo=github\u0026logoColor=white)](#github-cli-gh-skill)\n\nThe **icon-composer** plugin — tools to create, validate, and render Apple [Icon Composer](https://developer.apple.com/icon-composer/) `.icon` packages. The same package installs three ways: as a [Claude Code plugin](https://docs.claude.com/en/docs/claude-code/plugins), a [Codex plugin](https://developers.openai.com/codex/plugins), or a standalone skill via [`gh skill`](https://cli.github.com/manual/gh_skill_install).\n\n## Install\n\nPublished at \u003chttps://github.com/giginet/apple-icon-composer-skill\u003e. Pick the host you use — each path installs the same `compose-app-icon` skill.\n\n**Prerequisite:** [uv](https://docs.astral.sh/uv/) on your `PATH` (the skill runs its bundled Python CLIs through it) — `brew install uv`.\n\n### Claude Code\n\n```\n/plugin marketplace add giginet/apple-icon-composer-skill\n/plugin install icon-composer@icon-composer\n```\n\nThen 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.\n\n### Codex\n\n```sh\ncodex plugin marketplace add giginet/apple-icon-composer-skill\n# then open the plugin directory in Codex, pick the \"Icon Composer\" marketplace, and install\n```\n\nBacked 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.\n\n### GitHub CLI (`gh skill`)\n\nRequires GitHub CLI v2.90.0+.\n\n```sh\n# Browse and pick interactively\ngh skill install giginet/apple-icon-composer-skill\n\n# Or install it directly for a given host\ngh skill install giginet/apple-icon-composer-skill compose-app-icon --agent claude-code\n```\n\nThe 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.\n\n## Skill\n\nOne skill, `compose-app-icon`, covers authoring, validation, and rendering:\n\n| Triggers on | What it does |\n|---|---|\n| \"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. |\n| \"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. |\n| \"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. |\n\nThe skill shells out to two small Python CLIs bundled in its `scripts/` directory (a [uv](https://docs.astral.sh/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.\n\n## Repo layout\n\n```\n.\n├── .claude-plugin/\n│   └── marketplace.json                 Claude Code marketplace index (points at plugins/)\n├── .agents/plugins/\n│   └── marketplace.json                 Codex repo marketplace (points at plugins/)\n├── skills -\u003e plugins/icon-composer/skills   symlink for top-level `gh skill --from-local`\n├── plugins/\n│   └── icon-composer/\n│       ├── .claude-plugin/plugin.json   Claude Code manifest\n│       ├── .codex-plugin/plugin.json    Codex manifest (skills: \"./skills/\")\n│       └── skills/\n│           └── compose-app-icon/\n│               ├── SKILL.md             authoring + validation instructions\n│               └── scripts/             self-contained uv project\n│                   ├── create_icon.py\n│                   ├── validate_icon.py\n│                   ├── icon-schema.json source of truth for icon.json\n│                   ├── pyproject.toml   uv-managed deps: jsonschema, pillow, pytest (dev)\n│                   ├── uv.lock\n│                   └── tests/           pytest suite for both CLIs\n├── fixtures/                            example .icon packages — simple-image, variables-changed, complex-icon, test-generated, plugin-test\n└── README.md\n```\n\nThe skill is self-contained: the CLIs, schema, and their `uv` project all live in `plugins/icon-composer/skills/compose-app-icon/scripts/`, so every host — Claude Code, Codex, or `gh skill` — gets the full toolset when it copies the skill directory, with no shared files outside it. The top-level `skills` symlink points back into the plugin for local `gh skill --from-local` runs; remote `gh skill` discovers the skill via the nested `plugins/icon-composer/skills/*/SKILL.md` path.\n\n## Hacking on the skill locally\n\n```sh\ncd plugins/icon-composer/skills/compose-app-icon/scripts\nuv sync                          # installs runtime + dev (pytest) dependencies\n\n# Run the unit tests\nuv run pytest\n\n# Validate every example fixture by hand\nfor f in ../../../../../fixtures/*.icon; do\n    uv run python validate_icon.py \"$f\"\ndone\n\n# Round-trip: copy a fixture through the create CLI and re-validate\nFIX=../../../../../fixtures/simple-image.icon\nuv run python create_icon.py \\\n    --output /tmp/smoke.icon \\\n    --icon \"$FIX/icon.json\" \\\n    --asset video.fill.png=\"$FIX/Assets/video.fill.png\" \\\n    --force\nuv run python validate_icon.py /tmp/smoke.icon\n```\n\n`icon-schema.json` is the authoritative definition of the `icon.json` format — including per-appearance `-specializations` overrides, the LiquidGlass property set on groups, and the enum values Icon Composer's UI labels quietly map to (for example, Shadow `\"Natural\"` → `\"neutral\"`, `\"Chromatic\"` → `\"layer-color\"`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiginet%2Fapple-icon-composer-skill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiginet%2Fapple-icon-composer-skill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiginet%2Fapple-icon-composer-skill/lists"}