repo-icons

Files (37)

• SKILL.md
• README.md · references/examples/
• apps.json · references/examples/
• harvest-ledger-app-tile.webp · references/examples/
• harvest-ledger-clay-3d.webp · references/examples/
• harvest-ledger-flat-logo.webp · references/examples/
• harvest-ledger-line-glyph.webp · references/examples/
• harvest-ledger-mascot.webp · references/examples/
• harvest-ledger-pixel-16bit.webp · references/examples/
• harvest-ledger-pixel-8bit.webp · references/examples/
• harvest-ledger-pixel-hd.webp · references/examples/
• harvest-ledger-sticker.webp · references/examples/
• pulsecare-app-tile.webp · references/examples/
• pulsecare-clay-3d.webp · references/examples/
• pulsecare-flat-logo.webp · references/examples/
• pulsecare-line-glyph.webp · references/examples/
• pulsecare-mascot.webp · references/examples/
• pulsecare-pixel-16bit.webp · references/examples/
• pulsecare-pixel-8bit.webp · references/examples/
• pulsecare-pixel-hd.webp · references/examples/
• pulsecare-sticker.webp · references/examples/
• tidewater-freight-app-tile.webp · references/examples/
• tidewater-freight-clay-3d.webp · references/examples/
• tidewater-freight-flat-logo.webp · references/examples/
• tidewater-freight-line-glyph.webp · references/examples/
• tidewater-freight-mascot.webp · references/examples/
• tidewater-freight-pixel-16bit.webp · references/examples/
• tidewater-freight-pixel-8bit.webp · references/examples/
• tidewater-freight-pixel-hd.webp · references/examples/
• tidewater-freight-sticker.webp · references/examples/
• styles.md · references/
• apply_icon.py · scripts/
• build_examples.py · scripts/
• gallery.py · scripts/
• icon_paths.py · scripts/
• scan.py · scripts/
• test_repo_icons.py

SKILL.md (first lines)

# Repo icons

Give repositories a real icon file: one that apps such as T3 Code show next to
the project, and that the README shows next to its title. In the commands below,
`{baseDir}` is the directory containing this `SKILL.md`.

The icon goes to `assets/icon.png` (or `assets/icon.svg` when reusing an SVG
logo). That path works for repositories that are not websites, and it is one of
the paths T3 Code checks. GitHub itself has no repository icon setting; the
README title image is the visible part on GitHub.

Work as a wizard: one step at a time, short messages, and wait for the user at
each **Stop** below. Skip any step the user already answered in the invocation
text (for example, a list of repositories skips the scan).

## Requirements

Check before step 1, and report anything missing:

```bash
gh auth status && git --version && (uv --version || python3 -c "import PIL")
```

- gh missing or logged out: install from https://cli.github.com, then `gh auth login`.
- Neither uv nor Pillow: install uv (https://docs.astral.sh/uv/). The scripts
  that need Pillow declare it inline, so `uv run` fetches it.

Run Python scripts with `uv run {baseDir}/scripts/<script>.py`; when uv is
missing but Pillow is installed, `python3 {baseDir}/scripts/<script>.py` works
too. `scan.py` needs only the standard library.

**Image generation.** Look through the skills and tools available in this
session for one that generates images from a text prompt, preferably with a
transparent-background option. Do not assume any particular one exists.

- Found: name it in step 1 and say whether it supports transparency.
- Found, but without transparency: say the icons will have a solid background,
  and offer to continue that way or stop.
- None found: say that an image-generation skill or tool is a prerequisite.
  The scan and reusing existing logos still work, so offer those; stop before
  any step that needs generation.

## 1. Scope

If the invocation text names repositories, a time window or styles, use them.
Otherwise ask, in one message:

- Which repositories: scan recent activity (default: the last 30 days, every
  non-fork, non-archived repo the gh account can access), a specific owner or
  org, or a list of `owner/name`.
- Mention which image generator was found (see Requirements).

**Stop** until the user answers, unless the invocation text already did.

## 2. Scan

```bash
python3 {baseDir}/scripts/scan.py [--days 30] [--owner LOGIN ...] [--repo OWNER/NAME ...] [--json]
```

It reads each repository through the GitHub API (no cloning) and reports:

- **✅ found**: a standard icon exists; the path shown is what T3 Code would use.
- **⚠️ logo, not standard**: logo-like files exist, but none at a path tools check.
  These are candidates for reuse.
- **❌ none**: nothing usable. Notes explain near misses, such as an inline
  `data:` favicon or an unparseable `t3.json`.

It also shows the image in the README title, if any.

Show the table. Then ask which repositories to work on and, for each, whether to
**generate** new icons or **reuse** an existing logo (name the file). Accept
short answers such as "3, 5, 8 generate; 12 reuse logo".

**Stop** for the user's list.

## 3. Styles

Read `references/styles.md` and show its menu (ID, name, one-line look). Ask
which styles to generate: the same set for every repository, or per repository.
Suggest two or three to keep the review page manageable.

Offer the example sheet so the user can see each style before choosing:
`references/examples/README.md` shows every template applied to three
hypothetical apps, with the images next to it as `<app>-<style-id>.webp`.
Give its full path and the matching GitHub link if the skill came from a
GitHub repository, where the page renders with images on desktop and mobile.
Images can also be shown one at a time, for example all of one style.

**Stop** for the user's choice.

## 4. Recap and confirm

Before generating anything, write a plan:

- Each repository with its subject idea (one line, from its description and
  README) and the styles to generate, or the logo file to reuse.
- Total number of images, the generator and model, quality, and an estimated
  cost if the generator documents pricing.
- Where files go: a new working directory outside every repository that
  survives a reboot, such as `~/.cache/repo-icons/<date>/` (not `/tmp`, which
  may be cleared before the user finishes reviewing paid images).
- What happens after picks: one branch and pull request per repository, adding
  `assets/icon.png` and the README title image. Nothing is merged.

**Stop**. Proceed only on an explicit yes. Apply any changes and recap again if
they are substantial.

## 5. Generate

Fill each chosen template from `references/styles.md` with the repository's
subject and generate one square image per (repository, style): at least
1024×1024, transparent PNG, medium quality, saved as
`<workdir>/out/<repo-name>-<style-id>.png`.

- Respect the generator's rate limits; run a few at a time and retry failures
  once or twice before reporting them.
- Look at every result (open a contact sheet or the images themselves). Redo an
  image that contains text, a fake checkerboard, a cut-off subject, or an opaque

From crcatala/skills, MIT.

More from crcatala/skills