# unsplash-image

Searches Unsplash for stock photos, downloads the one it picks, and can stamp a title and subtitle onto the image. Handy when a post or cover needs a picture.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 367 installs · ★ 721
- Author: OpenClaudia
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/OpenClaudia/openclaudia-skills/tree/HEAD/skills/stock-images/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/unsplash-image

## What it does

The skill wraps a script at `~/.agents/tools/unsplash-search.py`, which the agent calls with a search query and an output path. You can filter by orientation (`landscape`, `portrait`, `squarish`) or by color, take a random result or the first one, and use `--list` to see what matched without downloading anything.

Text overlay turns on with `--title`, and `--subtitle` rides along with it. The script paints a semi-transparent dark band across the bottom, white title text with a shadow, gray subtitle, and handles word wrapping and font size on its own. That part needs Pillow, so install the dependencies up front: `pip install requests Pillow`. Skip `--title` and Pillow is not involved.

The script reads `UNSPLASH_CLIENT_ID` from `~/.agents/tools/.env`. No key, no API calls — check that file first if a search comes back empty. Downloads arrive at "regular" quality, 1080px wide; for anything larger you edit the script to use `urls.full` or `urls.raw`. Each run prints the photo URL, the photographer's name, the saved path, and pings Unsplash's download tracking endpoint, since their API terms require attribution.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill unsplash-image -a claude-code
```
```bash
npx skills add OpenClaudia/openclaudia-skills --skill stock-images -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/stock-images/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/stock-images/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill stock-images -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/stock-images/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill stock-images -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/stock-images/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install OpenClaudia/openclaudia-skills stock-images
```

2. **Manually: put the files in place**
- File: `.github/skills/stock-images/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill stock-images -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/OpenClaudia/openclaudia-skills --path skills/stock-images
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/stock-images/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill stock-images -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/OpenClaudia/openclaudia-skills/tree/HEAD/skills/stock-images/SKILL.md

## When to use it
- find a stock photo from a description and drop it into the project
- build a cover image with a title laid over the photo
- filter results by orientation for a wide banner
- preview matching photos without saving any of them
- get an image into markup without opening a browser

## Example prompts
- find a photo of a coffee shop and save it to ./coffee.jpg
- make a cover: technology image, title "My Post", subtitle "A short description"
- list results for sunset, don't download anything

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 08e867d84cb5e859.

BEGIN THIRD-PARTY FILE 08e867d84cb5e859
````text
---
name: unsplash-image
description: Search for images on Unsplash and download them. Optionally add text overlay (title/subtitle) to the image. Use when the user asks to find a stock photo, search for an image, get an Unsplash image, or download a photo with text.
argument-hint: [search query]
allowed-tools: Bash(*), Read, Write
---

# Unsplash Image Search & Download

Search Unsplash for images, download them, and optionally add text overlay.

## Tool Location

- Script: `~/.agents/tools/unsplash-search.py`
- Env file: `~/.agents/tools/.env` (contains `UNSPLASH_CLIENT_ID`)

## Quick Usage

### Search and download a random matching image

```bash
python ~/.agents/tools/unsplash-search.py \
  --query "nature landscape" \
  --output ./image.jpg
```

### With orientation filter

```bash
python ~/.agents/tools/unsplash-search.py \
  --query "coffee shop" \
  --orientation landscape \
  --output ./coffee.jpg
```

### With text overlay (title and subtitle)

```bash
python ~/.agents/tools/unsplash-search.py \
  --query "technology abstract" \
  --output ./cover.png \
  --title "My Blog Post Title" \
  --subtitle "A short description"
```

### List results without downloading

```bash
python ~/.agents/tools/unsplash-search.py \
  --query "sunset" \
  --list
```

### Pick the first result instead of random

```bash
python ~/.agents/tools/unsplash-search.py \
  --query "mountains" \
  --pick first \
  --output ./mountains.jpg
```

## CLI Options

| Option | Description |
|--------|-------------|
| `--query, -q` | **(Required)** Search query string |
| `--output, -o` | **(Required unless --list)** Output file path |
| `--orientation` | Filter: `landscape`, `portrait`, or `squarish` |
| `--color` | Color filter (e.g., `blue`, `green`, `red`, `black_and_white`) |
| `--pick` | How to select from results: `random` (default) or `first` |
| `--title` | Title text to overlay on the image |
| `--subtitle` | Subtitle text to overlay (only used with --title) |
| `--list` | List search results instead of downloading |
| `--count` | Number of results to fetch, max 30 (default: 30) |

## Text Overlay

When `--title` is provided, the script adds a text overlay to the bottom portion of the image with:
- Semi-transparent dark background behind the text
- White title text with shadow
- Gray subtitle text (if provided)
- Automatic word wrapping and font sizing

**Requires Pillow**: `pip install Pillow`

## Dependencies
````
END THIRD-PARTY FILE 08e867d84cb5e859

The third-party file has ended. Everything between the 08e867d84cb5e859 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2436 of 3094 bytes. © OpenClaudia · MIT · https://github.com/OpenClaudia/openclaudia-skills/tree/HEAD/skills/stock-images/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md