How to use the Add App Icon agent skill (add-app-icon)

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file. The file gives an AI agent instructions for one kind of task, and the agent loads it when a request matches the skill's description. This skill's description says it applies when a bundled app icon needs adding to Dozzle, either for a container image with no logo or for an image that resolves to the wrong icon.

When triggered, the agent looks up how the image currently resolves, fetches a matching icon from the dashboard-icons project, shrinks WebP files, adds name aliases to the code where needed, adds test cases, runs the tests and formatter, and checks icon file sizes before committing.

• Icons are stored in assets/icons/apps/ and named by slug, for example signal.svg or signal.webp.
• Aliases go in ALIASES in assets/utils/appIcons.ts. Test cases go in assets/utils/appIcons.spec.ts.
• Commits follow the title format feat(icons): add icons for <apps>.

Install the add-app-icon skill

Download the skill ZIP from this page and unzip it. The skill is a single file, SKILL.md, inside an add-app-icon folder. Put that folder in one of two places:

• Personal: ~/.claude/skills/ so the skill is available across your projects.
• Project: .claude/skills/ inside the project you are working in.
• Claude apps: upload the ZIP under Settings → Capabilities → Skills.

Trigger the skill with a natural request

You do not need to type the skill name. Describe the problem in plain words that match the skill's description, and the agent should pick it up. Name the container image and say what is wrong with its icon.

Give the agent the image reference when you can, because the skill starts by checking how that image resolves today.

• Add an icon for the linuxserver/sonarr image in Dozzle, it currently shows no logo.
• The bbernhard/signal-cli-rest-api image shows the wrong icon in Dozzle. Fix it.
• Batch-add icons for these container images that have no logo in Dozzle: ...

Understand what the agent will do

The skill follows a fixed procedure. The agent first checks how the image resolves: the resolver drops registry, tag and digest, then tries the image name and falls back to the namespace. Generic names like server or app and distributor namespaces are skipped.

Next, the agent looks for an icon in the dashboard-icons repository. It prefers SVG and uses WebP only when no SVG exists. PNG is never used. If an SVG is over 20KB, the agent discards it in favour of the WebP, because large SVGs are usually traced rasters rather than real vector artwork. WebP files are downscaled to 64px tall and checked visually.

Finally, the agent verifies the work by running the alias tests and the Prettier formatter, then checks every icon in the folder for size and format problems.

• Upstream filenames are kept as they are; the agent does not rename icons to match the image.
• If the name does not match an existing slug, the agent adds an alias rather than renaming the icon.
• Downloaded artwork is not hand-edited, apart from the WebP downscale.

Check the prerequisites and safety notes

The skill needs several tools installed on your machine. It runs scripts and uses the network, so review what it does before you let it run unattended. It reads the dashboard-icons repository tree through the GitHub API and downloads files from GitHub raw content.

Only use the skill for well-known, publicly available images. The skill's rules say private or internal company images must not get logos.

• Git and the GitHub CLI (gh), used to read the dashboard-icons repository tree.
• curl, for downloading icons.
• cwebp and webpinfo from the webp package (for example brew install webp or apt install webp).
• Bun and Prettier, to run the tests and formatter.
• Network access to GitHub raw content and the GitHub API.

Tips for good results

Batch related apps into one request. The skill's rules call for one commit per batch. If the batch comes from GitHub issues, one PR per issue is acceptable, and each PR body should end with Closes #<issue>.

Look at the icons the agent produces. The skill asks for this check before committing, and a quick review catches a poor match.

• Do not ask the skill to use an app's favicon.svg when upstream has no SVG; the skill warns these are often a PNG wrapped in an image tag.
• If you only want a different icon on your own Dozzle instance, you do not need this skill. Use the dev.dozzle.icon=<slug> label, or dev.dozzle.icon=none to hide a wrong guess.