# JAE Image Skill — Agent Install File

This markdown file is designed for AI agents to read and execute. Install the JAE Image Skill into the user’s local skills directory, then load `SKILL.md` whenever the user asks for image-prompt recommendations.

## Identity

- Human name: **JAE Image Skill**
- Canonical package/repo name: **JAE-IMAGE-SKILL**
- Local skill folder name: **jae-image-skill**
- Purpose: recommend and customise curated image-generation prompts with sample images for any text-to-image model.
- Canonical install document: `https://jaeswift.xyz/skills/JAE-image-skill/Jae-Image-Skill.MD`
- Canonical reference manifest: `https://jaeswift.xyz/skills/JAE-image-skill/references/manifest.json`
- Preferred Git repo: `https://git.jaeswift.xyz/jae/JAE-IMAGE-SKILL.git`

## Compatibility

Use this for:

- Agent Zero / Agent JAE
- Claude-style skills
- Cursor/Codex/Gemini CLI/Windsurf-style local agents
- Any agent that can read a `SKILL.md` file and local JSON references

## Required runtime

- Node.js 18+ minimum; Node.js 20+ recommended.
- `git`, `curl`, and `bash` recommended.
- `pnpm` is optional and only needed for development scripts.

## Installation algorithm for the AI agent

### Step 1 — choose skills root

Prefer the user’s configured skills directory. If unknown, use one of these common locations:

```bash
# Agent Zero / Agent JAE common user-space path inside container:
/a0/usr/skills

# Generic local fallback:
$HOME/.agent-zero/skills

# Generic agent fallback:
$HOME/.ai/skills
```

Use this shell pattern if no configured directory is known:

```bash
if [ -d /a0/usr/skills ]; then
  SKILLS_DIR=/a0/usr/skills
elif [ -d "$HOME/.agent-zero/skills" ]; then
  SKILLS_DIR="$HOME/.agent-zero/skills"
else
  SKILLS_DIR="$HOME/.ai/skills"
fi
export SKILLS_DIR
```

### Step 2 — install from Git

```bash
set -euo pipefail
: "${SKILLS_DIR:=${HOME}/.ai/skills}"
SKILL_DIR="$SKILLS_DIR/jae-image-skill"
mkdir -p "$SKILLS_DIR"

if [ -d "$SKILL_DIR/.git" ]; then
  git -C "$SKILL_DIR" pull --ff-only
else
  rm -rf "$SKILL_DIR"
  git clone https://git.jaeswift.xyz/jae/JAE-IMAGE-SKILL.git "$SKILL_DIR"
fi

cd "$SKILL_DIR"
node scripts/setup.js --check || node scripts/setup.js
```

### Step 3 — fallback install without Git

If Git access fails, download the static bundle from JaeSwift hosting:

```bash
set -euo pipefail
: "${SKILLS_DIR:=${HOME}/.ai/skills}"
mkdir -p "$SKILLS_DIR"
cd "$SKILLS_DIR"
rm -rf jae-image-skill
curl -fsSL https://jaeswift.xyz/skills/JAE-image-skill/jae-image-skill.tar.gz | tar -xz
cd jae-image-skill
node scripts/setup.js --check || true
```

### Step 4 — validate install

```bash
set -euo pipefail
cd "$SKILLS_DIR/jae-image-skill"
test -s SKILL.md
test -s package.json
test -s scripts/setup.js
test -s references/manifest.json
node - <<'NODE'
const fs = require('fs');
const m = JSON.parse(fs.readFileSync('references/manifest.json','utf8'));
if (!Array.isArray(m.categories) || m.categories.length === 0) throw new Error('No categories in manifest');
if (typeof m.totalPrompts !== 'number') throw new Error('Bad totalPrompts');
for (const c of m.categories) {
  if (!c.file || !fs.existsSync(`references/${c.file}`)) throw new Error(`Missing ${c.file}`);
  const arr = JSON.parse(fs.readFileSync(`references/${c.file}`,'utf8'));
  if (!Array.isArray(arr) || arr.length !== c.count) throw new Error(`Bad count for ${c.file}`);
}
console.log(`JAE Image Skill OK: ${m.categories.length} categories, ${m.totalPrompts} unique prompts`);
NODE
```

## How the installed agent should use the skill

1. Read `SKILL.md`.
2. Read `references/manifest.json` first.
3. Pick relevant category files from the manifest.
4. Do **not** load huge JSON files wholesale into model context.
5. Search using `rg`, `grep`, `jq`, Node.js, Python, or streaming JSON parsing.
6. Return up to 3 prompt recommendations.
7. Include sample image URLs from `sourceMedia[0]` whenever available.
8. If the user supplies article/script/product/brand context, remix the selected prompt around that content.

## Minimum file layout after install

```text
jae-image-skill/
  SKILL.md
  README.md
  package.json
  LICENSE
  NOTICE
  scripts/setup.js
  references/manifest.json
  references/*.json
```

## Refresh references

Agents should treat `references/manifest.json` as the entry point. Do not rely on directory listing; `/references/` is only a human-readable index page.


```bash
cd "$SKILLS_DIR/jae-image-skill"
node scripts/setup.js --force
```

The default refresh source is:

```text
https://jaeswift.xyz/skills/JAE-image-skill/references/manifest.json
```

To use a mirror:

```bash
JAE_IMAGE_SKILL_BASE_URL=https://example.com/references node scripts/setup.js --force
```

## Troubleshooting

- `node: fetch is not defined` — upgrade to Node.js 18+; Node.js 20+ recommended.
- `HTTP 404` — check URL case. The public path is case-sensitive: `/skills/JAE-image-skill/`.
- `references/manifest.json missing` — run `node scripts/setup.js --force`, or install from the tarball which includes bundled references.
- Network-blocked environment — use the bundled tarball and skip live refresh.
- Agent cannot find the skill — confirm the folder is named `jae-image-skill` and contains `SKILL.md` at the top level.

## Licence

JAE-IMAGE-SKILL is distributed under the MIT licence. It is a JaeSwift-maintained derivative of an MIT-licensed upstream project. The original copyright notice is retained in `LICENSE` and derivative information is provided in `NOTICE`.