@netlify/agent-runner-cli 2.7.0 → 2.8.0

package/dist/skills/netlify-image-cdn/SKILL.md

@@ -1,244 +1,185 @@
 ---
 name: netlify-image-cdn
-description: Transform and optimize images on-demand using Netlify Image CDN. Use when implementing responsive images, format conversion, resizing, cropping, or dynamic image optimization without build-time processing.
+description: Transforms images on demand via Netlify Image CDN's /.netlify/images endpoint with query parameters for resizing/cropping/format/quality. Use when adding image optimization or responsive images, converting formats (WebP/AVIF/PNG), generating thumbnails or blur placeholders, serving remote/third-party images through the CDN, allowlisting remote domains in netlify.toml, setting up image redirects or cache headers, building user-uploaded image pipelines, or debugging a 404 on /.netlify/images. Also covers framework image handling for Angular/Astro/Gatsby/Next.js/Nuxt.
 ---
 
 # Netlify Image CDN
 
-Netlify Image CDN transforms and optimizes images on demand at the edge without impacting build times. It handles
-content negotiation to serve the most efficient format and caches transformed images for fast delivery.
+Transform images by requesting the endpoint with a `url` query parameter. This is the current and only documented surface — there is no legacy form.
 
-## Quick Start
-
-All Netlify projects have a `/.netlify/images` route without any additional enablement. Use it with query parameters to
-transform any image:
-
-```html
-<!-- Resize to 400px wide, convert to WebP -->
-<img src="/.netlify/images?url=/photo.jpg&w=400&fm=webp" alt="Optimized photo" />
-
-<!-- Cover crop to 200x200 square -->
-<img src="/.netlify/images?url=/photo.jpg&w=200&h=200&fit=cover" alt="Cropped photo" />
-
-<!-- Transform a remote image -->
-<img src="/.netlify/images?url=https://example.com/image.jpg&w=800&q=80" alt="Remote image" />
+```
+GET /.netlify/images?url=<source>[&w=][&h=][&fit=][&position=][&fm=][&q=]
 ```
 
-## Query Parameters
-
-| Parameter | Required | Type | Description |
-|-----------|----------|------|-------------|
-| `url` | Yes | `string` | Source image path (relative) or URL (remote, requires config) |
-| `w` | No | `integer` | Width in pixels |
-| `h` | No | `integer` | Height in pixels |
-| `fit` | No | `string` | Resize mode: `contain` (default), `cover`, `fill` |
-| `position` | No | `string` | Crop anchor for `fit=cover`: `center` (default), `top`, `bottom`, `left`, `right` |
-| `fm` | No | `string` | Output format: `avif`, `jpg`, `png`, `webp`, `gif`, `blurhash` |
-| `q` | No | `integer` | Quality 1-100 for lossy formats (default: 75) |
-
-The `url` value must be URI-encoded when it contains special characters.
-
-## Fit Modes
-
-| `fit=` | Aspect Ratio Maintained | Crops | Always Returns Exact Dimensions |
-|--------|------------------------|-------|-------------------------------|
-| `contain` (default) | Yes | No | No, one dimension may be smaller |
-| `cover` | Yes | Yes | Yes, crops excess after proportional resize |
-| `fill` | No | No | Yes, stretches/squishes to exact dimensions |
-
-### `fit=contain` (default)
-
-Resizes proportionally to fit within the specified dimensions. If only one dimension is given, the other is calculated
-to maintain aspect ratio.
-
-```html
-<img src="/.netlify/images?url=/photo.jpg&w=600&h=400&fit=contain" />
+```bash
+# resize a deployed image to 50px wide
+curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&w=50'
 ```
 
-### `fit=cover`
+`url` is required; all other parameters are optional.
 
-Resizes proportionally to fill the dimensions, then crops excess pixels. Requires **both** `w` and `h`. Use `position`
-to control which area is retained.
+## Query parameters
 
-```html
-<img src="/.netlify/images?url=/photo.jpg&w=300&h=300&fit=cover&position=top" />
-```
+| Parameter | Purpose | Values | Default |
+|-----------|---------|--------|---------|
+| `url` | Source asset (required) | Relative path or remote URL | — |
+| `w` | Width in pixels | Integer | — |
+| `h` | Height in pixels | Integer | — |
+| `fit` | Resize behavior | `contain`, `cover`, `fill` | `contain` |
+| `position` | Crop anchor when `fit=cover` | `top`, `bottom`, `left`, `right`, `center` | `center` |
+| `fm` | Output format | `avif`, `jpg`, `png`, `webp`, `gif`, `blurhash` | content-negotiated |
+| `q` | Quality for lossy output | Integer `1`–`100` | `75` |
+
+## Common transformations
 
-### `fit=fill`
+```bash
+# resize + crop to a 50px square, retaining the left side
+curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fit=cover&w=50&h=50&position=left'
 
-Stretches the image to exactly match the specified dimensions. May distort the image if aspect ratios differ.
+# convert JPEG to PNG (response carries content-type: image/png)
+curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fm=png'
 
-```html
-<img src="/.netlify/images?url=/photo.jpg&w=400&h=200&fit=fill" />
+# convert JPEG to AVIF at medium quality
+curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fm=avif&q=50'
 ```
 
-## Format Negotiation
+### fit behavior
 
-When `fm` is **not** specified, Image CDN automatically negotiates the best format using the browser's `Accept` header:
+- **`contain` (default):** maintains aspect ratio; one dimension may come back smaller than requested. Supply one dimension and the other is computed.
+- **`cover`:** fills exactly, cropping excess. **Requires BOTH `w` and `h`** — omitting either is invalid. Use `position` to choose what's retained.
+- **`fill`:** fills exactly, stretching/squishing if aspect ratios differ.
 
-1. Use `webp` if the browser accepts it
-2. Otherwise use `avif` if accepted
-3. Otherwise serve the original format
+### Format notes
 
-Explicitly set `fm` only when a specific format is required (e.g., `blurhash` for placeholders).
+- `q` applies only when output is `avif`, `jpg`, `gif`, or `webp`.
+- `webp` and `gif` can be static or animated.
+- If `fm` is omitted, format is content-negotiated from the `Accept` header: `webp` if accepted, else `avif` if accepted, else the original format. A source-only request (no other params) still converts to `webp`/`avif` but keeps size and shape.
 
-## Remote Image Configuration
+## Remote source images
 
-To transform images from external domains, allowlist them in `netlify.toml` using regex patterns:
+Remote sources must be allowlisted in `netlify.toml` before transformation, or the request fails.
 
 ```toml
 [images]
-remote_images = [
-  "https://my-images\\.com/.*",
-  "https://animals\\.more-images\\.com/[bcr]at/.*"
-]
+  remote_images = ['https://my-images\.com/.*', 'https://animals.more-images.com/[bcr]at/.*']
 ```
 
-Then reference the full URL:
+Percent-encode remote source URLs before placing them in the `url` parameter with `encodeURIComponent` — a URL containing `?` or `&` breaks otherwise.
 
-```html
-<img src="/.netlify/images?url=https://my-images.com/photo.jpg&w=400" />
+```js
+const src = `/.netlify/images?url=${encodeURIComponent('https://my-images.com/owl.jpeg?v=2')}&w=400`;
 ```
 
-Only absolute URLs to external servers need to be in `remote_images`. Local site images work without configuration.
+Constraints:
+- Remote sources must be **publicly accessible**.
+- Credential-bearing headers (`Authorization`, `Cookie`) are **NOT forwarded** when fetching a remote source. For authenticated sources, use URLs that carry their own authorization (e.g. S3 presigned URLs) and make sure your `remote_images` patterns match those full URLs.
 
-## Redirects & Rewrites
+### remote_images regex escaping
 
-If you do not want to use the default `/.netlify/images` path, a redirect or rewrite can be used to have a different
-URL. When doing so, the parameters can remain parameters to pass in or can be statically defined.
+The only meaningful escape is the literal dot (`\.`). Forward slashes are NOT metacharacters — never write `https:\/\/`. In `netlify.toml`, use single-quoted literal strings (`'https://example\.com/.*'`) or double the backslash in double-quoted strings (`"https://example\\.com/.*"`). A bare `\.` inside double quotes is invalid TOML.
 
-**Using `netlify.toml`:**
+## Response codes
 
-```toml
-[[redirects]]
-from = "/transform-small/*"
-to = "/.netlify/images?url=/:splat&w=50&h=50"
-status = 200
-```
+- Invalid transformation parameter values → `404`.
+- Valid new transformation → `200` with content and matching `content-type`.
+- Previously transformed (cached) image → `304`.
+
+## Reusing parameters across images
 
-**Using `_redirects` file:**
+Map a friendly path to the endpoint with a redirect/rewrite.
 
+`_redirects`:
 ```
 /transform-small/* /.netlify/images?url=/:splat&w=50&h=50 200
 ```
 
-**Usage:**
-
-```html
-<!-- Transforms /photo.jpg with w=50&h=50 -->
-<img src="/transform-small/photo.jpg" />
+`netlify.toml`:
+```toml
+[[redirects]]
+  from = "/transform-small/*"
+  to = "/.netlify/images?url=/:splat&w=50&h=50"
+  status = 200
 ```
 
-DO NOT create circular redirects where an image URL redirects to another URL that redirects back. This causes infinite
-loops and errors.
+Then `GET /transform-small/owl.jpeg` returns the transformed image. **Cross-site redirects for transformations are NOT recommended** — they can degrade site performance.
 
-## Custom Headers
+## Caching headers
 
-Apply custom headers to source images on your site's domain. Headers propagate to the transformed output. ONLY do this
-when explicitly asked.
-
-**Using `netlify.toml`:**
+Apply custom headers to source images on the site's own domain; they carry through to the transformed output.
 
+`netlify.toml`:
 ```toml
 [[headers]]
-for = "/source-images/*"
-[headers.values]
-  Cache-Control = "public, max-age=604800, must-revalidate"
+  for = "/source-images/*"
+  [headers.values]
+    Cache-Control = "public, max-age=604800, must-revalidate"
 ```
 
-**Using `_headers` file:**
-
-```
-/source-images/*
-  Cache-Control: public, max-age=604800, must-revalidate
-```
-
-**Limitations:**
-- Custom headers only work for images on the same domain
-- Cannot apply custom headers to remote source images
-- Netlify respects cache headers that external domains send with their images
-- `Cache-Control` headers on source images apply to browsers/CDNs, not the Netlify cache itself
-
-## Framework Integration
-
-Many frameworks automatically use Netlify Image CDN when deployed to Netlify:
-
-| Framework | Setup | Remote Image Allowlist |
-|-----------|-------|----------------------|
-| **Angular** | Automatic via `NgOptimizedImage` | `[images] remote_images` in `netlify.toml` |
-| **Astro** | Automatic via `<Image />` component | `image.domains` or `image.remotePatterns` in `astro.config.mjs` |
-| **Gatsby 5.13+** | Set env var `NETLIFY_IMAGE_CDN=true` | `[images] remote_images` in `netlify.toml` |
-| **Next.js 13.5+** | Automatic with adapter v5 | `remotePatterns` in `next.config.js` |
-| **Nuxt** | Automatic via `nuxt/image` module | `image.domains` in `nuxt.config.ts` |
-
-## Caching & Deploy Behavior
-
-- Transformed images are uniquely cached at the edge per transformation parameters
-- Future requests for the same transformation serve the cached version
-- After a new deploy, cached images are invalidated if the source changed
-- Source images are also cached to speed up future transformations
-- Use asset fingerprinting (content hashes in filenames) for fine-grained cache control
-
-## Response Codes
-
-| Condition | Response |
-|-----------|----------|
-| Valid query, new transformation | `200` with transformed image |
-| Request for previously cached transformation | `304` Not Modified |
-| Invalid parameter values or missing source | `404` Not Found |
-
-## Common Errors & Solutions
-
-### "404 on image transformation"
+- Custom headers can be applied to source images on the site's domain only — NOT to remote source images (Netlify does respect cache headers the external domain sends).
+- `Cache-Control` on source images applies only to browsers and CDNs in front of Netlify, NOT the Netlify Cache itself.
 
-**Cause:** Invalid parameter values or source image not found.
+## Blur placeholders (fm=blurhash)
 
-**Fix:**
+`fm=blurhash` returns a BlurHash **text string**, not image bytes. Pointing an `<img src>` (or CSS background) at it renders nothing. Fetch the string ahead of time, decode it client-side with a BlurHash library (https://blurha.sh), and load the real image as a separate request without `fm=blurhash`.
 
-1. Verify the source image exists at the specified `url` path
-2. Check parameter values are valid (e.g., `q` must be 1-100, `fit` must be `contain`, `cover`, or `fill`)
-3. For remote images, ensure the domain is in `remote_images` config
+## Local development
 
-### Blurry or low-quality output
+The `/.netlify/images` endpoint, `[images]` allowlisting, and image redirects only exist under `netlify dev` (Netlify CLI). A local **404 on `/.netlify/images` almost always means a framework dev server (`vite`, `next dev`, `astro dev`) is running instead of `netlify dev`** — the URL itself is usually fine. Start the local environment with `netlify dev`.
 
-**Cause:** Quality setting too low or dimensions too small.
+## User-uploaded image pipelines
 
-**Fix:**
+For pipelines composing Functions + Blobs + Image CDN (handling user-uploaded images), see `references/user-uploads.md`.
 
-1. Increase the `q` parameter (default is 75, max is 100)
-2. Ensure `w` and `h` are appropriate for the display size
-3. Use `fm=png` for images that need lossless quality
+## Framework image handling
 
-### Remote image not loading
+Many frameworks route their built-in image optimization through Netlify Image CDN — use the framework's standard image component/syntax and only configure the remote allowlist. For unlisted frameworks, call `/.netlify/images` directly.
 
-**Cause:** External domain not allowlisted.
+| Framework | Prerequisites | Remote allowlist location |
+|-----------|---------------|---------------------------|
+| Angular | None; `NgOptimizedImage` uses it automatically | `[images] remote_images` in `netlify.toml` |
+| Astro | None; `<Image />` uses it automatically | `image.domains` or `image.remotePatterns` in `astro.config.mjs` |
+| Gatsby (both 5.13+ and 5.11 or earlier) | Set env `NETLIFY_IMAGE_CDN=true`; use Contentful/Drupal/WordPress source plugins | `[images] remote_images` in `netlify.toml` |
+| Next.js | Next.js 13.5+ and Next.js adapter v5 | `remotePatterns` in `next.config.js` |
+| Nuxt | None; `nuxt/image` module uses it automatically | `image.domains` in `nuxt.config.ts` |
 
-**Fix:**
+Setup guides: [Angular](https://docs.netlify.com/build/frameworks/framework-setup-guides/angular#netlify-image-cdn), [Astro](https://docs.netlify.com/build/frameworks/framework-setup-guides/astro#netlify-image-cdn), [Gatsby](https://docs.netlify.com/build/frameworks/framework-setup-guides/gatsby/#netlify-image-cdn), [Next.js](https://docs.netlify.com/build/frameworks/framework-setup-guides/nextjs/overview), [Nuxt](https://docs.netlify.com/build/frameworks/framework-setup-guides/nuxt#netlify-image-cdn).
 
-1. Add the domain to `remote_images` in `netlify.toml`:
-   ```toml
-   [images]
-   remote_images = ["https://example\\.com/.*"]
-   ```
-2. Escape dots in regex patterns with double backslash
-3. Redeploy after updating config
+## Additional constraints
 
-### Images not updating after deploy
+- Deploy behavior: transforms respect [atomic deploys](https://docs.netlify.com/build/caching/caching-overview#automatic-invalidation-with-atomic-deploys); changing a source image in a new deploy re-runs transforms on subsequent requests.
+- [Split Testing](https://docs.netlify.com/manage/monitoring/split-testing/) is NOT supported — image results may be inconsistent across split test branches.
+- Netlify Image CDN is NOT part of Netlify's HIPAA-compliant hosting offering.
 
-**Cause:** Browser or CDN cache serving stale version.
+Interactive parameter playground: https://image-cdn-playground.netlify.app/
 
-**Fix:**
+<!-- system: agent-context/image-cdn/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->
+# Netlify house rules (image-cdn)
 
-1. Use asset fingerprinting (e.g., `/photo-abc123.jpg`) for cache busting
-2. Clear browser cache or use hard refresh
-3. Wait a few minutes for edge cache propagation
+These are org conventions, not docs facts — merged into the rendered skill by
+ctx-gen and never generated. Owned by the skills maintainer.
 
-### Circular redirect error
+1. For user-uploaded image pipelines (Functions + Blobs + Image CDN
+   composed), see `references/user-uploads.md` in this skill — an authored
+   guide with no single docs source.
+2. Percent-encode remote source URLs before placing them in the `url`
+   parameter (`encodeURIComponent`) — URLs containing `?` or `&` break
+   otherwise.
+3. `fm=blurhash` returns a BlurHash TEXT string, not image bytes. Pointing an
+   `<img src>` (or CSS background) at it renders nothing — fetch the string
+   ahead of time, decode it client-side with a BlurHash library, and load the
+   real image as a separate request without `fm=blurhash`.
+4. A local 404 on `/.netlify/images` almost always means a framework dev
+   server (`vite`, `next dev`, `astro dev`) is running instead of
+   `netlify dev` — the endpoint, `[images]` allowlisting, and image redirects
+   only exist under `netlify dev`. The URL itself is usually fine.
+5. In `remote_images` patterns, the meaningful regex escape is the dot;
+   forward slashes are not metacharacters — do not write `https:\/\/`.
+   In `netlify.toml`, use a single-quoted literal string
+   (`'https://example\.com/.*'`) or double the backslash in a
+   double-quoted string (`"https://example\\.com/.*"`) — a bare `\.`
+   inside double quotes is invalid TOML.
 
-**Cause:** Redirect rule creates a loop with the image transformation endpoint.
 
-**Fix:**
+## Additional requirements
 
-1. Ensure redirect `from` path does not overlap with the `to` path
-2. Avoid redirecting `/.netlify/images` to another `/.netlify/images` URL
-3. Use status `200` (rewrite) not `301`/`302` (redirect) when possible
+Only add custom headers to source images when the user explicitly asks.

package/dist/skills/netlify-image-cdn/references/user-uploads.md

@@ -0,0 +1,156 @@
+# User-Uploaded Images Pipeline
+
+Compose Netlify Functions (upload handler) + Netlify Blobs (storage) + Image CDN (serving/transforming) to build a complete user-uploaded image pipeline.
+
+## Architecture
+
+1. **Upload** — A Netlify Function receives multipart form data, validates, and stores in Blobs
+2. **Storage** — Netlify Blobs stores the binary image with metadata
+3. **Serve** — A Netlify Function retrieves the blob and serves it at `/uploads/:key`
+4. **Transform** — A redirect maps `/img/:key` to `/.netlify/images?url=/uploads/:key` for CDN optimization
+
+## Dependencies
+
+```bash
+npm install @netlify/blobs
+```
+
+## Upload Handler
+
+```typescript
+// netlify/functions/upload.ts
+import type { Context, Config } from "@netlify/functions";
+import { getStore } from "@netlify/blobs";
+import { randomUUID } from "crypto";
+
+const ALLOWED_TYPES = ["image/jpeg", "image/png", "image/gif", "image/webp"];
+const MAX_SIZE = 4 * 1024 * 1024; // 4 MB
+
+export default async (req: Request, context: Context) => {
+  if (req.method !== "POST") {
+    return new Response("Method not allowed", { status: 405 });
+  }
+
+  const formData = await req.formData();
+  const image = formData.get("image") as File;
+
+  if (!image) return Response.json({ error: "No image provided" }, { status: 400 });
+  if (!ALLOWED_TYPES.includes(image.type)) return Response.json({ error: "Invalid type" }, { status: 400 });
+  if (image.size > MAX_SIZE) return Response.json({ error: "File too large" }, { status: 400 });
+
+  const extension = image.name.split(".").pop() || "jpg";
+  const key = `${randomUUID()}.${extension}`;
+  const store = getStore({ name: "images", consistency: "strong" });
+
+  await store.set(key, image, {
+    metadata: {
+      contentType: image.type,
+      originalFilename: image.name,
+      uploadedAt: new Date().toISOString(),
+    },
+  });
+
+  return Response.json({ success: true, key, url: `/img/${key}` });
+};
+
+export const config: Config = { path: "/api/upload", method: "POST" };
+```
+
+## Serve Handler
+
+```typescript
+// netlify/functions/serve-image.ts
+import type { Context, Config } from "@netlify/functions";
+import { getStore } from "@netlify/blobs";
+
+export default async (req: Request, context: Context) => {
+  const key = context.params.key;
+  const store = getStore({ name: "images", consistency: "strong" });
+
+  const result = await store.getWithMetadata(key, { type: "stream" });
+  if (!result) return new Response("Not found", { status: 404 });
+
+  return new Response(result.data, {
+    headers: {
+      "Content-Type": result.metadata?.contentType || "image/jpeg",
+      "Cache-Control": "public, max-age=31536000, immutable",
+    },
+  });
+};
+
+export const config: Config = { path: "/uploads/:key" };
+```
+
+## CDN Redirect
+
+```toml
+# netlify.toml
+
+# Basic optimized URL
+[[redirects]]
+from = "/img/:key"
+to = "/.netlify/images?url=/uploads/:key"
+status = 200
+
+# Thumbnail preset
+[[redirects]]
+from = "/img/thumb/:key"
+to = "/.netlify/images?url=/uploads/:key&w=150&h=150&fit=cover"
+status = 200
+
+# Hero preset
+[[redirects]]
+from = "/img/hero/:key"
+to = "/.netlify/images?url=/uploads/:key&w=1200&h=675&fit=cover"
+status = 200
+```
+
+## Client-Side Upload (React Example)
+
+```tsx
+function ImageUpload({ onUpload }: { onUpload: (url: string) => void }) {
+  const handleChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+
+    const formData = new FormData();
+    formData.append("image", file);
+
+    const res = await fetch("/api/upload", { method: "POST", body: formData });
+    const { url } = await res.json();
+    onUpload(url);
+  };
+
+  return <input type="file" accept="image/*" onChange={handleChange} />;
+}
+```
+
+## Astro Upload (API Route)
+
+```typescript
+// src/pages/api/upload.ts
+import type { APIRoute } from "astro";
+import { getStore } from "@netlify/blobs";
+import { randomUUID } from "crypto";
+
+export const POST: APIRoute = async ({ request, redirect }) => {
+  const formData = await request.formData();
+  const image = formData.get("image") as File;
+  if (!image) return new Response("No image", { status: 400 });
+
+  const key = `${randomUUID()}.${image.name.split(".").pop() || "jpg"}`;
+  const store = getStore({ name: "images", consistency: "strong" });
+  await store.set(key, image, {
+    metadata: { contentType: image.type, originalFilename: image.name },
+  });
+
+  return redirect(`/gallery?uploaded=${key}`);
+};
+```
+
+## Key Points
+
+- Always validate file type and size on the server (client validation can be bypassed)
+- Use `strong` consistency on Blobs for immediate reads after writes
+- The serve handler's `Cache-Control: immutable` means the CDN caches the raw image permanently — Image CDN transformations layer on top
+- Without `fm` parameter, Netlify auto-serves AVIF or WebP based on browser support

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/agent-runner-cli",
   "type": "module",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "CLI tool for running Netlify agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -68,6 +68,7 @@
     "@eslint/js": "^10.0.1",
     "@netlify/axis": "^1.21.0",
     "@netlify/eslint-config-node": "^7.0.1",
+    "@netlify/skills": "1.7.0",
     "@types/node": "^24.5.0",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",

package/scripts/build-skills.js

@@ -0,0 +1,52 @@
+import { appendFile, cp, mkdir, readdir, readFile, rm } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const localSkillsDir = new URL('../src/skills/', import.meta.url)
+const sharedPackagePath = createRequire(import.meta.url).resolve('@netlify/skills/package.json')
+const sharedSkillsDir = path.join(path.dirname(sharedPackagePath), 'skills')
+export const bundledSkillsDir = fileURLToPath(new URL('../dist/skills/', import.meta.url))
+const selectedSharedSkills = [
+  { name: 'netlify-access-control' },
+  {
+    name: 'netlify-forms',
+    instructions: new URL('../src/skill-instructions/netlify-forms.md', import.meta.url),
+    assets: new URL('../src/skill-assets/netlify-forms/', import.meta.url),
+  },
+  {
+    name: 'netlify-image-cdn',
+    instructions: new URL('../src/skill-instructions/netlify-image-cdn.md', import.meta.url),
+  },
+]
+
+export const buildSkills = async (targetDir = bundledSkillsDir) => {
+  await rm(targetDir, { recursive: true, force: true })
+  await cp(localSkillsDir, targetDir, { recursive: true })
+
+  for (const { name, instructions, assets } of selectedSharedSkills) {
+    await cp(path.join(sharedSkillsDir, name), path.join(targetDir, name), {
+      recursive: true,
+      force: false,
+      errorOnExist: true,
+    })
+    if (instructions) {
+      await appendFile(path.join(targetDir, name, 'SKILL.md'), `\n\n${await readFile(instructions, 'utf8')}`)
+    }
+    if (assets) {
+      const assetsDir = fileURLToPath(assets)
+      for (const entry of await readdir(assetsDir, { recursive: true, withFileTypes: true })) {
+        if (!entry.isFile()) continue
+        const source = path.join(entry.parentPath, entry.name)
+        const destination = path.join(targetDir, name, path.relative(assetsDir, source))
+        await mkdir(path.dirname(destination), { recursive: true })
+        await cp(source, destination, { force: false, errorOnExist: true })
+      }
+    }
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await buildSkills()
+}

package/scripts/scenarios/install-skills.mjs

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /**
  * Installs the orchestrator's bundled skills into the agent's skill directory
  * by calling `setupAgentSkills` from `src/context.js` — the same function the
@@ -15,10 +14,15 @@
  * Omit `--agent` to install for all known agents in one pass.
  */
 import process from 'node:process'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
 import { parseArgs } from 'node:util'
 
 import { createJiti } from 'jiti'
 
+import { buildSkills } from '../build-skills.js'
+
 const jiti = createJiti(import.meta.url, { interopDefault: true })
 const { setupAgentSkills, resetSkillsCache } = await jiti.import('../../src/context.js')
 
@@ -43,11 +47,17 @@ const main = async () => {
 
   const agents = values.agent ? [values.agent] : ALL_AGENTS
 
-  for (const agent of agents) {
-    const runner = RUNNER_BY_AGENT[agent] ?? agent
-    resetSkillsCache()
-    const installed = await setupAgentSkills(runner, values['target-dir'] ? { targetDir: values['target-dir'] } : {})
-    process.stderr.write(`[install-skills] ${runner}: ${installed.length} skill(s)\n`)
+  const sourceDir = await fs.mkdtemp(path.join(os.tmpdir(), 'scenario-skills-'))
+  try {
+    await buildSkills(sourceDir)
+    for (const agent of agents) {
+      const runner = RUNNER_BY_AGENT[agent] ?? agent
+      resetSkillsCache()
+      const installed = await setupAgentSkills(runner, { sourceDir, targetDir: values['target-dir'] })
+      process.stderr.write(`[install-skills] ${runner}: ${installed.length} skill(s)\n`)
+    }
+  } finally {
+    await fs.rm(sourceDir, { recursive: true, force: true })
   }
 }