create-svg-image

Create SVG Image (Numbered Step Badge)

Use this skill to take a screenshot or image and produce an SVG that shows the image with a numbered red circle placed on top of it. This is for adding "step 1 / step 2" call-out badges that point at a specific UI control in a course screenshot.

The caller always provides three things:

1. The image to use — a .webp, .png, or .jpg file in the repo.
2. The location of the numbered circle — where on the image the circle goes, in the image's native pixel coordinates (X from the left, Y from the top).
3. The number to apply — the digit/short text shown inside the circle.

Optional inputs: circle --radius, fill --color, --text-color, and --out path.

Why This Produces an SVG (Not Inline HTML or a Plain Image Edit)

GitHub renders an SVG referenced from Markdown (![](file.svg)) inside a sandboxed <img>. In that mode GitHub:

• strips inline <svg> from README HTML, so you cannot paste raw <svg> markup into the Markdown, and
• refuses to fetch an external/relative <image href="photo.webp">, so an SVG that merely points at the raster shows a blank photo.

The reliable approach is therefore an SVG file that embeds the raster as a data: base64 URI and draws the <circle> + <text> on top. The photo renders on GitHub and the badge stays editable as plain SVG markup. (Baking the number into the PNG/webp with an image editor also works, but then the number is no longer editable text — prefer the SVG.)

Helper Script

sample_codes/create-svg-badge.sh does the whole job: detects the image size and mime type, base64-encodes the raster, writes the SVG, validates it with xmllint when available, and renders a PNG preview when a renderer is available and previews are enabled.

# Required: --image, --x, --y, --number
bash .github/skills/create-svg-image/sample_codes/create-svg-badge.sh \
  --image 02-sessions-worktrees-context/assets/app-create-from-icon.webp \
  --x 710 --y 72 --number 1
# -> writes assets/app-create-from-icon-step1.svg and prints a PREVIEW png path

Useful options: --radius (defaults to ~2.5% of the image width so badges stay a consistent on-screen size, see below), --color "#d1242f" (GitHub danger red), --out PATH, --grid (coordinate finder, below), --no-preview.

Workflow

1. Find the circle coordinates if the caller gave an approximate spot ("left of the Create from icon") rather than exact pixels. Run the script in --grid mode, which overlays a labeled coordinate grid on the image and renders a preview without writing anything to the repo:

   bash .github/skills/create-svg-image/sample_codes/create-svg-badge.sh \
     --image <path> --number 1 --grid
   

   View the printed GRID_PREVIEW PNG, read the green (X) and magenta (Y) labels to pick the target pixel, then continue. Coordinates are in the image's native pixel space (the SVG viewBox equals the image's pixel dimensions).

2. Generate the badged SVG with the chosen --x, --y, and --number:

   bash .github/skills/create-svg-image/sample_codes/create-svg-badge.sh \
     --image <path> --x <N> --y <N> --number <N>
   

3. Verify by viewing the preview. Open the printed PREVIEW PNG with the image view tool and confirm the circle sits where the caller wanted. Note: macOS qlmanage pads the preview to a square canvas — only the top strip (the image's real height) is the actual image; the white area below is padding, not output.

4. Adjust if needed. Nudge by re-running with new values: smaller --x moves the circle left, larger --x right; --y moves it up/down; --radius resizes it (the font scales automatically). Iterate until the placement is right.

5. Wire it into the chapter (only when the caller asks for the README change): reference the new .svg instead of the original raster, keeping descriptive alt text:

   ![Create from branch](assets/app-create-from-icon-step1.svg)
   

Conventions

• Default output lives next to the source image as <stem>-step<number>.svg, matching this repo's per-chapter assets/ layout.
• Keep the original raster in the repo as the editable source; it stays the input even though the README now points at the .svg.
• Default badge style: solid GitHub danger red #d1242f, white number, thin white outline so it reads on light or dark screenshots.
• Keep the badge diameter consistent across every generated SVG. The radius defaults to ~2.5% of the image width (the white outline and number scale with it). Because GitHub scales each screenshot to the README column width, this makes every badge render at the same apparent size regardless of the capture's resolution. This is why a radius 24 badge on a 936px-wide capture and a radius 56 badge on a 2240px-wide capture look identical. Only pass --radius for a deliberate one-off; otherwise let the default keep things uniform.
• One circle per file matches the required inputs (image + one location + one number). For a multi-step figure, either generate separate -step1, -step2 files or hand-add extra <circle>/<text> pairs to the SVG.

Safety and Notes

• Renders previews to a temp dir ($TMPDIR/create-svg-badge), never into the repo.
• --grid writes nothing to the repo; it is purely a coordinate-finding preview.
• Screenshots may contain account names, private repo names, or paths — describe the UI generically and don't surface private data when reporting placement.

Related Skills

• comic-strip-site — builds a full webcomic-style site by wrapping AI-generated character panels in inline SVG (comic frame, tailed speech bubbles, terminal command bar). Shares this skill's SVG-over-raster technique and the --grid coordinate-finding workflow, but for storytelling panels and recurring cartoon characters rather than single numbered step badges.