Image Hosting Integration

Upload images to GitHub Pages and get permanent public URLs. Ideal for generated images that need to be shared or embedded.

Quick Start

After generating an image to a local path, host it:

- run: Upload Image to GitHub Pages
  args:
    - "session/generated-image.png"
    - "optional-custom-name"
    - "Hosted Images Index"

Output includes the public URL:

{
  "success": true,
  "url": "https://username.github.io/media-assets/2026/01/14/custom-name.png",
  "filename": "custom-name.png",
  "remotePath": "2026/01/14/custom-name.png"
}

How It Works

1. Images upload to a shared media-assets repo on the user's GitHub
2. Files organize by date: YYYY/MM/DD/filename.png
3. GitHub Pages serves the images at public URLs
4. URLs are permanent—safe to embed or share

Integration Pattern

Skills that generate images can import this as a dependency:

dependencies:
  - use: Image Hosting
    when: "User wants a public URL for generated images"

Then chain generation → hosting:

steps:
  # Generate image to local session folder
  - run: Generate or Edit Image
    args: ["prompt", "", "session/images/"]

  # Host and get public URL
  - run: Upload Image to GitHub Pages
    args: ["session/images/generated.png", "descriptive-name", "Hosted Images Index"]

  # Present the URL to the user
  - instruction: "Share the public URL from the upload result with the user."

Arguments

Arg	Required	Description
imagePath	Yes	Path to local image file
filename	No	Custom name (sanitized, no extension needed)
trackingPath	No	Path to tracking JSON (e.g., Hosted Images Index)

Supported Formats

PNG, JPG, JPEG, GIF, WebP, SVG

URL Structure

https://{username}.github.io/media-assets/{YYYY}/{MM}/{DD}/{filename}.{ext}

Example: https://johndoe.github.io/media-assets/2026/01/14/sunset-landscape.png

First-Time Setup

On first use, the code creates:

1. A media-assets repository on the user's GitHub
2. Enables GitHub Pages for that repo
3. Initial deployment may take 1-2 minutes

Subsequent uploads are near-instant.

When to Use

• Generated AI images that need sharing
• Charts or visualizations for reports
• Assets for web apps or documents
• Any image needing a permanent public URL

When NOT to Use

• Large files (>50MB) — GitHub has limits
• Sensitive/private images — repo is public
• Temporary images — use session files instead
• High-frequency uploads — respect GitHub rate limits