Stock Images

Security Rules

• NEVER display API keys in your output
• NEVER echo full curl commands that contain API keys
• Pixabay limitation: Pixabay requires the API key as a URL query parameter, which is visible in process lists (ps aux). Be aware of this inherent API limitation. Never display the full Pixabay curl command in output.
• Only download from allowed domains:
• images.pexels.com
• images.unsplash.com, plus.unsplash.com
• pixabay.com, cdn.pixabay.com
• All URLs MUST use HTTPS
• After downloading, check file size — alert if > 10MB
• For Unsplash downloads, use the links.download URL (not urls.raw) to comply with Unsplash API TOS (triggers download count)

Non-Activation

Do NOT activate this skill when:

• Discussing image components (`, next/image`, etc.)
• AI image generation is requested (that is a different skill)
• Referencing existing images already in the project

Setup Detection

Before searching, check if API keys are configured:

test -f ~/.config/stock-images/keys.json && stat -f "%Lp" ~/.config/stock-images/keys.json 2>/dev/null || stat -c "%a" ~/.config/stock-images/keys.json 2>/dev/null

• If the file does not exist: guide the user interactively through setup:

1. Ask which providers they want to use (Pexels, Unsplash, Pixabay — all free)
2. Provide the relevant signup links:

• Pexels: https://www.pexels.com/api/
• Unsplash: https://unsplash.com/developers
• Pixabay: https://pixabay.com/api/docs/

1. Once the user provides their keys, create the config file via Bash with chmod 600
2. NEVER display the keys back after saving

• If permissions are not 600: warn the user and offer to fix with chmod 600 ~/.config/stock-images/keys.json.
• If the file exists with correct permissions: use the keys silently. Do NOT display the file contents, the keys, or commands containing key values.

Determine configured providers without printing secret values:

python3 - -.` (e.g., `mountain-landscape-pexels.jpg`). Default extension is `.jpg` unless the URL clearly indicates otherwise (`.png`, `.webp`).
5. **Download**:

```bash
curl -sL --max-time 30 --fail -o "./images/FILENAME" "IMAGE_URL"

1. Verify: check file size and confirm to user

ls -lh "./images/FILENAME"

1. Attribution reminder: after download, remind the user:

> Attribution required: Photo by [Author](author_url) on [Provider]

Alert if file size > 10MB — the user may want a smaller resolution.

Attribution and license requirements vary by provider and project use. Always preserve and present author attribution metadata so the user can comply with the relevant provider terms.

Behavior Guidelines

• Infer orientation from context: "hero", "banner", "header" → landscape; "avatar", "profile" → portrait; "thumbnail", "icon" → square
• When the user is working on a UI component and mentions needing an image, proactively offer to search stock images
• Always present author attribution — Unsplash and Pixabay TOS require it
• Respond in the user's language
• If no results found, suggest alternative search terms
• If only one provider is configured, skip the provider selection and use it directly

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jeanpfs
• Source: jeanpfs/stock-images
• License: MIT

Install and usage instructions live in the source repository linked above.