--- name: unsplash-image-filler description: Scans web projects, analyzes page context with NLP, and inserts Unsplash hotlink URLs directly into HTML\/JSX. NEVER downloads images locally - always uses Unsplash CDN hotlinks. --- # Unsplash Image Filler This skill automatically populates your website with relevant images from Unsplash using **hotlink URLs only**. > [!IMPORTANT] > **ALWAYS USE HOTLINKS - NEVER DOWNLOAD IMAGES LOCALLY** > > This skill is designed to use Unsplash CDN hotlinks (`images.unsplash.com`) directly in the `src` attribute. > **DO NOT** download images to local directories. **DO NOT** save images to `public\/`, `assets\/`, or any local folder. > The `imageDestination` config option is deprecated and should be ignored. ## How It Works 1. Scans HTML\/JSX files for placeholder tags 2. Analyzes page content using NLP to determine relevant keywords 3. Searches Unsplash API for matching images 4. **Inserts the Unsplash CDN URL directly into the `src` attribute** (e.g., `https:\/\/images.unsplash.com\/photo-xxx?w=1080`) 5. Tracks downloads per Unsplash API guidelines ## Usage ### 1. Configuration Set your Unsplash Access Key via environment variable (recommended): ```bash export UNSPLASH_ACCESS_KEY="your_key_here" ``` Or create `unsplash.config.json` in your project root: ```json { "accessKey": "YOUR_UNSPLASH_ACCESS_KEY" } ``` ### 2. Add Placeholders Add image tags to your HTML or JSX files: | Placeholder | Description | |-------------|-------------| | `` | Auto-match based on page content | | `` | Specific search term | For articles (HTML only): ```html

<\/article>

<\/article> ``` ### 3. Run the Script ```bash node scripts\/auto_fill.js --dir \/path\/to\/your\/project ``` Options: - `--dir, -d`: Target directory to scan (default: `.`) - `--key, -k`: Unsplash Access Key (overrides env\/config) - `--dry-run`: Preview operations without making changes ## Output Example Before: ```html ``` After: ```html

``` > [!NOTE] > The script adds `data-unsplash-processed="true"` to prevent re-processing on subsequent runs. ## Features - **Semantic Analysis**: NLP-powered content analysis for auto-matching - **Hotlink Only**: Uses Unsplash CDN URLs directly (no local downloads) - **Smart Caching**: In-memory cache prevents redundant API calls - **Rate Limiting**: Built-in retry logic and exponential backoff - **Idempotent**: Safe to run multiple times (skips processed images) ## Requirements - Node.js - Run `npm install` in the `scripts` directory ## Agent Instructions > [!CAUTION] > **FOR AI AGENTS**: When using this skill: > 1. **NEVER** use the `downloadImage()` method from `unsplash_client.js` > 2. **ALWAYS** use the hotlink URL from `photo.urls.regular` or `photo.urls.small` > 3. **NEVER** save images to local filesystem > 4. **ONLY** run `auto_fill.js` script which handles everything correctly > 5. If manually inserting images, use format: `