# agnes-ai-skill

Adopt this skill: https://proskills.md/skills/other/jomeswang-agnes-ai-skill

Page: https://proskills.md/skills/other/jomeswang-agnes-ai-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 17324
sha: edd3830b7df2033eaae28295475df9306ff016cb
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/SKILL.md

````text
---
name: agnes-ai-skill
version: 1.2.2
description: "Use when the user wants Agnes AI text, image, or video generation and should execute it through the agnes-ai-cli command line instead of hand-writing raw HTTP requests."
tags:
  - agnes
  - agnes-ai
  - agnes-skill
  - multimodal-ai
  - free-ai-api
  - free-ai-model
  - text-generation
  - image-generation
  - ai-image-generation
  - text-to-image
  - image-editing
  - image-to-image
  - video-generation
  - ai-video-generation
  - text-to-video
  - image-to-video
  - api-integration
  - agent-skill
  - codex
  - claude-code
  - openclaw
metadata:
  openclaw:
    emoji: "sparkles"
    homepage: "https://github.com/jomeswang/agnes-ai-skill"
    requires:
      bins:
        - npm
        - npx
        - node
    primaryEnv: AGNES_API_KEY
    envVars:
      - name: AGNES_API_KEY
        required: false
        description: Agnes API key used for live authenticated text, image, and video requests. The skill can still load without it and guide setup.
---

# Agnes AI Skill

Use this skill when the user wants Agnes AI text, image, or video generation.
This skill is now **CLI-first**: prefer `agnes-ai-cli` for all live execution,
guide the user through `--help` when needed, and do not default to hand-written
`curl` commands for Agnes work.

Agnes is attractive because one platform covers:

- text with `agnes-2.0-flash`
- image generation and editing with `agnes-image-2.1-flash` and
  `agnes-image-2.0-flash`
- video generation with `agnes-video-v2.0`

Some public June 2026 materials positioned Agnes as broadly free to try. The
live docs also include pricing sections, so treat that free-access message as a
strong but time-sensitive positioning claim and verify current billing when the
user cares about cost.

## When To Use

Use this skill when:

- the user mentions Agnes AI, `agnes-ai.com`, or the Agnes platform
- the user wants one provider for text, image, and video generation
- the user wants Agnes text, image, or video APIs executed from a terminal
- the user wants image-to-image, multi-image composition, image-to-video, or
  keyframe video generation
- the user wants a low-friction multimodal API for prototyping, agent loops,
  creative iteration, ecommerce content, or storyboard work

Do not use this skill when:

- the user is asking for a different provider only
- the task does not need Agnes-specific models, auth, or request behavior
- you would have to guess current Agnes behavior without running the CLI or
  checking the live docs

## Source Of Truth

Prefer these Agnes pages:

- Quickstart: `https://agnes-ai.com/doc/quickstart`
- API key page: `https://platform.agnes-ai.com/settings/apiKeys`
- Text docs: `https://agnes-ai.com/doc/agnes-20-flash`
- Image 2.0 docs: `https://agnes-ai.com/doc/agnes-image-20-flash`
- Image 2.1 docs: `https://agnes-ai.com/doc/agnes-image-21-flash`
- Video docs: `https://agnes-ai.com/doc/agnes-video-v20`
- Published CLI: `https://www.npmjs.com/package/agnes-ai-cli`
- CLI repo: `https://github.com/jomeswang/agnes-ai-cli`

Use public articles only as supporting context for likely use cases and product
positioning, not as the operational source of truth.

## Base URL And Auth

- Base URL: `https://apihub.agnes-ai.com/v1`
- Main environment variable: `AGNES_API_KEY`
- Preferred execution package: `agnes-ai-cli`

Check `AGNES_API_KEY` before making live Agnes requests.

## Missing Key Behavior

If `AGNES_API_KEY` is missing and the task requires live Agnes access:

1. Tell the user Agnes access is not configured yet.
2. Point them to:
   - `https://agnes-ai.com/doc/quickstart`
   - `https://platform.agnes-ai.com/settings/apiKeys`
3. Explain the path briefly:
   `Settings -> API Keys -> Create new secret key`
4. Ask them to provide the key if they want you to save it for future use.

Do not continue with live Agnes calls until a valid key exists.

## Chinese Quick Start Response

When a Chinese-speaking user asks how to get started, install, or use Agnes
from an agent tool, give them this concise copy-paste path:

```text
Please read and install Agnes AI Skill: https://github.com/jomeswang/agnes-ai-skill
```

Then explain:

- install the skill into the agent's skill directory or use a repository-aware
  installer such as `npx skills add jomeswang/agnes-ai-skill -g`
- create an Agnes API key at `https://platform.agnes-ai.com/settings/apiKeys`
  and configure it as `AGNES_API_KEY`
- say `generate an image`, `generate a video`, or `integrate Agnes API`
- the agent should choose the proper Agnes model and use `agnes-ai-cli` when it
  is available

Keep this onboarding short before moving into model-specific details.

## Persisting The Key Permanently

If the user explicitly gives you an Agnes key and wants it remembered, persist
it for future terminal sessions instead of keeping it only in the current
process.

### Rules

- Save it as `AGNES_API_KEY`
- Detect the shell and write to the matching rc file:
  - zsh -> `~/.zshrc`
  - bash -> `~/.bashrc`
  - fallback -> `~/.profile`
- Update an existing `export AGNES_API_KEY=...` line if present
- Otherwise append a new export line
- Also export it in the current session immediately
- Do not echo the full key back after saving
- Tell the user which rc file you changed

### Reliable Shell Snippet

Use a non-interactive shell flow like this when saving a provided key:

```bash
AGNES_API_KEY_VALUE='USER_PROVIDED_KEY'
shell_name="$(basename "${SHELL:-}")"
case "$shell_name" in
  zsh) rc_file="$HOME/.zshrc" ;;
  bash) rc_file="$HOME/.bashrc" ;;
  *) rc_file="$HOME/.profile" ;;
esac

touch "$rc_file"
tmp_file="$(mktemp)"
grep -v '^export AGNES_API_KEY=' "$rc_file" > "$tmp_file" || true
printf '\nexport AGNES_API_KEY=%q\n' "$AGNES_API_KEY_VALUE" >> "$tmp_file"
mv "$tmp_file" "$rc_file"
export AGNES_API_KEY="$AGNES_API_KEY_VALUE"
unset AGNES_API_KEY_VALUE
```

After saving, continue using `AGNES_API_KEY` for the current task.

## Execution Contract

This skill should execute Agnes through the CLI, not by manually composing raw
HTTP requests.

### Preferred Order

1. First use the no-install command path:
   - `npx -y agnes-ai-cli@^0.1.0 --help`
2. Use `npx -y agnes-ai-cli@^0.1.0 ...` as the default live execution path
   in fresh or unknown environments.
3. If a local `agnes` binary already exists, run:
   - `agnes --version`
   - `agnes --help`
4. Use the local binary only when its version falls inside:
   - `>=0.1.0 <0.2.0`
5. Do not fall back to raw `curl` for normal Agnes execution paths.

### Why CLI-First

The CLI already handles:

- auth checks
- local file to temporary public URL bridging
- image request normalization
- video task creation
- video polling
- JSON output for agent consumption

That means the agent should select the right CLI command, not rebuild the
underlying HTTP payload each time.

## Mandatory `--help` Guidance

When the user is new to the CLI, or when you are about to use a less common
command, guide through `--help` first.

At minimum, know these help entry points:

```bash
npx -y agnes-ai-cli@^0.1.0 --help
npx -y agnes-ai-cli@^0.1.0 auth --help
npx -y agnes-ai-cli@^0.1.0 media --help
npx -y agnes-ai-cli@^0.1.0 text chat --help
npx -y agnes-ai-cli@^0.1.0 image text2img --help
npx -y agnes-ai-cli@^0.1.0 image img2img --help
npx -y agnes-ai-cli@^0.1.0 image compose --help
npx -y agnes-ai-cli@^0.1.0 video text2video --help
npx -y agnes-ai-cli@^0.1.0 video img2video --help
npx -y agnes-ai-cli@^0.1.0 video multivideo --help
npx -y agnes-ai-cli@^0.1.0 video keyframes --help
npx -y agnes-ai-cli@^0.1.0 video poll --help
```

If `agnes` is already installed globally and version-compatible, you can drop
the `npx -y agnes-ai-cli@^0.1.0` prefix and run the same subcommands directly.

## Model Selection

Choose the smallest suitable Agnes model path:

- `agnes-2.0-flash`
  - chat, coding, tool calling, structured agent work, fast production tasks
  - default when `text chat` runs without `--model`
- `agnes-image-2.1-flash`
  - default for new text-to-image and straightforward image-to-image work
  - especially useful for denser layouts and stronger semantic alignment
  - default when `image text2img`, `image img2img`, or `image compose` runs
    without `--model`
- `agnes-image-2.0-flash`
  - use when the user explicitly wants Image 2.0
  - useful for edit-heavy or multi-image composition flows
- `agnes-video-v2.0`
  - use for text-to-video, image-to-video, multi-image guided video, and
    keyframes
  - current default when any `video` generate command runs without `--model`

## CLI Command Map

### Auth

```bash
npx -y agnes-ai-cli@^0.1.0 auth check
npx -y agnes-ai-cli@^0.1.0 auth save-key --key 'YOUR_KEY'
```

Use `auth check` before live requests when auth may be missing.

### Media URL Bridge

```bash
npx -y agnes-ai-cli@^0.1.0 media url ./local-image.png
npx -y agnes-ai-cli@^0.1.0 media url https://example.com/already-remote.png
```

Use this when the user gives a local image path and Agnes needs a public image
URL. The CLI handles the temporary upload bridge automatically.

### Text

```bash
npx -y agnes-ai-cli@^0.1.0 text chat --prompt "Reply with exactly pong."
```

Use this for one-shot text verification, coding help, or small agent checks.
If `--model` is omitted here, the CLI defaults to `agnes-2.0-flash`.

### Image

```bash
npx -y agnes-ai-cli@^0.1.0 image text2img --prompt "A premium studio product photo of a perfume bottle"

npx -y agnes-ai-cli@^0.1.0 image img2img \
  --image ./input.png \
  --prompt "Turn this into a refined editorial campaign visual"

npx -y agnes-ai-cli@^0.1.0 image compose \
  --image ./subject.png \
  --image ./reference.png \
  --prompt "Blend these references into one polished commercial still"
```

Use:

- `text2img` for prompt-only image generation
- `img2img` for one input image
- `compose` for multiple input images
- if `--model` is omitted, the CLI defaults to `agnes-image-2.1-flash`

### Video

```bash
npx -y agnes-ai-cli@^0.1.0 video text2video \
  --prompt "A cinematic beach scene at dusk"

npx -y agnes-ai-cli@^0.1.0 video img2video \
  --image ./frame.png \
  --prompt "Add subtle wind and a slow camera push"

npx -y agnes-ai-cli@^0.1.0 video multivideo \
  --image ./frame-a.png \
  --image ./frame-b.png \
  --prompt "Blend these frames into one smooth motion concept"

npx -y agnes-ai-cli@^0.1.0 video keyframes \
  --image ./frame-a.png \
  --image ./frame-b.png \
  --prompt "Transition between these frames with a polished morph"

npx -y agnes-ai-cli@^0.1.0 video poll video_123 --interval 5 --timeout 600
```

Use:

- `text2video` for prompt-only video
- `img2video` for one image input
- `multivideo` for multiple guiding images
- `keyframes` for explicit keyframe interpolation
- `poll` for asynchronous completion
- if `--model` is omitted, current CLI behavior uses `agnes-video-v2.0`

## Practical CLI Workflow

### Text Verification

1. `npx -y agnes-ai-cli@^0.1.0 text chat --help`
2. `npx -y agnes-ai-cli@^0.1.0 text chat --prompt "Reply with exactly pong." --json`

### Text-To-Image

1. `npx -y agnes-ai-cli@^0.1.0 image text2img --help`
2. run `npx -y agnes-ai-cli@^0.1.0 image text2img ... --json`
3. read the returned image URL

### Image-To-Image

1. `npx -y agnes-ai-cli@^0.1.0 image img2img --help`
2. if the user gave a local path, let the CLI bridge it automatically
3. run `npx -y agnes-ai-cli@^0.1.0 image img2img ... --json`

### Multi-Image Composition

1. `npx -y agnes-ai-cli@^0.1.0 image compose --help`
2. pass `--image` multiple times
3. run with `npx -y agnes-ai-cli@^0.1.0 image compose ... --json`

### Text-To-Video

1. `npx -y agnes-ai-cli@^0.1.0 video text2video --help`
2. run `npx -y agnes-ai-cli@^0.1.0 video text2video ... --json`
3. capture `videoId`
4. run `npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json`

### Image-To-Video

1. `npx -y agnes-ai-cli@^0.1.0 video img2video --help`
2. if the user gave a local path, let the CLI bridge it automatically
3. run `npx -y agnes-ai-cli@^0.1.0 video img2video ... --json`
4. capture `videoId`
5. run `npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json`

### Keyframes

1. `npx -y agnes-ai-cli@^0.1.0 video keyframes --help`
2. pass `--image` at least twice
3. run `npx -y agnes-ai-cli@^0.1.0 video keyframes ... --json`
4. capture `videoId`
5. run `npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json`

## Image Guidance

Use the CLI as the execution layer, but keep these Agnes-specific rules in mind:

- Image 2.1 is the default for most new image work
- Image 2.0 is useful for edit-heavy or multi-image composition work
- For edits, explicitly separate:
  - what should change
  - what must stay fixed
- For dense images, be explicit about:
  - primary subject
  - background environment
  - important secondary details
  - style and lighting
  - composition constraints

## Video Guidance

Use the CLI as the execution layer, but keep these Agnes-specific rules in mind:

- the API is asynchronous
- `num_frames` must be `<= 441`
- `num_frames` must satisfy `8n + 1`
- `frame_rate` supports `1-60`
- common safe example settings are:
  - `width: 1152`
  - `height: 768`
  - `num_frames: 121`
  - `frame_rate: 24`
- for keyframes, use the dedicated CLI subcommand instead of inventing your
  own payload shape

For text-to-video prompts, describe:

- subject
- action
- environment
- camera movement
- lighting
- style

For image-to-video prompts, describe:

- what should move
- what should stay stable
- how subtle or dramatic the motion should be

For keyframes and multi-image work, describe:

- how the inputs relate
- what continuity should remain stable
- what transition feeling is desired

## JSON Output

Prefer `--json` whenever the command result will be consumed by the agent.

Examples:

```bash
npx -y agnes-ai-cli@^0.1.0 image text2img --prompt "..." --json
npx -y agnes-ai-cli@^0.1.0 video text2video --prompt "..." --json
npx -y agnes-ai-cli@^0.1.0 video poll video_123 --json
```

This makes it easier to:

- read `taskId` and `videoId`
- extract image URLs
- extract final video URLs
- detect failures cleanly

## Operational Guidance

- Supported companion CLI range for this skill release:
  - `>=0.1.0 <0.2.0`
- Prefer live CLI tests over guessing when the user asks whether a model path
  or parameter actually works.
- For image results, expect a URL in the response.
- For video results, expect task creation first, then polling.
- Prefer `videoId` for polling. Passing an older `taskId` remains compatible
  through the CLI's legacy endpoint routing.
- Use the CLI's local-file bridge instead of manually uploading files yourself
  unless the user explicitly wants a separate upload step.
- If the user asks for SDK code, translate the confirmed CLI behavior into the
  target language only after the CLI path has been validated.
- If the user asks about pricing, limits, or free access, verify the live docs.

## Compact Reference

- Base URL: `https://apihub.agnes-ai.com/v1`
- Text endpoint behind CLI: `/chat/completions`
- Image endpoint behind CLI: `/images/generations`
- Video create endpoint behind CLI: `/videos`
- Video recommended poll endpoint behind CLI: `/agnesapi?video_id={video_id}`
- Video legacy poll endpoint behind CLI: `/videos/{task_id}`

- Text model: `agnes-2.0-flash`
- Image model: `agnes-image-2.1-flash`
- Image compatibility model: `agnes-image-2.0-flash`
- Video model: `agnes-video-v2.0`

## Do Not

- Do not proceed with live Agnes calls when the key is missing
- Do not default to raw `curl` for Agnes execution in this skill
- Do not rebuild request payloads by hand when the CLI already covers the flow
- Do not skip `video poll` and assume video generation is synchronous
- Do not trust stale marketing claims over the current API docs

## Safety

- Never echo a full Agnes API key back to the user after it has been supplied
- Never continue with live Agnes requests when auth is missing or clearly
  invalid
- Never treat article copy or marketing claims as more authoritative than the
  official Agnes docs
- Never promise pricing, limits, or "forever free" terms without noting they
  can change over time
- Never write the key to a project file unless the user explicitly asks for
  that behavior

## Installation

With repository-aware skill installers:

```bash
npx skills add jomeswang/agnes-ai-skill -g
```

After installation, invoke this skill whenever Agnes setup or Agnes model usage
comes up.

## Version History

- `1.2.2` - Added a linked Chinese README and Chinese quick-start onboarding
  guidance for agent responses.
- `1.2.1` - Made `npx -y agnes-ai-cli@^0.1.0` the default copy-paste execution
  path in fresh environments and kept global `agnes` as an optional fast path.
- `1.2.0` - Switched the skill to CLI-first Agnes execution, removed raw curl
  execution guidance, and made `--help` discovery part of the expected flow.
- `1.1.2` - Added dual-track CLI guidance so agents prefer the separate Agnes
  execution layer when available and keep raw `curl` as the fallback.
- `1.1.0` - Expanded official doc coverage for Image 2.0, Image 2.1, and Video
  2.0 parameters, scenarios, prompt structures, response fields, and task
  states.
- `1.0.0` - Initial public release with Agnes platform setup, persistent auth,
  text, image, and video workflow guidance.
````

## File: README.md
size: 16027
sha: bf60ed361b19dd1fbe5ba27a8ba748e60319a1b2
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/README.md

````text
# Agnes AI Free Text, Image & Video Generation Skill

[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-SKILL.md-blue)](./SKILL.md)
[![Models](https://img.shields.io/badge/models-text%20%7C%20image%20%7C%20video-black)](https://agnes-ai.com/doc)
[![Agnes AI](https://img.shields.io/badge/platform-Agnes%20AI-ff6b3d)](https://platform.agnes-ai.com/)
[![Chinese README](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-blue)](./README.zh-CN.md)

Agnes AI Skill is a free multimodal Agent Skill for Codex, Claude Code,
OpenClaw, Claude Desktop, Hermes, WorkBuddy, Cherry Studio, Opencode, and
similar AI agent tools. It helps agents use Agnes 2.0 APIs for text generation,
image generation, image editing, text-to-video, image-to-video, and API
integration through a single root `SKILL.md`.

Use this Agnes skill when you want an Agnes AI skill, image generation skill,
video generation skill, text to image workflow, image to video workflow, free AI API
workflow, or free AI model workflow that fits Codex skills, Claude Code skills,
and OpenClaw skills.

中文：Agnes AI 免费文本 / 生图 / 图片编辑 / 生视频 Agent Skill，支持 Codex、
Claude Code、OpenClaw、Claude Desktop、Hermes、WorkBuddy、Cherry Studio、
Opencode 等工具。

## Quick Start

Install the skill with a repository-aware skills installer:

```bash
npx skills add jomeswang/agnes-ai-skill -g
```

Or copy this sentence to your agent:

```text
Please read and install Agnes AI Skill: https://github.com/jomeswang/agnes-ai-skill
```

After installation, create an Agnes API key at
[platform.agnes-ai.com/settings/apiKeys](https://platform.agnes-ai.com/settings/apiKeys)
and configure it as `AGNES_API_KEY`. Then tell the agent `generate an image`,
`generate a video`, `edit this image`, or `integrate Agnes API`, and it can
choose the proper Agnes model and execution path automatically.

This skill helps agents:

- set up Agnes AI and persist an `AGNES_API_KEY`
- use `agnes-2.0-flash` for chat, coding, streaming, and tool calling
- use `agnes-image-2.0-flash` and `agnes-image-2.1-flash` for AI image
  generation, image editing, and image-to-image workflows
- use `agnes-video-v2.0` for text-to-video, image-to-video, and async video
  generation
- prefer the companion `agnes-ai-cli` for live requests

Compatible tools: Codex, Claude Code, Claude Desktop, OpenClaw, Hermes,
WorkBuddy, Cherry Studio, Opencode, Kimi Work, and other Agent Skills /
SKILL.md-compatible environments.

![Agnes AI frontier models hero](./assets/images/agnes-frontier-models-banner.jpg)

## Important Announcement

**Agnes 2.0 full-modal model APIs are officially open for free global calls.**

- No fixed end date, full-modal access, and free API calls within RPM 20
- Register on the official platform, create a key, and call directly
- Text, image, and video are all supported
- Models keep upgrading while free access is maintained

**Official platform:** https://platform.agnes-ai.com

> The live official model docs also include pricing sections. For cost, quota,
> or commercial use, check the current official docs first.

This repository packages a single root `SKILL.md` so coding agents can quickly:

- get and persist an Agnes API key
- use `agnes-2.0-flash` for chat, coding, streaming, and tool calling
- use `agnes-image-2.0-flash` and `agnes-image-2.1-flash` for image generation
  and editing
- use `agnes-video-v2.0` for asynchronous video generation and polling

It is designed for the exact pitch that makes Agnes easy to try:

- one provider for text, image, and video
- public free-access positioning that lowers experimentation friction
- agent, creative, and prototyping workflows where repeated calls matter

The skill stays intentionally lightweight. It teaches agents how to make Agnes
API calls successfully without copying the full docs into the repository.

## Install

With a repository-aware skills installer:

```bash
npx skills add jomeswang/agnes-ai-skill -g
```

Because this repository uses a single root `SKILL.md`, installers that support
repository-root skills can discover it directly.

### Verified Install Path

This repository has been validated with:

```bash
npx skills add jomeswang/agnes-ai-skill --list
npx skills add jomeswang/agnes-ai-skill --agent codex --yes
```

The repository is discoverable as a single root-level skill named
`agnes-ai-skill`.

## Companion CLI

The published companion execution layer is:

- npm: [`agnes-ai-cli`](https://www.npmjs.com/package/agnes-ai-cli)
- GitHub: [`jomeswang/agnes-ai-cli`](https://github.com/jomeswang/agnes-ai-cli)

Install it when you want stable commands instead of hand-written requests:

```bash
npm install -g agnes-ai-cli
agnes --help
```

## Model Guide

Use the repository skill with these defaults:

- `agnes-2.0-flash`
  - chat, coding, streaming, tool calling, and agent workflows
  - default when `text chat` runs without `--model`
- `agnes-image-2.1-flash`
  - default for new text-to-image and image-to-image work
  - strongest fit for denser layouts, richer detail, and better semantic
    alignment
  - default when `image text2img`, `image img2img`, or `image compose` runs
    without `--model`
- `agnes-image-2.0-flash`
  - better when you explicitly need its documented `tags: ["img2img"]` flow,
    multi-image composition, or `seed`-based reproducibility
- `agnes-video-v2.0`
  - text-to-video, image-to-video, multi-image guided video, keyframes, and
    asynchronous polling
  - current default when any `video` generate command runs without `--model`

The official docs also give each model fairly different best practices:

- Image 2.1 leans into high-information-density visuals and composition
  preservation
- Image 2.0 is more explicit about edit/composition workflows, response fields,
  and OpenAI Images-style compatibility
- Video 2.0 is task-based and documents multiple generation modes, task states,
  result polling, and frame-count constraints

## Showcase

The strongest outside prompt libraries all do the same three things well:
lead with a preview, keep the prompt compact enough to scan, and organize
examples by outcome instead of by raw API parameter lists. This gallery follows
that pattern with 9 compact cases regenerated with Agnes on June 1, 2026. The
image prompts were tightened toward the shorter, more editorial style seen in
`awesome-gpt-image-2`, the video prompts were rebuilt around ad-film,
animation, and cinematic beats inspired by `awesome-seedance`, and the HTML
cases were regenerated as brighter, more public-facing product experiences.

### Image Cases

`agnes-image-2.1-flash`

| Preview | Case | Model | Prompt recipe |
| --- | --- | --- | --- |
| [![Y2K golden hour portrait](./assets/images/y2k-golden-hour.png)](./assets/images/y2k-golden-hour.png) | Y2K golden hour portrait | `agnes-image-2.1-flash` | Candid blonde portrait, baby-pink velour tracksuit, butterfly clips, glossy lips, palm trees, warm golden hour, real skin texture, soft film grain. |
| [![Pencil editorial fashion](./assets/images/pencil-editorial-fashion.png)](./assets/images/pencil-editorial-fashion.png) | Pencil editorial fashion | `agnes-image-2.1-flash` | Minimal monochrome pencil-sketch fashion portrait, round sunglasses, rolled white shirt, denim overalls, combat boots, burnt-orange circle, indie magazine composition. |
| [![Brand envelope perfume ad](./assets/images/brand-envelope-perfume.png)](./assets/images/brand-envelope-perfume.png) | Brand-envelope perfume ad | `agnes-image-2.1-flash` | Dusty-rose brand world, travertine pedestal, translucent perfume bottle, matte cream paper curves, warm studio light, quiet-luxury beauty campaign. |

### Video Cases

`agnes-video-v2.0`

| Preview | Case | Model | Prompt recipe |
| --- | --- | --- | --- |
| [![Perfume ad film first frame](./assets/video-previews/ad-film-10s.jpg)](./assets/videos/ad-film-10s.mp4) | Perfume ad film | `agnes-video-v2.0` | Ten-second luxury commercial with macro bottle details, orbiting reflections, atomizer tension beat, champagne-gold glow, and a final hero reveal built for premium beauty launch pages. |
| [![Mechanical otter animation short first frame](./assets/video-previews/animation-film-10s.jpg)](./assets/videos/animation-film-10s.mp4) | Mechanical otter animation short | `agnes-video-v2.0` | Ten-second animated short: fearless otter pilot bursts through a clockwork engine room, expressive face, hand-painted adventure energy, cinematic action timing, family-film clarity. |
| [![Desert cinematic film scene first frame](./assets/video-previews/cinema-film-10s.jpg)](./assets/videos/cinema-film-10s.mp4) | Desert cinematic film scene | `agnes-video-v2.0` | Ten-second widescreen film moment: lone traveler crosses a dust-heavy desert test site, sculptural machine in the background, restrained grading, prestige sci-fi drama mood. |

### App Cases

`agnes-2.0-flash`

Single-file HTML demos generated from Agnes text prompts and saved in
[`examples/apps`](./examples/apps).

| Preview | Case | Model | Prompt recipe |
| --- | --- | --- | --- |
| [![Agnes AI official-style homepage](./assets/apps/cinematic-ai-landing.jpg)](./examples/apps/cinematic-ai-landing.html) | Agnes AI official-style homepage | `agnes-2.0-flash` | Fresh one-file official product homepage for Agnes AI, bright premium palette, strong platform nav, enterprise hero copy, high-clarity call-to-action hierarchy. |
| [![Lantern Sprint mini-game](./assets/apps/beijing-map-ui.jpg)](./examples/apps/beijing-map-ui.html) | Lantern Sprint mini-game | `agnes-2.0-flash` | Fresh browser mini-game with bright festival palette, instant start state, arcade score loop, keyboard and touch controls, polished one-file mobile-friendly presentation. |
| [![Golden Hour Stories promo page](./assets/apps/watch-experience.jpg)](./examples/apps/watch-experience.html) | Golden Hour Stories promo page | `agnes-2.0-flash` | Fresh campaign landing page for Agnes image and video outputs, soft daylight tones, editorial serif hero, luxury launch framing, clear promotional storytelling. |

## Why Agnes

Agnes is most interesting when one workflow needs all three layers together:

- text for planning, coding, prompting, and agent loops
- image for marketing, e-commerce, and creative visual generation
- video for storyboards, product demos, motion tests, and short-form content

The supplied public writeups consistently frame Agnes as useful for:

- rapid AI product prototyping
- high-frequency agent workflows where repeated model calls matter
- frontend or HTML generation
- marketing and e-commerce creatives
- ad, storyboard, and cinematic short-video iteration

This skill turns that platform surface into one reusable installation target for
Codex and other SKILL.md-compatible agents, with guidance that helps the agent
choose the right Agnes model and authenticate cleanly.

## What It Does

- Platform and auth flow from the Agnes quickstart docs
- API key creation via the Agnes platform settings page
- Persistent `AGNES_API_KEY` setup for future sessions
- OpenAI-style request patterns for text and image endpoints
- Asynchronous task workflow for video generation
- Practical use cases reinforced by the supplied public writeups

## Why The Free Angle Matters

- Agnes is unusually compelling when one platform covers text, image, and video
  together.
- The strongest growth hook in its public messaging is not just quality, but
  the promise of lower-cost or broadly free experimentation.
- That matters most for agents, prototypes, content pipelines, and repeated
  A/B-style creative iteration.
- In practice, treat this as a major adoption advantage, while still verifying
  the current live billing terms before promising zero cost.

## Model Quick Reference

| Model | Best for | Endpoint | Required fields | Special fields / caveats |
| --- | --- | --- | --- | --- |
| `agnes-2.0-flash` | chat, coding, streaming, tool calling, agent loops | `/v1/chat/completions` | `model`, `messages` | OpenAI-style `tools`, `tool_choice`, `stream` |
| `agnes-image-2.1-flash` | new text-to-image, image-to-image, denser layouts, composition-preserving edits | `/v1/images/generations` | `model`, `prompt` | `size`, `extra_body.image`, `extra_body.response_format`; strongest fit for high-information-density scenes |
| `agnes-image-2.0-flash` | edit-heavy workflows, multi-image composition, compatibility-style image flows | `/v1/images/generations` | `model`, `prompt` | often pair with `tags: ["img2img"]`; supports `seed`, `extra_body.image`, `extra_body.response_format` |
| `agnes-video-v2.0` | text-to-video, image-to-video, multi-image guided video, keyframes | create: `/v1/videos`; poll: `/agnesapi?video_id={video_id}` | `model`, `prompt` | asynchronous task workflow; create returns `taskId` and `videoId`; use `videoId` for polling, while older `taskId` polling remains legacy-compatible |

## Pricing / Operational Caveats

- The official Image 2.0, Image 2.1, and Video 2.0 docs currently include
  pricing sections.
- Some public writeups still frame Agnes as broadly free or indefinitely free.
- The Video 2.0 docs are also operationally time-sensitive: the same page can
  mix concrete price figures with "pricing to be announced" style notes.
- Treat all pricing, free-tier, and billing claims as live-doc verified only.

## Safety Model

- The skill checks for `AGNES_API_KEY` before live requests
- If the key is missing, it points the user to the official Agnes quickstart
  and API key page instead of guessing
- If the user provides a key and wants it remembered, the skill persists
  `AGNES_API_KEY` in the correct shell rc file for future sessions
- Live payloads and response handling stay grounded in Agnes docs and real API
  behavior, not only in marketing copy

## Manual Install

Copy this repository into any standard skills location supported by your agent,
for example:

- Codex: `~/.codex/skills/agnes-ai-skill`
- Claude Code: `~/.claude/skills/agnes-ai-skill`
- Cursor: `~/.cursor/skills/agnes-ai-skill`

## What Agents Learn

- How to detect missing Agnes auth before making live calls
- How to guide the user to create an API key
- How to persist `AGNES_API_KEY` in shell startup files for future sessions
- How to choose between Agnes text, image, and video models
- How to make the smallest reliable live request first
- How to poll Agnes video tasks until they complete

## Discovery Notes

- GitHub repository: [jomeswang/agnes-ai-skill](https://github.com/jomeswang/agnes-ai-skill)
- Public repository topics:
  `agent-skills`, `ai-agent-skills`, `codex-skills`, `multimodal-ai`, `agnes-ai`
- These topics improve discoverability across GitHub-linked skill directories
  and crawler-based ecosystems.
- The repository is ready for third-party skill hub submission, including
  ClawHub-style marketplaces that read `SKILL.md` metadata.

## Primary Sources

- Agnes quickstart: [https://agnes-ai.com/doc/quickstart](https://agnes-ai.com/doc/quickstart)
- API key settings:
  [https://platform.agnes-ai.com/settings/apiKeys](https://platform.agnes-ai.com/settings/apiKeys)
- Text model:
  [https://agnes-ai.com/doc/agnes-20-flash](https://agnes-ai.com/doc/agnes-20-flash)
- Image 2.0:
  [https://agnes-ai.com/doc/agnes-image-20-flash](https://agnes-ai.com/doc/agnes-image-20-flash)
- Image 2.1:
  [https://agnes-ai.com/doc/agnes-image-21-flash](https://agnes-ai.com/doc/agnes-image-21-flash)
- Video:
  [https://agnes-ai.com/doc/agnes-video-v20](https://agnes-ai.com/doc/agnes-video-v20)

## Notes

- The public materials supplied with this repository describe Agnes as offering
  free access to its core multimodal APIs as of June 1, 2026. Treat pricing and
  promotion details as time-sensitive and verify them in the platform if cost
  matters.
- ClawHub publishing requires a separate ClawHub login or publish token plus a
  GitHub OAuth grant.
- This repository is released under the MIT License.
````

## File: scripts/agnes-media-url.sh
size: 904
sha: c5c10464edf43f723b999025a10c64a6c2c333e9
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/scripts/agnes-media-url.sh

```text
#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<'EOF'
Usage:
  agnes-media-url.sh <file-or-url> [ttl]

Examples:
  agnes-media-url.sh ./frame.png
  agnes-media-url.sh ./frame.png 12h
  agnes-media-url.sh https://example.com/frame.png

If the input is already an http(s) URL, the script prints it unchanged.
If the input is a local file path, the script uploads it to Litterbox and
prints the resulting temporary public URL.
EOF
}

if [[ "${1:-}" == "-h" || "${1:-}" == "--help" || $# -lt 1 ]]; then
  usage
  exit 0
fi

input="$1"
ttl="${2:-1h}"

if [[ "$input" =~ ^https?:// ]]; then
  printf '%s\n' "$input"
  exit 0
fi

if [[ ! -r "$input" ]]; then
  printf 'Input must be a readable file path or an http(s) URL: %s\n' "$input" >&2
  exit 1
fi

curl -sS https://litterbox.catbox.moe/resources/internals/api.php \
  -F "reqtype=fileupload" \
  -F "time=${ttl}" \
  -F "fileToUpload=@${input}"
```

## File: scripts/extract_first_frames.swift
size: 2245
sha: 09114cdb6b0cac181dcec55b07e5599ca52172f4
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/scripts/extract_first_frames.swift

```text
import AppKit
import AVFoundation
import CoreMedia
import Foundation

enum FrameExtractError: Error, CustomStringConvertible {
  case invalidArguments
  case missingFrame(String)
  case encodeFailure(String)

  var description: String {
    switch self {
    case .invalidArguments:
      return "Usage: xcrun swift scripts/extract_first_frames.swift <input.mp4> <output.jpg> [<input.mp4> <output.jpg> ...]"
    case .missingFrame(let path):
      return "Could not extract a frame from \(path)"
    case .encodeFailure(let path):
      return "Could not encode a JPEG preview for \(path)"
    }
  }
}

func writeFirstFrame(from inputPath: String, to outputPath: String) throws {
  let inputURL = URL(fileURLWithPath: inputPath)
  let asset = AVURLAsset(url: inputURL)
  let generator = AVAssetImageGenerator(asset: asset)
  generator.appliesPreferredTrackTransform = true
  generator.maximumSize = CGSize(width: 1600, height: 1600)

  let semaphore = DispatchSemaphore(value: 0)
  var generatedImage: CGImage?
  var generationError: Error?

  generator.generateCGImageAsynchronously(for: .zero) { image, _, error in
    generatedImage = image
    generationError = error
    semaphore.signal()
  }

  semaphore.wait()

  if let generationError {
    throw generationError
  }

  guard let cgImage = generatedImage else {
    throw FrameExtractError.missingFrame(inputPath)
  }

  let bitmap = NSBitmapImageRep(cgImage: cgImage)

  guard let data = bitmap.representation(using: .jpeg, properties: [.compressionFactor: 0.9]) else {
    throw FrameExtractError.encodeFailure(inputPath)
  }

  let outputURL = URL(fileURLWithPath: outputPath)
  try FileManager.default.createDirectory(
    at: outputURL.deletingLastPathComponent(),
    withIntermediateDirectories: true
  )
  try data.write(to: outputURL)
}

let arguments = Array(CommandLine.arguments.dropFirst())

guard !arguments.isEmpty, arguments.count.isMultiple(of: 2) else {
  throw FrameExtractError.invalidArguments
}

for pairIndex in stride(from: 0, to: arguments.count, by: 2) {
  let inputPath = arguments[pairIndex]
  let outputPath = arguments[pairIndex + 1]
  try writeFirstFrame(from: inputPath, to: outputPath)
  FileHandle.standardOutput.write(Data("\(outputPath)\n".utf8))
}
```

## File: assets/apps/beijing-map-ui.jpg
size: 80869
sha: f9d064abd273f95633825db870abc6ccdb20613c
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/apps/beijing-map-ui.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/apps/beijing-map-ui.jpg

## File: assets/apps/cinematic-ai-landing.jpg
size: 127688
sha: bd322f6f5d5a0c71d89f21f72ed7ac2ecc0dc3b6
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/apps/cinematic-ai-landing.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/apps/cinematic-ai-landing.jpg

## File: assets/apps/watch-experience.jpg
size: 149245
sha: 7bd1cb1231f00922897faa8d1a984f2b96f92b36
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/apps/watch-experience.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/apps/watch-experience.jpg

## File: assets/images/agnes-frontier-models-banner.jpg
size: 263176
sha: 79af0e82fc43ca2cfccb489d4dd17b905f98c141
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/agnes-frontier-models-banner.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/agnes-frontier-models-banner.jpg

## File: assets/images/brand-envelope-perfume.png
size: 3662047
sha: c3c20e0039b6988a8d33aaece05fb2ceb1a6f3db
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/brand-envelope-perfume.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/brand-envelope-perfume.png

## File: assets/images/cyberpunk-bridge.jpg
size: 471996
sha: f6c0d03e3e5b793d8e090cdfb1bc440662725ab1
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/cyberpunk-bridge.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/cyberpunk-bridge.jpg

## File: assets/images/latte-infographic.jpg
size: 331293
sha: 69c94f0a41e7bc7e3c70fa7bc5fd89c5fab10282
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/latte-infographic.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/latte-infographic.jpg

## File: assets/images/pencil-editorial-fashion.png
size: 2370418
sha: 193069a60916b949ad1c2164e1b097d4b202d681
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/pencil-editorial-fashion.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/pencil-editorial-fashion.png

## File: assets/images/perfume-product.jpg
size: 359264
sha: 172859cfabd8c3e23e8d346b15f143c97f7a5ab0
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/perfume-product.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/perfume-product.jpg

## File: assets/images/y2k-golden-hour.png
size: 2764913
sha: aa4056b9de1ed01da558c509a16de9e220f2a0d7
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/y2k-golden-hour.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/images/y2k-golden-hour.png

## File: assets/video-previews/ad-film-10s.jpg
size: 104499
sha: 4062bd0e3ec87cbdf20d0b823f61bc19ecf21e38
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/ad-film-10s.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/ad-film-10s.jpg

## File: assets/video-previews/animation-film-10s.jpg
size: 142870
sha: 9a3a2e8151dd1b676d6bbf7f09fc7ea282dceee1
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/animation-film-10s.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/animation-film-10s.jpg

## File: assets/video-previews/bridge-pushin-clean.png
size: 689629
sha: a01df4f7ee9cec25e8b91fc0326f6a3af3ec680d
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/bridge-pushin-clean.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/bridge-pushin-clean.png

## File: assets/video-previews/cinema-film-10s.jpg
size: 95157
sha: 2368cccba861b46b15e1d6d8acf498566130d664
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/cinema-film-10s.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/cinema-film-10s.jpg

## File: assets/video-previews/forest-waterfall.jpg
size: 32015
sha: 33000ebfd27cb6f7ae6b5e28f33ac26e0d3872ad
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/forest-waterfall.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/forest-waterfall.jpg

## File: assets/video-previews/luxury-perfume-10s.jpg
size: 112429
sha: 30015a6506449190840664747d8005ecc3317e28
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/luxury-perfume-10s.jpg

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/luxury-perfume-10s.jpg

## File: assets/video-previews/perfume-motion.png
size: 578391
sha: 16bdd205516ba25ec628989a38377f6c473ec198
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/perfume-motion.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/perfume-motion.png

## File: assets/video-previews/rural-cooking.png
size: 239579
sha: 57cc4e64c36a1dea1cd347de016e1d04c9b9c4b6
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/rural-cooking.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/video-previews/rural-cooking.png

## File: assets/videos/ad-film-10s.mp4
size: 2298110
sha: 63ffa5b752f8daec6c11049fc2cd33cc8be52107
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/ad-film-10s.mp4

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/ad-film-10s.mp4

## File: assets/videos/animation-film-10s.mp4
size: 3076448
sha: 028f9c9c72e12578313c1939dc087963ddb84644
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/animation-film-10s.mp4

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/animation-film-10s.mp4

## File: assets/videos/bridge-pushin.mp4
size: 320741
sha: aae65216e5859eaab8cc11078e928c189e71e031
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/bridge-pushin.mp4

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/bridge-pushin.mp4

## File: assets/videos/cinema-film-10s.mp4
size: 1800758
sha: 4c98f0246a5818b716b5d50ada07da323324c6d2
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/cinema-film-10s.mp4

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/cinema-film-10s.mp4

## File: assets/videos/forest-waterfall.mp4
size: 657952
sha: 2ca478887ed74dc7f46ff38dd4c2cfdd2c33209c
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/forest-waterfall.mp4

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/forest-waterfall.mp4

## File: assets/videos/luxury-perfume-10s.mp4
size: 2753750
sha: 2ddf1bf3c56ac1d7eabb0a0ebc36fd80f289684b
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/luxury-perfume-10s.mp4

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/luxury-perfume-10s.mp4

## File: assets/videos/perfume-motion.mp4
size: 1560316
sha: b418bff1b3e989c641d29a64e531c5a74c43fbab
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/perfume-motion.mp4

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/perfume-motion.mp4

## File: assets/videos/rural-cooking.mp4
size: 282452
sha: ab63dad67693ae9b690c74091ce90e2f504a9ca2
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/rural-cooking.mp4

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/assets/videos/rural-cooking.mp4

## File: .gitattributes
size: 189
sha: b05f4d0a2a5c499f561c4790446d04e313805b71
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/.gitattributes

```text
scripts/extract_first_frames.swift linguist-documentation
scripts/*.sh linguist-documentation
examples/apps/*.html linguist-documentation
docs/superpowers/specs/*.md linguist-documentation
```

## File: .gitignore
size: 36
sha: 05c9b460380922133de0cb6e4cbd40d087426d3d
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/.gitignore

```text
.DS_Store
.agents/
skills-lock.json
```

## File: agents/openai.yaml
size: 307
sha: f0de657de813449e2265ed091a38a20e2f7d91de
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/agents/openai.yaml

```text
interface:
  display_name: "Agnes AI Skill"
  short_description: "Set up Agnes auth once, then use Agnes text, image, and video APIs from one installable skill"
  default_prompt: "Use $agnes-ai-skill to set up Agnes access, persist my API key if needed, and call the right Agnes text, image, or video API."
```

## File: docs/superpowers/specs/2026-06-02-agnes-cli-design-zh.md
size: 20885
sha: 6976112ec0350de78897b9cdb063e81d91fd3752
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/docs/superpowers/specs/2026-06-02-agnes-cli-design-zh.md

````text
# Agnes CLI 与 npm 包双轨方案设计稿

日期：2026-06-02  
仓库：`jomeswang/agnes-ai-skill`  
状态：待评审

## 目标

为 Agnes 增加一个真正可执行的工具层，让 agent 在常见场景下不再优先手写原始
`curl`，同时继续保留当前 skill 仓库的轻量安装体验。

这套设计要同时满足：

- `agnes-ai-skill` 继续保持轻量，适合 `npx skills add ... -g`
- Agnes 的执行层单独沉淀为 npm 包和 CLI
- 图生图、图生视频等需要远程 URL 的场景，可以自动把本地文件转成临时公网 URL
- 后续 Node 自动流可以直接复用 JS API，而不只是调用命令行

## 核心结论

推荐采用**双轨方案**，而不是 Monorepo 根目录 skill + CLI 源码混放。

### 轨道 1：`agnes-ai-skill`

定位：

- 安装型 skill 仓库
- 面向 Codex / Claude Code / 其他 `SKILL.md` 兼容 agent
- 尽量轻，不把完整 CLI 源码打包进 skill 安装目录

职责：

- `SKILL.md`
- `README.md`
- 最少量必要脚本或 fallback helper
- Agnes 能力说明、模型选择、auth 指导、命令调用策略

### 轨道 2：`agnes-ai-cli`

定位：

- 执行型 npm 包
- 面向 agent、命令行用户、Node 自动流

职责：

- 提供 `agnes` CLI
- 提供 JS API
- 负责真实的 Agnes 请求执行
- 负责本地文件转临时公网 URL
- 负责视频轮询、参数归一化、稳定输出

## 为什么不推荐根目录 Monorepo 直接混放

当前 skill 安装器的典型行为是：**复制选中的 skill 目录**。

如果继续保持：

- 仓库根目录就是 skill
- CLI 源码也放在根目录下的 `packages/`

那么用户安装 skill 时，很可能会把 CLI 源码也一起复制进去。

这会带来几个问题：

- 安装体积变大
- skill 安装目录变重
- 图片、视频、示例、CLI 源码容易一起被带下去
- skill 仓库不再像“安装型 skill”，而更像“全量项目镜像”

所以更合理的边界是：

- `agnes-ai-skill` 只负责教 agent 怎么做
- `agnes-ai-cli` 负责真正去做

## 双轨结构

### 仓库 A：`agnes-ai-skill`

建议保留当前仓库名，继续作为 skill 分发入口。

建议结构：

```text
agnes-ai-skill/
  LICENSE
  README.md
  SKILL.md
  agents/
    openai.yaml
  scripts/
    agnes-media-url.sh
    extract_first_frames.swift
```

说明：

- `scripts/agnes-media-url.sh` 可以先保留，作为 fallback 或调试工具
- 不再把完整 npm CLI 源码塞进这个仓库

### 仓库 / 包 B：`agnes-ai-cli`

建议单独作为 npm 包维护。

建议结构：

```text
agnes-ai-cli/
  LICENSE
  README.md
  package.json
  bin/
    agnes.js
  src/
    cli.ts
    index.ts
    config.ts
    errors.ts
    output.ts
    auth/
      check.ts
      saveKey.ts
    media/
      toPublicUrl.ts
      litterbox.ts
    image/
      generateImage.ts
      normalizeImageRequest.ts
    video/
      generateVideo.ts
      pollVideo.ts
      normalizeVideoRequest.ts
  test/
    cli/
    unit/
```

## 两个轨道怎么衔接

`agnes-ai-skill` 不再鼓励 agent 直接拼原始 `curl`，而是优先按这个顺序执行：

1. 先尝试调用本机已安装的 `agnes` CLI
2. 如果没装 CLI，则尝试 `npx -y agnes-ai-cli@<兼容版本范围> ...`
3. 只有在 CLI 不可用或需要最小验证时，才退回原始 `curl`

这样有几个好处：

- skill 继续轻量
- 执行逻辑集中在 CLI
- agent 的调用方式更稳定
- 用户不用每次关心 Agnes 的底层 payload 细节

## Skill / CLI 兼容契约

双轨方案要成立，必须显式定义 skill 和 CLI 的兼容关系，不能默认跟随
“latest”。

规则建议：

- skill 文档声明一个最小兼容 CLI 主版本或次版本范围
- 本机已安装的 `agnes` 只有在 `agnes --version` 满足兼容范围时才可直接使用
- `SKILL.md` 优先调用：
  1. 先校验版本后再使用本机 `agnes`
  2. `npx -y agnes-ai-cli@<兼容范围> ...`
  3. 最后再退回原始 `curl`
- 如果 CLI 引入了 breaking change，skill 必须在同一个发布窗口同步更新
- skill 不能假设“最新 npm 包永远兼容”

## CLI 设计

### 设计原则

- 不要把 `generate` 做成过重的层级，例如 `agnes video generate`
- 命令要尽量贴近任务场景，让 agent 好选、人也好记
- 内部实现统一，外部命令清晰

### 技术选型

推荐使用成熟开源库，不建议手写参数解析器。

建议组合：

- `commander`
  - 作为 CLI 主框架
  - 负责子命令、参数解析、`--help`、`--version`
- `zod`
  - 作为参数校验和内部 options 归一化层
  - 让 CLI 参数校验和 JS API 参数校验复用同一套规则
- Node 原生 `fetch` / `FormData`
  - 作为 Agnes API 与 Litterbox 上传的 HTTP 层
  - 尽量避免为简单请求额外引入过多网络依赖
- 可选 `picocolors`
  - 用于命令行输出的轻量着色
  - 不是必须依赖

不建议作为第一选择：

- `yargs`
  - 功能很强，但对这个项目来说偏重
- `cac`
  - 可以用，但在多层命令和帮助信息组织上不如 `commander` 稳妥

当前推荐结论：

- CLI 框架：`commander`
- 参数校验：`zod`
- HTTP / 上传：Node 原生 `fetch` + `FormData`
- 输出美化：可选 `picocolors`

### 推荐命令树

```text
agnes auth check
agnes auth save-key [--key <value>]

agnes media url <file-or-url> [--ttl 1h|12h|24h|72h]

agnes text chat --prompt <text> [--model agnes-2.0-flash] [--json]

agnes image text2img --prompt <text> [options]
agnes image img2img --image <path-or-url> --prompt <text> [options]
agnes image compose --image <path-or-url> --image <path-or-url> --prompt <text> [options]

agnes video text2video --prompt <text> [options]
agnes video img2video --image <path-or-url> --prompt <text> [options]
agnes video multivideo --image <path-or-url> --image <path-or-url> --prompt <text> [options]
agnes video keyframes --image <path-or-url> --image <path-or-url> --prompt <text> [options]
agnes video poll <task-id> [--interval 3] [--timeout 600]
```

### 为什么这样设计

- `text chat` 保留一个最小文本入口，让 agent 可以通过 CLI 跑通 Agnes
  文本、图片、视频三类流程
- `text2img`、`img2img`、`text2video`、`img2video` 足够直观
- `keyframes` 单独暴露更清晰，因为它本来就是 Agnes 的特殊模式
- `poll` 是视频异步任务的一等操作，不应该被埋掉
- 比 `video generate` 更利落，也更容易让 agent 命中

### `--help` 设计要求

CLI 必须内建完整帮助系统，而不是只在 README 里说明。

至少要支持：

```bash
agnes --help
agnes auth --help
agnes media --help
agnes text --help
agnes text chat --help
agnes image --help
agnes image img2img --help
agnes video --help
agnes video keyframes --help
```

每一层帮助都应包含：

- 这个命令的用途
- 必填参数
- 可选参数
- 至少 1 个最小示例
- 与 Agnes request shape 对应的场景说明

例如 `agnes video keyframes --help` 应明确说明：

- 这是 Agnes `keyframes` 模式
- 需要 2 张或以上图片
- `--image` 可重复传入
- 常用参数：
  - `--width`
  - `--height`
  - `--num-frames`
  - `--frame-rate`
  - `--seed`
  - `--json`

帮助信息应同时面向：

- 人类开发者
- 直接读取命令输出的 agent

### 是否保留别名

可以保留，但不作为主入口：

- `agnes image generate` -> `agnes image text2img`
- `agnes video generate` -> `agnes video text2video`

skill 文档和 agent 提示里应该优先使用明确命令，不优先使用别名。

## JS API 设计

CLI 面向人和 agent，JS API 面向 Node 自动流。

### 公共入口建议

```ts
const agnes = createAgnesClient(config)

agnes.auth.check()

agnes.media.toPublicUrl(input, options?)

agnes.text.complete(options)

agnes.image.generate(options)

agnes.video.generate(options)
agnes.video.poll(taskId, options?)
```

推荐使用 `Client + 命名空间` 结构，而不是在顶层直接裸暴露
`generateImage()` / `generateVideo()`。

这样可以同时保留：

- 清晰的能力分组
- 统一的配置入口
- 更小的顶层 API 面
- 对未来 provider、logger、默认参数、重试策略的扩展空间

shell 启动文件写入应保持为 CLI-only 行为，不建议作为公开 JS API 暴露。

文本能力建议保留一个轻量公开入口：

- `agnes.text.complete()`

这样可以让 Node 自动流直接跑最小 Agnes 文本请求，而不会逼调用方退回
原始 `fetch`。

### 为什么 JS API 要统一成 `image.generate()` / `video.generate()`

如果把图片和视频拆成很多公开方法，例如：

- `textToImage()`
- `imageToImage()`
- `composeImage()`
- `textToVideo()`
- `imageToVideo()`
- `multiImageVideo()`
- `keyframesVideo()`

短期看起来直观，但长期会有两个问题：

1. API 面会越来越碎
2. 新模式或 provider 差异出现时，方法名会持续膨胀

而 Agnes 的能力本质上本来就是“同一能力域下的多种 mode”。

图片：

- 文生图
- 图生图
- 多图合成

视频：

- 文生视频
- 单图生视频
- 多图生视频
- keyframes 生视频

所以：

- 对外 CLI：按场景命令拆开，方便人和 agent 使用
- 对内 JS API：统一为 `generate()`，通过 `mode` 区分

这是更兼容、更容易演进的设计。

### 推荐的 Client 形态

```ts
const agnes = createAgnesClient({
  apiKey: process.env.AGNES_API_KEY,
})

await agnes.image.generate({
  mode: "text2img",
  prompt: "A luminous floating city above a misty canyon at sunrise",
})

await agnes.image.generate({
  mode: "img2img",
  image: "/path/to/input.png",
  prompt: "Preserve the silhouette and convert the scene into a bright editorial campaign",
})

await agnes.video.generate({
  mode: "img2video",
  image: "/path/to/frame.png",
  prompt: "Keep the hero subject stable while adding subtle wind and a soft push-in",
})

await agnes.video.generate({
  mode: "keyframes",
  images: ["frame-a.png", "frame-b.png"],
  prompt: "Create a smooth premium transition between the two frames",
})

await agnes.video.poll("video_123")
```

## 参数归一化规则

### `image.generate(options)`

建议使用判别联合类型，而不是一个无限膨胀的大对象。

```ts
type ImageGenerateOptions =
  | {
      mode: "text2img"
      model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
      prompt: string
      size?: string
      responseFormat?: "url"
      seed?: number
    }
  | {
      mode: "img2img"
      model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
      image: string
      prompt: string
      size?: string
      responseFormat?: "url"
      seed?: number
      ttl?: "1h" | "12h" | "24h" | "72h"
    }
  | {
      mode: "compose"
      model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
      images: string[]
      prompt: string
      size?: string
      responseFormat?: "url"
      seed?: number
      ttl?: "1h" | "12h" | "24h" | "72h"
    }
```

归一化规则：

- `mode: "text2img"` -> 文生图
- `mode: "img2img"` -> 单图图生图
- `mode: "compose"` -> 多图合成
- 模型是 2.1 且有图像输入 -> `extra_body.image`
- 模型是 2.0 且有图像输入 -> `tags: ["img2img"]` + `extra_body.image`

### `video.generate(options)`

视频侧也建议使用判别联合类型。

```ts
type VideoGenerateOptions =
  | {
      mode: "text2video"
      prompt: string
      width?: number
      height?: number
      numFrames?: number
      frameRate?: number
      seed?: number
      negativePrompt?: string
    }
  | {
      mode: "img2video"
      image: string
      prompt: string
      width?: number
      height?: number
      numFrames?: number
      frameRate?: number
      seed?: number
      negativePrompt?: string
      ttl?: "1h" | "12h" | "24h" | "72h"
    }
  | {
      mode: "multivideo"
      images: string[]
      prompt: string
      width?: number
      height?: number
      numFrames?: number
      frameRate?: number
      seed?: number
      negativePrompt?: string
      ttl?: "1h" | "12h" | "24h" | "72h"
    }
  | {
      mode: "keyframes"
      images: string[]
      prompt: string
      width?: number
      height?: number
      numFrames?: number
      frameRate?: number
      seed?: number
      negativePrompt?: string
      ttl?: "1h" | "12h" | "24h" | "72h"
    }
```

归一化规则：

- `mode: "text2video"` -> 文生视频
- `mode: "img2video"` -> Agnes 顶层 `image`
- `mode: "multivideo"` -> `extra_body.image`
- `mode: "keyframes"` -> `extra_body.image + extra_body.mode = "keyframes"`

### 视频参数校验与默认值

这部分应直接内建在 CLI 和 JS API 中，而不是留到实现时临场决定。

建议默认值：

- `width: 1152`
- `height: 768`
- `numFrames: 121`
- `frameRate: 24`

必须校验：

- `numFrames <= 441`
- `numFrames` 必须满足 `8n + 1`
- `frameRate` 必须在 `1-60`
- `mode: "img2video"` 必须恰好 1 张图
- `mode: "multivideo"` 至少 2 张图
- `mode: "keyframes"` 至少 2 张图

只要参数非法，就应在发送 Agnes 请求前直接失败。

### 为什么 CLI 和 JS API 要故意不完全一样

这里刻意做分层设计：

- CLI：显式命令
- JS API：统一 `generate()`

原因是：

- CLI 更适合被人和 agent 通过命令名字发现能力
- JS API 更适合通过 `mode` 保持兼容性和扩展性
- 两层各自优化自己的使用体验，而不是强行完全一致

## 本地文件转公网 URL

这是这次设计里最关键的一段。

Agnes 官方文档当前写的是：

- 图生图：传图片 URL
- 图生视频：传图片 URL
- 多图 / keyframes：也是图片 URL 数组

所以 CLI 应自动做这件事：

- 如果 `--image` 已经是 `http://` 或 `https://`，直接使用
- 如果 `--image` 是本地路径，先上传到临时文件托管服务
- 拿到公网 URL 后，再调用 Agnes

### 第一版上传 provider

第一版建议使用 **Litterbox**：

- 免费
- 接口简单
- 已经验证过可用
- 足够做临时桥接层

### Provider 抽象

后面不要把 CLI 写死在 Litterbox 上，建议一开始就留出抽象：

```ts
interface MediaUrlProvider {
  upload(localPath: string, options?: { ttl?: string }): Promise<string>
}
```

第一版实现：

- `LitterboxMediaUrlProvider`

未来可扩展：

- Cloudinary
- Google Cloud Storage
- 用户自定义 provider

### URL bridge 的行为约束

这部分需要明确，不然后续实现容易不一致：

- 多次传入 `--image` 时，必须严格保留输入顺序
- 同一个命令调用里，重复本地路径可以只上传一次，再在归一化请求里复用
- 如果其中任意一个上传失败，整个 Agnes 请求不应继续发送
- 默认 TTL 设为 `1h`
- 对长视频或可能排队较久的视频任务，CLI 应允许显式传更长 TTL，
  并在帮助信息中说明 `12h` / `24h` 更稳妥

## 输出协议

CLI 应同时支持：

- 默认输出：给人看
- `--json`：给 agent / 自动流看

### 默认输出建议

- `agnes media url`：只打印 URL
- 图片命令：只打印生成结果 URL
- 视频创建命令：打印 `task_id`、`video_id` + 状态
- `agnes video poll`：打印最终视频 URL + 状态摘要

### `--json` 建议

统一输出机器可读结构，例如：

```json
{
  "ok": true,
  "url": "https://litter.catbox.moe/abc123.jpg",
  "source": "litterbox"
}
```

```json
{
  "ok": true,
  "taskId": "task_123",
  "videoId": "video_123",
  "status": "queued"
}
```

### 视频任务标准化返回

CLI 和 JS API 必须对 Agnes 视频异步结果做统一标准化，不应直接把原始
`id` / `task_id` / `video_id` / 状态字段裸暴露给上层。

建议的标准化创建结果：

```json
{
  "ok": true,
  "taskId": "task_123",
  "videoId": "video_123",
  "status": "queued",
  "rawStatus": "queued",
  "model": "agnes-video-v2.0"
}
```

建议的标准化轮询结果：

```json
{
  "ok": true,
  "taskId": "task_123",
  "videoId": "video_123",
  "status": "completed",
  "videoUrl": "https://...",
  "seconds": 10.0,
  "size": "1152x768"
}
```

建议保证的状态枚举：

- `queued`
- `in_progress`
- `completed`
- `failed`
- `timed_out`

规则建议：

- 原始 `id` 或 `task_id` 一律映射成 `taskId`
- 保留 `video_id` 为 `videoId`；推荐轮询接口返回 `id: "video_..."`
  时，也保留为 `videoId`
- 如有需要，保留 `rawStatus`
- `video.generate()` 返回标准化任务对象，不自动轮询
- `video.poll()` 返回标准化终态对象
- `video poll --json` 需要对以下情况有明确结构：
  - `failed`
  - `404`
  - `503`
  - timeout

建议失败结构：

```json
{
  "ok": false,
  "taskId": "task_123",
  "status": "failed",
  "code": "TASK_FAILED",
  "message": "Agnes video task failed"
}
```

## 认证设计

CLI 需要沿用当前 skill 已经建立好的 Agnes key 规则。JS API 只负责检查
和运行时配置，不负责改写 shell 启动文件。

### `agnes auth check`

职责：

- 检查 `AGNES_API_KEY` 是否存在
- 输出当前是否可直接调用 Agnes

### `agnes auth save-key`

职责：

- 将 `AGNES_API_KEY` 写入：
  - zsh -> `~/.zshrc`
  - bash -> `~/.bashrc`
  - fallback -> `~/.profile`
- 更新已有 export 或追加新 export
- 不回显完整 key

### JS auth surface

公开 JS API 建议只保留：

- `agnes.auth.check()`

可选内部能力：

- `resolveAuthConfig()`

不建议把 shell rc 文件写入暴露成普通 JS API。

## 错误处理

CLI 不能只把底层原始异常裸抛给 agent，建议统一成稳定错误类别：

- auth missing
- local file missing
- upload failed
- Agnes request failed
- Agnes task timeout
- invalid arguments

`--json` 下错误也应该保持结构化：

```json
{
  "ok": false,
  "code": "UPLOAD_FAILED",
  "message": "Failed to upload local file to Litterbox"
}
```

视频相关错误码至少应覆盖：

- `TASK_FAILED`
- `TASK_NOT_FOUND`
- `SERVICE_BUSY`
- `POLL_TIMEOUT`
- `INVALID_VIDEO_SETTINGS`

## 测试建议

### 单元测试

- 参数归一化
- 本地路径与远程 URL 透传逻辑
- shell rc 文件选择逻辑
- JSON 输出格式
- `task_id` / `video_id` / `id` 标准化
- 视频状态映射
- `numFrames <= 441` 校验
- `numFrames = 8n + 1` 校验
- `frameRate` 在 `1-60` 的校验
- 默认 TTL 与显式 TTL 覆盖逻辑

### CLI 测试

- `agnes media url https://example.com/x.png`
- `agnes text chat --help`
- `agnes image text2img --help`
- `agnes video keyframes --help`
- `agnes auth check`
- `agnes video poll video_123 --json`

### 集成测试

默认 mock：

- Litterbox 上传
- Agnes API

live test 显式开启：

- 要求 `AGNES_API_KEY`
- 要求显式 opt-in

## 与 skill 的集成方式

`agnes-ai-skill` 后续应更新为：

- 优先使用 CLI
- 只有在 CLI 不可用时才退回 `curl`

推荐执行优先级：

1. 本机 `agnes --version` 满足兼容范围时，使用 `agnes ...`
2. `npx -y agnes-ai-cli@<兼容范围> ...`
3. 原始 `curl`

这能让：

- skill 仓库保持轻
- CLI 真正承担执行责任
- agent 的调用更稳定

## 发布方式

### `agnes-ai-skill`

继续作为 GitHub skill 仓库分发：

- `npx skills add jomeswang/agnes-ai-skill -g`

### `agnes-ai-cli`

单独发布到 npm：

- 包名优先：`agnes-ai-cli`
- 如果名字已占用，再退到：`@jomeswang/agnes-ai-cli`

CLI 执行文件名：

- `agnes`

## 实施顺序

### Phase 1

- 初始化 `agnes-ai-cli`
- 实现：
  - `auth check`
  - `auth save-key`
  - `media url`
  - `text chat`

### Phase 2

- 实现图片命令：
  - `text2img`
  - `img2img`
  - `compose`

### Phase 3

- 实现视频命令：
  - `text2video`
  - `img2video`
  - `multivideo`
  - `keyframes`
  - `poll`

### Phase 4

- 更新 `agnes-ai-skill`
- 将 CLI 作为首选执行路径
- 保留 shell helper 作为 fallback

## 成功标准

这套双轨方案算成功，当且仅当：

1. skill 安装不再把完整 CLI 源码一起打包下去
2. agent 能通过 CLI 稳定完成 Agnes 文本、图片、视频流程
3. 本地图片路径在 Agnes 图生图 / 图生视频场景下能自动桥接为公网 URL
4. npm 包可以独立发布和升级
5. 视频任务标准化返回和参数校验足够稳定，agent 不需要猜 Agnes
   的原始响应差异

## 当前推荐

如果现在要拍板，推荐是：

- `agnes-ai-skill` 继续保持当前轻量 root skill 形态
- `agnes-ai-cli` 单独做 npm 包
- CLI 用场景式 commands
- JS API 用 `createAgnesClient()` + 统一的 `image.generate()` /
  `video.generate()`
- 本地文件第一版通过 Litterbox 做 URL bridge
- shell helper 保留为 fallback，不作为长期主执行层

## 需要确认的两个点

1. npm 包名优先用：
   - `agnes-ai-cli`
   - 还是 `@jomeswang/agnes-ai-cli`

2. shell helper 的长期定位：
   - 仅 fallback
   - 还是继续作为公开脚本一起维护
````

## File: docs/superpowers/specs/2026-06-02-agnes-cli-design.md
size: 19690
sha: 44d7a995f939c17a4a13ee151fe7d4ae6aae394f
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/docs/superpowers/specs/2026-06-02-agnes-cli-design.md

````text
# Agnes CLI And npm Package Design

Date: 2026-06-02
Repository: `jomeswang/agnes-ai-skill`
Status: Draft for review

## Objective

Add a real execution layer for Agnes workflows so agents do not need to handcraft
raw `curl` calls for common tasks. The new layer should:

- preserve the current root-level `SKILL.md` install experience
- provide a publishable npm package and CLI
- normalize Agnes text, image, and video request shapes
- bridge local file paths into temporary public URLs when Agnes expects remote
  image URLs
- keep the repository lightweight enough to remain an install-friendly skill repo

## Current Context

The repository already contains:

- a root `SKILL.md` focused on Agnes platform setup and API usage
- a public GitHub distribution path for `npx skills add jomeswang/agnes-ai-skill -g`
- a lightweight shell helper:
  `scripts/agnes-media-url.sh`

The current pain points are:

- agents still need to assemble raw Agnes `curl` payloads
- local-path handling for image-to-image and image-to-video is easy to forget
- video polling and response normalization are repetitive
- the execution layer is not yet reusable outside the skill itself

## Recommendation

Choose a **dual-track architecture** instead of a root-level monorepo that
mixes installable skill content and CLI source in the same copied directory.

### Track 1: `agnes-ai-skill`

Role:

- install-friendly root skill repository
- optimized for `npx skills add ... -g`
- intentionally lightweight

Responsibilities:

- `SKILL.md`
- `README.md`
- minimal fallback helpers or tiny utility scripts
- Agnes capability guidance, model selection, auth flow, and command strategy

### Track 2: `agnes-ai-cli`

Role:

- executable npm package
- reusable JS API for Node automation
- canonical execution layer for Agnes requests

Responsibilities:

- provide the `agnes` CLI
- provide the JS client API
- normalize Agnes request shapes
- bridge local file paths into temporary public URLs
- own polling, output shaping, and validation

## Why Not A Root-Level Monorepo

Typical skill installers copy the selected skill directory.

If the root of `agnes-ai-skill` stays the installable skill and the CLI source
also lives under that root, installing the skill is likely to copy:

- CLI source
- package metadata
- extra assets or examples tied to the package

That would make the skill distribution heavier and blur the repository's role.

The better boundary is:

- `agnes-ai-skill` teaches agents what to do
- `agnes-ai-cli` performs the work

## Proposed Repository / Package Topology

### Repository A: `agnes-ai-skill`

Keep the current repository name and continue using it as the public skill
distribution entry point.

```text
agnes-ai-skill/
  LICENSE
  README.md
  SKILL.md
  agents/
    openai.yaml
  scripts/
    agnes-media-url.sh
    extract_first_frames.swift
```

Notes:

- `scripts/agnes-media-url.sh` may remain as a fallback or debugging helper
- do not place full npm CLI source in this repository root

### Repository / Package B: `agnes-ai-cli`

Maintain the CLI as a separate npm package.

```text
agnes-ai-cli/
  LICENSE
  README.md
  package.json
  bin/
    agnes.js
  src/
    cli.ts
    index.ts
    config.ts
    errors.ts
    output.ts
    auth/
      check.ts
      saveKey.ts
    media/
      toPublicUrl.ts
      litterbox.ts
    image/
      generateImage.ts
      normalizeImageRequest.ts
    video/
      generateVideo.ts
      pollVideo.ts
      normalizeVideoRequest.ts
  test/
    cli/
    unit/
```

## Package Scope

The npm package should be both:

- a CLI executable named `agnes`
- a JS API for Node-based automation

The package name should be one of:

1. `agnes-ai-cli` (recommended)
2. `@jomeswang/agnes-ai-cli`

Recommendation:

- Publish as `agnes-ai-cli` if available.
- Fall back to `@jomeswang/agnes-ai-cli` only if the unscoped name is taken.

## Skill / CLI Compatibility Contract

The dual-track setup needs an explicit compatibility rule so the skill can call
the CLI without silent drift.

Rules:

- the skill documents the minimum supported CLI major or minor version
- a locally installed `agnes` binary may be used only if `agnes --version`
  satisfies the declared compatible range
- the preferred execution path is:
  1. `agnes ...` only after version verification
  2. `npx -y agnes-ai-cli@<supported-range> ...`
  3. raw `curl` only as a fallback
- the skill should not assume "latest" without a declared compatible range
- when the CLI introduces breaking request-shape behavior, the skill must be
  updated in the same release window

## CLI Design

### Principles

- avoid raw `generate` as a repeated noun in the command tree
- use explicit task-shaped commands that agents can select reliably
- keep the user-facing commands short
- let aliases map into a smaller internal API surface

### Command Tree

```text
agnes auth check
agnes auth save-key [--key <value>]

agnes media url <file-or-url> [--ttl 1h|12h|24h|72h]

agnes text chat --prompt <text> [--model agnes-2.0-flash] [--json]

agnes image text2img --prompt <text> [options]
agnes image img2img --image <path-or-url> --prompt <text> [options]
agnes image compose --image <path-or-url> --image <path-or-url> --prompt <text> [options]

agnes video text2video --prompt <text> [options]
agnes video img2video --image <path-or-url> --prompt <text> [options]
agnes video multivideo --image <path-or-url> --image <path-or-url> --prompt <text> [options]
agnes video keyframes --image <path-or-url> --image <path-or-url> --prompt <text> [options]
agnes video poll <task-id> [--interval 3] [--timeout 600]
```

### Why This Tree

- `text chat` preserves a minimal Agnes text entry point so agents can complete
  Agnes text, image, and video flows through the CLI
- `text2img`, `img2img`, `text2video`, and `img2video` are concrete and easy
  for agents to choose
- `keyframes` stays explicit because it has a distinct Agnes request mode
- `multivideo` avoids hiding the difference between one-image and multi-image
  requests
- `poll` stays a first-class video operation because Agnes video is asynchronous

### Command Aliases

The CLI may additionally support these aliases:

- `agnes image generate` -> `agnes image text2img`
- `agnes video generate` -> `agnes video text2video`

However, the skill should prefer the explicit task commands, not the aliases.

## JS API Design

### Public Entry Point

```ts
const agnes = createAgnesClient(config)

agnes.auth.check()

agnes.media.toPublicUrl(input, options?)

agnes.text.complete(options)

agnes.image.generate(options)

agnes.video.generate(options)
agnes.video.poll(taskId, options?)
```

Use a `Client + namespaced services` shape instead of exposing top-level
`generateImage()` / `generateVideo()` functions directly.

This preserves:

- clearer capability grouping
- a single config entry point
- a smaller top-level API surface
- room for future providers, logging, retries, and defaults

Shell startup-file mutation should stay CLI-only. The JS API should not expose a
public method that edits `~/.zshrc`, `~/.bashrc`, or `~/.profile`.

Text should keep a lightweight public entry point:

- `agnes.text.complete()`

This lets Node workflows run the smallest Agnes text request without dropping
down to raw `fetch`.

### Why JS Should Use Unified `image.generate()` / `video.generate()`

If the public JS API exposes many task-specific methods such as:

- `textToImage()`
- `imageToImage()`
- `composeImage()`
- `textToVideo()`
- `imageToVideo()`
- `multiImageVideo()`
- `keyframesVideo()`

it starts out readable, but it fragments quickly as new modes and provider
differences appear.

Agnes capabilities are a better fit for a unified `generate()` surface with
mode-based branching.

Images:

- text-to-image
- image-to-image
- multi-image composition

Video:

- text-to-video
- image-to-video
- multi-image video
- keyframe video

So the design should intentionally split the layers:

- CLI: explicit task-shaped commands
- JS API: unified `generate()` methods keyed by `mode`

That gives the best compatibility story without bloating the public JS API.

### Recommended Client Shape

```ts
const agnes = createAgnesClient({
  apiKey: process.env.AGNES_API_KEY,
})

await agnes.image.generate({
  mode: "text2img",
  prompt: "A luminous floating city above a misty canyon at sunrise",
})

await agnes.image.generate({
  mode: "img2img",
  image: "/path/to/input.png",
  prompt: "Preserve the silhouette and convert the scene into a bright editorial campaign",
})

await agnes.video.generate({
  mode: "img2video",
  image: "/path/to/frame.png",
  prompt: "Keep the hero subject stable while adding subtle wind and a soft push-in",
})

await agnes.video.generate({
  mode: "keyframes",
  images: ["frame-a.png", "frame-b.png"],
  prompt: "Create a smooth premium transition between the two frames",
})

await agnes.video.poll("video_123")
```

### Type Shapes

```ts
type ImageGenerateOptions =
  | {
      mode: "text2img"
      model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
      prompt: string
      size?: string
      responseFormat?: "url"
      seed?: number
    }
  | {
      mode: "img2img"
      model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
      image: string
      prompt: string
      size?: string
      responseFormat?: "url"
      seed?: number
      ttl?: "1h" | "12h" | "24h" | "72h"
    }
  | {
      mode: "compose"
      model?: "agnes-image-2.1-flash" | "agnes-image-2.0-flash"
      images: string[]
      prompt: string
      size?: string
      responseFormat?: "url"
      seed?: number
      ttl?: "1h" | "12h" | "24h" | "72h"
    }

type VideoGenerateOptions =
  | {
      mode: "text2video"
      prompt: string
      width?: number
      height?: number
      numFrames?: number
      frameRate?: number
      seed?: number
      negativePrompt?: string
    }
  | {
      mode: "img2video"
      image: string
      prompt: string
      width?: number
      height?: number
      numFrames?: number
      frameRate?: number
      seed?: number
      negativePrompt?: string
      ttl?: "1h" | "12h" | "24h" | "72h"
    }
  | {
      mode: "multivideo"
      images: string[]
      prompt: string
      width?: number
      height?: number
      numFrames?: number
      frameRate?: number
      seed?: number
      negativePrompt?: string
      ttl?: "1h" | "12h" | "24h" | "72h"
    }
  | {
      mode: "keyframes"
      images: string[]
      prompt: string
      width?: number
      height?: number
      numFrames?: number
      frameRate?: number
      seed?: number
      negativePrompt?: string
      ttl?: "1h" | "12h" | "24h" | "72h"
    }
```

### Internal Mapping Rules

For images:

- `mode: "text2img"` -> text-to-image
- `mode: "img2img"` -> single-image image-to-image
- `mode: "compose"` -> multi-image composition
- Image 2.1 with image input -> `extra_body.image`
- Image 2.0 with image input -> `tags: ["img2img"]` plus
  `extra_body.image`

For video:

- `mode: "text2video"` -> text-to-video
- `mode: "img2video"` -> top-level `image`
- `mode: "multivideo"` -> `extra_body.image`
- `mode: "keyframes"` -> `extra_body.image` plus
  `extra_body.mode = "keyframes"`

### Video Validation And Defaults

The design should bake Agnes-specific validation into the CLI and JS layer
instead of leaving it to ad hoc request assembly.

Recommended defaults:

- `width: 1152`
- `height: 768`
- `numFrames: 121`
- `frameRate: 24`

Required validation:

- `numFrames <= 441`
- `numFrames` must satisfy `8n + 1`
- `frameRate` must be in `1-60`
- `mode: "img2video"` requires exactly one image
- `mode: "multivideo"` requires at least two images
- `mode: "keyframes"` requires at least two images

Invalid settings should fail before any Agnes request is sent.

### Why CLI And JS Should Intentionally Differ

This is a deliberate split:

- CLI: explicit task-shaped commands
- JS API: unified `generate()` surface

The CLI optimizes for discoverability and help text.
The JS API optimizes for compatibility and long-term extension.

## Local File Handling

Agnes docs describe image inputs as remote image URLs. The CLI should therefore
normalize local file paths automatically.

### Rule

Whenever a command accepts `--image`:

- if the value is already `http://` or `https://`, use it unchanged
- if the value is a local file path, upload it to Litterbox first
- then use the resulting temporary public URL in the Agnes request

### First Provider

Use Litterbox first because:

- it is free
- it already works with simple `curl`
- it is enough for temporary bridge behavior

This provider should live behind an abstraction so future providers can be
added without changing the public CLI.

### Provider Abstraction

```ts
interface MediaUrlProvider {
  upload(localPath: string, options?: { ttl?: string }): Promise<string>
}
```

First implementation:

- `LitterboxMediaUrlProvider`

Future candidates:

- Cloudinary
- Google Cloud Storage
- custom provider interface

### URL Bridge Behavior

The bridge behavior should be deterministic:

- repeated `--image` inputs preserve input order exactly
- duplicate local paths may be uploaded once per command invocation and reused
  in-place in the normalized request
- if any upload fails, the whole command fails before sending the Agnes request
- default TTL is `1h`
- commands that start long-running Agnes video jobs should allow explicit TTL
  override and document that longer jobs may require `12h` or `24h`

## Output Contract

The CLI should support:

- human-readable default output
- `--json` for machine/agent consumption

### Default Output

- `media url`: print only the resulting URL
- image commands: print the resulting image URL
- video create commands: print `task_id`, `video_id`, and status summary
- `video poll`: print the resulting video URL and completion fields

### JSON Output

Examples:

```json
{
  "ok": true,
  "taskId": "task_123",
  "videoId": "video_123",
  "status": "queued"
}
```

```json
{
  "ok": true,
  "url": "https://litter.catbox.moe/abc123.jpg",
  "source": "litterbox"
}
```

### Video Task Normalization

The CLI and JS API must normalize Agnes async video responses into a stable
shape, regardless of whether the raw API returns `id`, `task_id`, or `video_id`.

Recommended normalized task object:

```json
{
  "ok": true,
  "taskId": "task_123",
  "videoId": "video_123",
  "status": "queued",
  "rawStatus": "queued",
  "model": "agnes-video-v2.0"
}
```

Recommended normalized poll result:

```json
{
  "ok": true,
  "taskId": "task_123",
  "videoId": "video_123",
  "status": "completed",
  "videoUrl": "https://...",
  "seconds": 10.0,
  "size": "1152x768"
}
```

Guaranteed status enum:

- `queued`
- `in_progress`
- `completed`
- `failed`
- `timed_out`

Rules:

- map raw `id` or `task_id` into `taskId`
- preserve `video_id` as `videoId`; when the recommended poll endpoint returns
  `id: "video_..."`, preserve it as `videoId` too
- preserve the raw provider status as `rawStatus` when useful
- `video.generate()` returns a normalized task object and does not auto-poll
- `video.poll()` returns a normalized terminal result object
- `video poll --json` must define structured output for:
  - `failed`
  - `404`
  - `503`
  - timeout

Recommended failure shape:

```json
{
  "ok": false,
  "taskId": "task_123",
  "status": "failed",
  "code": "TASK_FAILED",
  "message": "Agnes video task failed"
}
```

## Auth Behavior

The CLI should use the same Agnes key behavior already documented in the skill.
The JS API should limit itself to inspection and runtime config, not shell file
mutation.

### `agnes auth check`

Returns whether `AGNES_API_KEY` is available and which source was used.

### `agnes auth save-key`

Rules:

- write `AGNES_API_KEY`
- detect shell rc file:
  - zsh -> `~/.zshrc`
  - bash -> `~/.bashrc`
  - fallback -> `~/.profile`
- update existing export if present
- export into the current process for child calls when possible
- never echo the full key back

### JS Auth Surface

Recommended public JS auth surface:

- `agnes.auth.check()`

Optional internal or advanced surface:

- `resolveAuthConfig()`

Do not expose shell-rc mutation as a routine public JS API.

## Error Handling

The CLI should convert raw failures into stable categories:

- auth missing
- local file missing
- upload failed
- Agnes request failed
- Agnes task timeout
- invalid command arguments

For `--json`, errors should still print machine-readable output:

```json
{
  "ok": false,
  "code": "UPLOAD_FAILED",
  "message": "Failed to upload local file to Litterbox"
}
```

Video-specific error codes should include at least:

- `TASK_FAILED`
- `TASK_NOT_FOUND`
- `SERVICE_BUSY`
- `POLL_TIMEOUT`
- `INVALID_VIDEO_SETTINGS`

## Skill Integration

The root `SKILL.md` should eventually prefer CLI commands over raw `curl`
whenever the CLI is available.

Preferred hierarchy:

1. use local `agnes` only if `agnes --version` satisfies the supported range
2. otherwise use `npx -y agnes-ai-cli@<supported-range> ...`
3. otherwise fall back to the shell helper or raw `curl`

The skill should keep the minimal `curl` examples for portability, but treat the
CLI as the preferred execution path.

## Release And Distribution

### npm

- package published from the dedicated `agnes-ai-cli` package repository
- executable name: `agnes`
- versioning should start at `0.1.0`

### Skill Repository

`agnes-ai-skill` remains the canonical source for:

- the skill install experience
- skill-facing README and showcase
- skill documentation and compatibility guidance

### CLI Repository

`agnes-ai-cli` remains the canonical source for:

- CLI source
- JS API source
- package README
- release and npm publish workflow

## Testing Strategy

### Unit Tests

- request normalization for image and video modes
- local-path vs URL passthrough behavior
- rc file selection logic
- JSON output formatting
- `task_id` / `video_id` / `id` normalization
- video status mapping
- validation of `numFrames <= 441`
- validation of `numFrames = 8n + 1`
- validation of `frameRate` in `1-60`
- default TTL behavior and explicit TTL override

### CLI Tests

- `agnes media url https://example.com/x.png`
- `agnes text chat --help`
- `agnes image text2img --help`
- `agnes video keyframes --help`
- `agnes auth check`
- `agnes video poll video_123 --json`

### Integration Tests

Mock by default:

- Litterbox upload
- Agnes API requests

Optional live tests behind environment flags:

- `AGNES_API_KEY`
- explicit opt-in for live upload and live Agnes requests

## Rollout Plan

### Phase 1

- scaffold the standalone `agnes-ai-cli` package repository
- implement `auth check`, `auth save-key`, `media url`, and `text chat`

### Phase 2

- implement image commands
- implement video create + poll commands

### Phase 3

- update `SKILL.md` to prefer CLI
- keep shell fallback
- document install and publish flow

## Success Criteria

This design is successful when:

1. an agent can complete Agnes text, image, and video workflows without
   hand-authoring raw `curl` payloads in normal cases
2. local file inputs for Agnes image/video flows are bridged automatically
3. the public skill repository remains installable as a root-level skill
4. the CLI can be published independently to npm
5. video task normalization and validation are stable enough that agents do not
   need to guess raw Agnes response differences

## Open Questions

These should be decided before implementation:

1. package name:
   - `agnes-ai-cli`
   - or `@jomeswang/agnes-ai-cli`
2. whether to keep the shell helper permanently as a fallback
3. whether live integration tests should run in CI or only manually
````

## File: examples/apps/beijing-map-ui.html
size: 15142
sha: 7d1f8384c7616c0f84b47fc236f1cb4f20d7863c
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/examples/apps/beijing-map-ui.html

```text
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
    <title>Lantern Sprint</title>
    <style>
        :root {
            --bg-color: #fdfbf7; /* Cream */
            --primary-red: #d32f2f; /* Lacquer Red */
            --primary-gold: #ffc107; /* Gold */
            --accent-gold: #ffeb3b; /* Bright Gold */
            --text-color: #3e2723;
            --cloud-color: #546e7a;
        }

        body {
            margin: 0;
            padding: 0;
            background-color: var(--bg-color);
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            overflow: hidden;
            touch-action: none;
            user-select: none;
            display: flex;
            flex-direction: column;
            align-items: center;
            justify-content: center;
            height: 100vh;
            color: var(--text-color);
        }

        #game-container {
            position: relative;
            width: 100%;
            max-width: 600px;
            height: 100%;
            max-height: 800px;
            box-shadow: 0 4px 20px rgba(0,0,0,0.1);
            background: linear-gradient(to bottom, #fffdf5, #f0efe9);
            border: 2px solid var(--text-color);
            overflow: hidden;
        }

        canvas {
            display: block;
            width: 100%;
            height: 100%;
        }

        .ui-layer {
            position: absolute;
            top: 0;
            left: 0;
            width: 100%;
            height: 100%;
            pointer-events: none;
            display: flex;
            flex-direction: column;
            justify-content: space-between;
        }

        .hud {
            display: flex;
            justify-content: space-between;
            padding: 20px;
            font-size: 24px;
            font-weight: bold;
            color: var(--primary-red);
            text-shadow: 1px 1px 0px var(--primary-gold);
        }

        .screen {
            position: absolute;
            top: 0;
            left: 0;
            width: 100%;
            height: 100%;
            background: rgba(253, 251, 247, 0.9);
            display: flex;
            flex-direction: column;
            align-items: center;
            justify-content: center;
            text-align: center;
            pointer-events: auto;
            transition: opacity 0.3s;
        }

        .hidden {
            opacity: 0;
            pointer-events: none;
        }

        h1 {
            font-size: 48px;
            color: var(--primary-red);
            margin: 0 0 10px 0;
            text-transform: uppercase;
            letter-spacing: 2px;
            border-bottom: 4px solid var(--primary-gold);
            padding-bottom: 10px;
        }

        p {
            font-size: 18px;
            margin-bottom: 30px;
            color: #5d4037;
        }

        button {
            background-color: var(--primary-red);
            color: white;
            border: none;
            padding: 15px 40px;
            font-size: 20px;
            font-weight: bold;
            border-radius: 2px;
            cursor: pointer;
            box-shadow: 0 4px 0 #b71c1c;
            transition: transform 0.1s, box-shadow 0.1s;
            text-transform: uppercase;
            letter-spacing: 1px;
        }

        button:active {
            transform: translateY(4px);
            box-shadow: 0 0 0 #b71c1c;
        }

        button:hover {
            background-color: #e53935;
        }

        .stat-value {
            color: var(--primary-gold);
            text-shadow: 1px 1px 0 #3e2723;
        }

        /* Decoration lines */
        .corner {
            position: absolute;
            width: 20px;
            height: 20px;
            border: 4px solid var(--primary-red);
            pointer-events: none;
        }
        .tl { top: 10px; left: 10px; border-right: none; border-bottom: none; }
        .tr { top: 10px; right: 10px; border-left: none; border-bottom: none; }
        .bl { bottom: 10px; left: 10px; border-right: none; border-top: none; }
        .br { bottom: 10px; right: 10px; border-left: none; border-top: none; }

    </style>
</head>
<body>

    <div id="game-container">
        <div class="corner tl"></div>
        <div class="corner tr"></div>
        <div class="corner bl"></div>
        <div class="corner br"></div>

        <canvas id="gameCanvas"></canvas>

        <div class="ui-layer">
            <div class="hud">
                <div id="scoreDisplay">Score: 0</div>
                <div id="timeDisplay">Time: 30</div>
            </div>
        </div>

        <div id="startScreen" class="screen">
            <h1>Lantern Sprint</h1>
            <p>Catch the glowing lanterns.<br>Avoid the rain clouds.<br>Use Arrow Keys or Touch sides.</p>
            <button id="startBtn">Start Run</button>
        </div>

        <div id="gameOverScreen" class="screen hidden">
            <h1>Time Up!</h1>
            <p>Final Score: <span id="finalScore" class="stat-value">0</span></p>
            <button id="restartBtn">Try Again</button>
        </div>
    </div>

    <script>
        const canvas = document.getElementById('gameCanvas');
        const ctx = canvas.getContext('2d');
        const scoreDisplay = document.getElementById('scoreDisplay');
        const timeDisplay = document.getElementById('timeDisplay');
        const startScreen = document.getElementById('startScreen');
        const gameOverScreen = document.getElementById('gameOverScreen');
        const finalScoreEl = document.getElementById('finalScore');

        let gameRunning = false;
        let score = 0;
        let timeLeft = 30;
        let lastTime = 0;
        let spawnTimer = 0;
        let difficulty = 1;

        // Game Objects
        const player = {
            x: 0, y: 0, width: 50, height: 70, speed: 0, targetX: 0, color: '#d32f2f'
        };
        let items = []; // Lanterns and Clouds
        let particles = [];

        // Input State
        const keys = { ArrowLeft: false, ArrowRight: false };

        // Setup Canvas Size
        function resize() {
            canvas.width = canvas.parentElement.clientWidth;
            canvas.height = canvas.parentElement.clientHeight;
            player.y = canvas.height - 100;
            if (!gameRunning) {
                player.x = canvas.width / 2;
            }
        }
        window.addEventListener('resize', resize);
        resize();

        // Input Handling
        window.addEventListener('keydown', (e) => { if(keys.hasOwnProperty(e.code)) keys[e.code] = true; });
        window.addEventListener('keyup', (e) => { if(keys.hasOwnProperty(e.code)) keys[e.code] = false; });

        // Touch Support
        canvas.addEventListener('touchstart', handleTouch);
        canvas.addEventListener('touchmove', handleTouch);
        canvas.addEventListener('touchend', () => {
            player.targetX = player.x;
        });

        function handleTouch(e) {
            e.preventDefault();
            const rect = canvas.getBoundingClientRect();
            const touchX = e.touches[0].clientX - rect.left;
            player.targetX = touchX;
        }

        // Start / Restart
        document.getElementById('startBtn').addEventListener('click', startGame);
        document.getElementById('restartBtn').addEventListener('click', startGame);

        function startGame() {
            gameRunning = true;
            score = 0;
            timeLeft = 30;
            items = [];
            particles = [];
            difficulty = 1;
            player.x = canvas.width / 2;
            player.targetX = player.x;
            scoreDisplay.textContent = `Score: 0`;
            timeDisplay.textContent = `Time: 30`;
            startScreen.classList.add('hidden');
            gameOverScreen.classList.add('hidden');
            lastTime = performance.now();
            requestAnimationFrame(gameLoop);

            // Start Timer
            const timerInterval = setInterval(() => {
                if (!gameRunning) {
                    clearInterval(timerInterval);
                    return;
                }
                timeLeft--;
                timeDisplay.textContent = `Time: ${timeLeft}`;
                difficulty = 1 + (30 - timeLeft) * 0.05;
                if (timeLeft <= 0) endGame();
            }, 1000);
        }

        function endGame() {
            gameRunning = false;
            finalScoreEl.textContent = score;
            gameOverScreen.classList.remove('hidden');
        }

        function spawnItem() {
            const isCloud = Math.random() > 0.7; // 30% chance for cloud
            const size = isCloud ? 60 : 40;
            const x = Math.random() * (canvas.width - size);
            items.push({
                x: x,
                y: -50,
                width: size,
                height: size,
                speed: (Math.random() * 3 + 2) * difficulty,
                type: isCloud ? 'cloud' : 'lantern',
                angle: 0
            });
        }

        function createParticles(x, y, color) {
            for (let i = 0; i < 8; i++) {
                particles.push({
                    x: x,
                    y: y,
                    vx: (Math.random() - 0.5) * 10,
                    vy: (Math.random() - 0.5) * 10,
                    life: 1.0,
                    color: color
                });
            }
        }

        function drawPlayer() {
            // Smooth movement towards target
            player.x += (player.targetX - player.x) * 0.2;

            // Clamp
            if (player.x < player.width/2) player.x = player.width/2;
            if (player.x > canvas.width - player.width/2) player.x = canvas.width - player.width/2;

            ctx.save();
            ctx.translate(player.x, player.y);

            // Handle keyboard override
            if (keys.ArrowLeft) player.targetX -= 8;
            if (keys.ArrowRight) player.targetX += 8;

            // Stick
            ctx.fillStyle = '#8d6e63';
            ctx.fillRect(-2, -10, 4, 20);

            // Body (Lantern shape)
            ctx.fillStyle = player.color;
            ctx.beginPath();
            ctx.ellipse(0, 0, 20, 30, 0, 0, Math.PI * 2);
            ctx.fill();

            // Shine
            ctx.fillStyle = '#ffeb3b';
            ctx.beginPath();
            ctx.ellipse(0, 0, 12, 20, 0, 0, Math.PI * 2);
            ctx.fill();

            // Glow
            ctx.shadowColor = '#ffeb3b';
            ctx.shadowBlur = 20;
            ctx.fillStyle = 'rgba(255, 235, 59, 0.5)';
            ctx.beginPath();
            ctx.ellipse(0, 0, 15, 25, 0, 0, Math.PI * 2);
            ctx.fill();
            ctx.restore();
        }

        function drawItems() {
            items.forEach((item, index) => {
                ctx.save();
                ctx.translate(item.x + item.width/2, item.y + item.height/2);

                if (item.type === 'lantern') {
                    // Draw Lantern
                    item.angle += 0.05;
                    ctx.rotate(Math.sin(item.angle) * 0.2);

                    // Rope
                    ctx.strokeStyle = '#5d4037';
                    ctx.beginPath();
                    ctx.moveTo(0, -item.height/2 - 10);
                    ctx.lineTo(0, -item.height/2);
                    ctx.stroke();

                    // Red Shell
                    ctx.fillStyle = '#d32f2f';
                    ctx.beginPath();
                    ctx.rect(-15, -20, 30, 40);
                    ctx.fill();

                    // Gold Caps
                    ctx.fillStyle = '#ffb300';
                    ctx.fillRect(-15, -20, 30, 5);
                    ctx.fillRect(-15, 15, 30, 5);

                    // Inner Glow
                    ctx.shadowColor = '#ffeb3b';
                    ctx.shadowBlur = 15;
                    ctx.fillStyle = '#ffeb3b';
                    ctx.fillRect(-10, -15, 20, 30);

                } else {
                    // Draw Cloud
                    ctx.fillStyle = '#78909c';
                    ctx.beginPath();
                    ctx.arc(0, 0, 25, 0, Math.PI*2);
                    ctx.arc(-20, 5, 20, 0, Math.PI*2);
                    ctx.arc(20, 5, 20, 0, Math.PI*2);
                    ctx.fill();

                    // Darker underbelly
                    ctx.fillStyle = '#455a64';
                    ctx.beginPath();
                    ctx.arc(0, 5, 25, 0, Math.PI, true);
                    ctx.fill();
                }
                ctx.restore();
            });
        }

        function drawParticles() {
            for (let i = particles.length - 1; i >= 0; i--) {
                const p = particles[i];
                ctx.fillStyle = p.color;
                ctx.globalAlpha = p.life;
                ctx.beginPath();
                ctx.arc(p.x, p.y, 4 * p.life, 0, Math.PI*2);
                ctx.fill();
                p.x += p.vx;
                p.y += p.vy;
                p.life -= 0.05;
                if (p.life <= 0) particles.splice(i, 1);
            }
            ctx.globalAlpha = 1.0;
        }

        function update(dt) {
            // Spawning
            spawnTimer += dt;
            if (spawnTimer > (1000 / difficulty)) {
                spawnItem();
                spawnTimer = 0;
            }

            // Item Physics
            for (let i = items.length - 1; i >= 0; i--) {
                const item = items[i];
                item.y += item.speed;

                // Collision
                const dx = (player.x) - (item.x + item.width/2);
                const dy = (player.y) - (item.y + item.height/2);
                const dist = Math.sqrt(dx*dx + dy*dy);

                if (dist < 45) { // Hit
                    if (item.type === 'lantern') {
                        score += 10;
                        scoreDisplay.textContent = `Score: ${score}`;
                        createParticles(player.x, player.y, '#ffeb3b');
                    } else {
                        score -= 20;
                        scoreDisplay.textContent = `Score: ${score}`;
                        createParticles(player.x, player.y, '#546e7a');
                        // Visual shake or flash could go here
                    }
                    items.splice(i, 1);
                    continue;
                }

                // Remove off screen
                if (item.y > canvas.height + 50) {
                    items.splice(i, 1);
                }
            }
        }

        function gameLoop(timestamp) {
            if (!gameRunning) return;

            const dt = timestamp - lastTime;
            lastTime = timestamp;

            ctx.clearRect(0, 0, canvas.width, canvas.height);

            update(dt);
            drawItems();
            drawPlayer();
            drawParticles();

            requestAnimationFrame(gameLoop);
        }
    </script>
</body>
</html>
```

## File: examples/apps/cinematic-ai-landing.html
size: 18126
sha: 33a27e6eb65b9bf718dd525b4a9af5d1eef3d57b
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/examples/apps/cinematic-ai-landing.html

```text
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Agnes AI | Intelligent Architecture</title>
    <style>
        :root {
            --pearl: #F9F9F7;
            --sand: #F4F2ED;
            --ink: #121212;
            --gray: #555555;
            --light-gray: #E5E5E5;
            --amber: #D96C2A;
            --amber-hover: #C0581D;
            --font-main: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
            --font-serif: Georgia, "Times New Roman", serif;
        }
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body {
            font-family: var(--font-main);
            background-color: var(--pearl);
            color: var(--ink);
            line-height: 1.6;
            overflow-x: hidden;
            -webkit-font-smoothing: antialiased;
        }
        a { text-decoration: none; color: inherit; transition: opacity 0.2s; }
        a:hover { opacity: 0.6; }

        /* Layout Utilities */
        .container {
            max-width: 1200px;
            margin: 0 auto;
            padding: 0 2rem;
        }
        .grid {
            display: grid;
            gap: 2rem;
        }
        .grid-2 { grid-template-columns: 1fr 1fr; }
        .grid-3 { grid-template-columns: repeat(3, 1fr); }

        /* Typography */
        h1, h2, h3 { font-weight: 600; letter-spacing: -0.03em; line-height: 1.1; }
        h1 { font-size: 3.5rem; margin-bottom: 1.5rem; }
        h2 { font-size: 2rem; margin-bottom: 1rem; }
        h3 { font-size: 1.25rem; margin-bottom: 0.5rem; }
        p { margin-bottom: 1.5rem; color: var(--gray); font-size: 1.05rem; }
        .serif { font-family: var(--font-serif); font-style: italic; color: var(--amber); }

        /* Buttons */
        .btn {
            display: inline-block;
            padding: 0.8rem 1.8rem;
            font-size: 0.9rem;
            font-weight: 500;
            letter-spacing: 0.02em;
            border: 1px solid var(--ink);
            transition: all 0.3s ease;
            cursor: pointer;
        }
        .btn-primary {
            background-color: var(--ink);
            color: var(--pearl);
        }
        .btn-primary:hover {
            background-color: var(--amber);
            border-color: var(--amber);
            opacity: 1;
        }
        .btn-secondary {
            background-color: transparent;
            color: var(--ink);
        }
        .btn-secondary:hover {
            background-color: var(--ink);
            color: var(--pearl);
            opacity: 1;
        }

        /* Header */
        header {
            padding: 1.5rem 0;
            position: sticky;
            top: 0;
            background: rgba(249, 249, 247, 0.9);
            backdrop-filter: blur(10px);
            z-index: 100;
            border-bottom: 1px solid var(--light-gray);
        }
        nav {
            display: flex;
            justify-content: space-between;
            align-items: center;
        }
        .logo { font-weight: 700; font-size: 1.2rem; letter-spacing: -0.05em; }
        .nav-links { display: flex; gap: 2rem; align-items: center; }
        .nav-links a { font-size: 0.9rem; font-weight: 500; }

        /* Hero */
        .hero {
            padding: 8rem 0 6rem;
            display: flex;
            flex-direction: column;
            justify-content: center;
            min-height: 80vh;
        }
        .hero-grid {
            display: grid;
            grid-template-columns: 1.2fr 0.8fr;
            gap: 4rem;
            align-items: center;
        }
        .hero-visual {
            background: var(--sand);
            height: 400px;
            width: 100%;
            display: flex;
            align-items: center;
            justify-content: center;
            border-left: 4px solid var(--amber);
            position: relative;
        }
        .hero-visual::after {
            content: "System Ready";
            position: absolute;
            bottom: 1.5rem;
            right: 1.5rem;
            font-family: monospace;
            font-size: 0.8rem;
            color: var(--gray);
        }

        /* Sections */
        section { padding: 6rem 0; }
        .section-header {
            border-top: 1px solid var(--light-gray);
            padding-top: 2rem;
            margin-bottom: 4rem;
            display: flex;
            justify-content: space-between;
            align-items: flex-end;
        }
        .section-tag {
            text-transform: uppercase;
            font-size: 0.75rem;
            letter-spacing: 0.1em;
            color: var(--amber);
            margin-bottom: 1rem;
            display: block;
        }

        /* Cards */
        .card {
            background: white;
            padding: 2rem;
            border: 1px solid var(--light-gray);
            transition: transform 0.3s, box-shadow 0.3s;
        }
        .card:hover {
            transform: translateY(-4px);
            box-shadow: 0 10px 30px rgba(0,0,0,0.05);
            border-color: var(--amber);
        }
        .stat-number {
            font-size: 2.5rem;
            font-weight: 700;
            color: var(--ink);
            margin-bottom: 0.2rem;
        }

        /* Developer / API */
        .dev-section {
            background: var(--ink);
            color: var(--pearl);
            padding: 6rem 0;
        }
        .dev-section p { color: #A0A0A0; }
        .code-block {
            background: #1A1A1A;
            padding: 1.5rem;
            border-radius: 4px;
            font-family: monospace;
            font-size: 0.85rem;
            color: #D96C2A;
            margin: 2rem 0;
            border-left: 1px solid #333;
        }

        /* Trust */
        .trust-bar {
            display: flex;
            gap: 4rem;
            align-items: center;
            padding: 2rem 0;
            border-top: 1px solid var(--light-gray);
            border-bottom: 1px solid var(--light-gray);
            margin-top: 4rem;
            opacity: 0.6;
        }
        .trust-item { font-weight: 600; font-size: 1.2rem; color: var(--gray); }

        /* Footer */
        footer {
            background: white;
            padding: 4rem 0;
            margin-top: 4rem;
        }
        .footer-grid {
            display: flex;
            justify-content: space-between;
        }
        .footer-col h4 { font-size: 0.9rem; margin-bottom: 1.2rem; }
        .footer-col ul { list-style: none; }
        .footer-col li { margin-bottom: 0.8rem; }
        .footer-col a { font-size: 0.9rem; color: var(--gray); }
        .footer-col a:hover { color: var(--ink); opacity: 1; }

        /* Mobile */
        @media (max-width: 768px) {
            h1 { font-size: 2.5rem; }
            .grid-2, .grid-3, .hero-grid, .footer-grid { grid-template-columns: 1fr; display: flex; flex-direction: column; }
            .nav-links { display: none; }
            .hero-visual { height: 250px; margin-top: 2rem; }
            .section-header { flex-direction: column; align-items: flex-start; }
        }
    </style>
</head>
<body>

    <!-- Navigation -->
    <header>
        <div class="container">
            <nav>
                <a href="#" class="logo">AGNES AI</a>
                <div class="nav-links">
                    <a href="#platform">Platform</a>
                    <a href="#research">Research</a>
                    <a href="#enterprise">Enterprise</a>
                    <a href="#pricing">Pricing</a>
                    <a href="#" class="btn btn-primary" style="padding: 0.5rem 1.2rem; font-size: 0.8rem;">Launch Console</a>
                </div>
            </nav>
        </div>
    </header>

    <!-- Hero Section -->
    <section class="container hero">
        <div class="hero-grid">
            <div>
                <span class="section-tag">Next Generation Infrastructure</span>
                <h1>Architectural <br><span class="serif">intelligence.</span></h1>
                <p>Agnes AI delivers semantic precision for the world's most demanding developers. We bridge the gap between raw computation and refined logic.</p>
                <div style="margin-top: 2rem;">
                    <a href="#api" class="btn btn-primary">Get API Keys</a>
                    <a href="#docs" class="btn btn-secondary" style="margin-left: 1rem;">Read Documentation</a>
                </div>
            </div>
            <div class="hero-visual">
                <div style="text-align: left; width: 80%;">
                    <div style="height: 4px; width: 40px; background: var(--amber); margin-bottom: 20px;"></div>
                    <div style="height: 8px; width: 100%; background: #EAE9E4; margin-bottom: 10px;"></div>
                    <div style="height: 8px; width: 85%; background: #EAE9E4; margin-bottom: 10px;"></div>
                    <div style="height: 8px; width: 92%; background: #EAE9E4; margin-bottom: 20px;"></div>
                    <div style="font-family: monospace; font-size: 0.8rem; color: var(--amber); margin-top: 30px;">
                        &gt; optimizing neural weights...<br>
                        &gt; latency: 12ms<br>
                        &gt; context window: 128k
                    </div>
                </div>
            </div>
        </div>
    </section>

    <!-- Model Overview -->
    <section class="container">
        <div class="section-header">
            <div>
                <span class="section-tag">Model Zoo</span>
                <h2>Tailored for scale.</h2>
            </div>
            <a href="#" style="border-bottom: 1px solid var(--ink); font-size: 0.9rem;">View full specifications</a>
        </div>
            <div class="grid grid-3">
                <div class="card">
                    <h3>agnes-2.0-flash</h3>
                    <p style="font-size: 0.9rem; margin-bottom: 1rem;">Fast default for chat, coding, tool calling, and agent workflows where teams want a single dependable text model.</p>
                    <a href="#" style="font-size: 0.85rem; font-weight: 600; color: var(--ink);">Launch text workflows &rarr;</a>
                </div>
                <div class="card" style="border-color: var(--ink);">
                    <div style="font-size: 0.7rem; background: var(--ink); color: white; display: inline-block; padding: 2px 6px; margin-bottom: 1rem;">RECOMMENDED</div>
                    <h3>agnes-image-2.1-flash</h3>
                    <p style="font-size: 0.9rem; margin-bottom: 1rem;">Preferred visual model for dense compositions, polished marketing imagery, and image-to-image work that preserves layout.</p>
                    <a href="#" style="font-size: 0.85rem; font-weight: 600; color: var(--amber);">Generate visual campaigns &rarr;</a>
                </div>
                <div class="card">
                    <h3>agnes-video-v2.0</h3>
                    <p style="font-size: 0.9rem; margin-bottom: 1rem;">Asynchronous video generation for ad spots, animated concepts, and cinematic motion studies driven by text or image prompts.</p>
                    <a href="#" style="font-size: 0.85rem; font-weight: 600; color: var(--ink);">Create motion stories &rarr;</a>
                </div>
            </div>
        </section>

    <!-- Feature Story: Developer Experience -->
    <section id="api" class="dev-section">
        <div class="container">
            <div class="grid grid-2" style="align-items: center;">
                <div>
                    <span class="section-tag">Integration</span>
                    <h2 style="color: white;">Designed for the <span style="color: var(--amber);">developer</span> workflow.</h2>
                    <p>Agnes AI isn't just a model; it's a structural component of your stack. Our API is standardized, typed, and incredibly fast.</p>
                    <ul style="margin-bottom: 2rem; list-style: none; color: #A0A0A0;">
                        <li style="margin-bottom: 0.5rem;">&bull; 99.99% SLA Uptime</li>
                        <li style="margin-bottom: 0.5rem;">&bull; JSON-mode strict parsing</li>
                        <li style="margin-bottom: 0.5rem;">&bull; Streaming tokens for real-time UI</li>
                    </ul>
                    <a href="#" class="btn btn-secondary" style="border-color: #555; color: white;">View API Reference</a>
                </div>
                <div>
                    <div class="code-block">
const agnes = require('agnes-sdk');<br><br>
const response = await agnes.chat.complete({<br>
&nbsp;&nbsp;model: 'agnes-14b-v4',<br>
&nbsp;&nbsp;messages: [<br>
&nbsp;&nbsp;&nbsp;&nbsp;{ role: 'user', content: 'Analyze this dataset.' }<br>
&nbsp;&nbsp;],<br>
&nbsp;&nbsp;temperature: 0.2,<br>
&nbsp;&nbsp;response_format: { type: 'json_object' }<br>
});<br><br>
console.log(response.choices[0].message);
                    </div>
                </div>
            </div>
        </div>
    </section>

    <!-- Trust & Features -->
    <section class="container">
        <div class="section-header">
            <div>
                <span class="section-tag">Enterprise Grade</span>
                <h2>Reliability by design.</h2>
            </div>
        </div>
        <div class="grid grid-3">
            <div style="padding: 1rem 0;">
                <div class="stat-number">128k</div>
                <h3>Context Window</h3>
                <p style="font-size: 0.9rem;">Process entire codebases or legal documents in a single pass.</p>
            </div>
            <div style="padding: 1rem 0; border-left: 1px solid var(--light-gray);">
                <div class="stat-number">4x</div>
                <h3>Inference Speed</h3>
                <p style="font-size: 0.9rem;">Proprietary pruning algorithms ensure faster time-to-first-token.</p>
            </div>
            <div style="padding: 1rem 0; border-left: 1px solid var(--light-gray);">
                <div class="stat-number">SOC2</div>
                <h3>Compliant</h3>
                <p style="font-size: 0.9rem;">Type B certification for data privacy and secure handling.</p>
            </div>
        </div>

        <div class="trust-bar">
            <span class="trust-item">NVIDIA PARTNER</span>
            <span class="trust-item">STACK OVERFLOW SPONSOR</span>
            <span class="trust-item">GITHUB EXCEL</span>
            <span class="trust-item">Vercel</span>
        </div>
    </section>

    <!-- Final CTA -->
    <section style="background: var(--sand); text-align: center;">
        <div class="container">
            <h2 style="font-size: 2.5rem; margin-bottom: 1rem;">Ready to build?</h2>
            <p style="max-width: 600px; margin: 0 auto 2rem auto;">Join thousands of engineers who have migrated to Agnes AI for better accuracy and lower latency.</p>
            <a href="#" class="btn btn-primary" style="padding: 1rem 3rem;">Start Building Now</a>
        </div>
    </section>

    <!-- Footer -->
    <footer class="container">
        <div class="footer-grid">
            <div class="footer-col" style="max-width: 300px;">
                <div class="logo" style="margin-bottom: 1rem;">AGNES AI</div>
                <p style="font-size: 0.85rem;">San Francisco, CA.<br>Optimizing the future of intelligence.</p>
            </div>
            <div class="footer-col">
                <h4>PRODUCT</h4>
                <ul>
                    <li><a href="#">Model Zoo</a></li>
                    <li><a href="#">Pricing</a></li>
                    <li><a href="#">Security</a></li>
                    <li><a href="#">Enterprise</a></li>
                </ul>
            </div>
            <div class="footer-col">
                <h4>DEVELOPERS</h4>
                <ul>
                    <li><a href="#">Documentation</a></li>
                    <li><a href="#">API Reference</a></li>
                    <li><a href="#">GitHub Repo</a></li>
                    <li><a href="#">Status</a></li>
                </ul>
            </div>
            <div class="footer-col">
                <h4>COMPANY</h4>
                <ul>
                    <li><a href="#">About</a></li>
                    <li><a href="#">Blog</a></li>
                    <li><a href="#">Careers</a></li>
                    <li><a href="#">Contact</a></li>
                </ul>
            </div>
        </div>
        <div style="margin-top: 4rem; padding-top: 2rem; border-top: 1px solid var(--light-gray); display: flex; justify-content: space-between; font-size: 0.8rem; color: var(--gray);">
            <span>&copy; 2024 Agnes AI Inc. All rights reserved.</span>
            <div>
                <a href="#" style="margin-left: 1rem;">Privacy Policy</a>
                <a href="#" style="margin-left: 1rem;">Terms of Service</a>
            </div>
        </div>
    </footer>

    <script>
        // Simple script to handle smooth scroll for anchor links
        document.querySelectorAll('a[href^="#"]').forEach(anchor => {
            anchor.addEventListener('click', function (e) {
                e.preventDefault();
                document.querySelector(this.getAttribute('href')).scrollIntoView({
                    behavior: 'smooth'
                });
            });
        });

        // Minimal scroll observer for fade-in effect (Performance conscious)
        const observer = new IntersectionObserver((entries) => {
            entries.forEach(entry => {
                if (entry.isIntersecting) {
                    entry.target.style.opacity = 1;
                    entry.target.style.transform = 'translateY(0)';
                }
            });
        });

        // Add subtle load animation to cards
        document.querySelectorAll('.card').forEach((card, index) => {
            card.style.opacity = 0;
            card.style.transform = 'translateY(20px)';
            card.style.transition = `all 0.6s ease ${index * 0.1}s`;
            observer.observe(card);
        });
    </script>
</body>
</html>
```

## File: examples/apps/watch-experience.html
size: 12545
sha: 804e8d1cca9adb3bbc0eb0153a56f0c6d793fc3c
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/examples/apps/watch-experience.html

```text
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Golden Hour Stories | Agnes Image + Video</title>
    <style>
        :root {
            --cream: #F9F7F2;
            --blush: #F2E6E5;
            --gold: #C5A065;
            --gold-dark: #A68248;
            --text: #2C2824;
            --font-serif: 'Times New Roman', Times, serif;
            --font-sans: 'Helvetica Neue', Helvetica, Arial, sans-serif;
        }
        body {
            margin: 0;
            padding: 0;
            background-color: var(--cream);
            color: var(--text);
            font-family: var(--font-sans);
            line-height: 1.6;
            overflow-x: hidden;
        }
        .container {
            max-width: 1200px;
            margin: 0 auto;
            padding: 0 40px;
        }
        h1, h2, h3, h4 {
            font-family: var(--font-serif);
            font-weight: 400;
            margin: 0 0 20px 0;
            letter-spacing: -0.02em;
        }
        .btn {
            display: inline-block;
            background-color: var(--gold);
            color: #fff;
            padding: 18px 40px;
            text-decoration: none;
            text-transform: uppercase;
            font-size: 0.85rem;
            letter-spacing: 0.15em;
            transition: background 0.3s ease;
            border: none;
            cursor: pointer;
        }
        .btn:hover {
            background-color: var(--gold-dark);
        }
        header {
            padding: 40px 0;
            display: flex;
            justify-content: space-between;
            align-items: center;
        }
        .logo {
            font-family: var(--font-serif);
            font-size: 1.5rem;
            font-weight: 700;
            letter-spacing: 0.05em;
        }
        .nav-link {
            color: var(--text);
            text-decoration: none;
            font-size: 0.8rem;
            text-transform: uppercase;
            letter-spacing: 0.1em;
        }
        .hero {
            padding: 120px 0;
            text-align: center;
            background: linear-gradient(to bottom, var(--cream), var(--blush));
        }
        .hero h1 {
            font-size: 5rem;
            line-height: 0.95;
            color: var(--text);
            margin-bottom: 30px;
        }
        .hero p {
            font-size: 1.25rem;
            max-width: 600px;
            margin: 0 auto 50px;
            color: #665c56;
            font-family: var(--font-serif);
            font-style: italic;
        }
        .campaign-narrative {
            padding: 100px 0;
            border-top: 1px solid #E5DFD6;
        }
        .narrative-grid {
            display: grid;
            grid-template-columns: 1fr 1fr;
            gap: 60px;
            align-items: center;
        }
        .narrative-text h2 {
            font-size: 3rem;
            line-height: 1.1;
        }
        .narrative-text p {
            font-size: 1rem;
            margin-bottom: 30px;
            color: #555;
        }
        .narrative-visual {
            height: 500px;
            background-color: var(--gold);
            position: relative;
            overflow: hidden;
        }
        .narrative-visual::after {
            content: '';
            position: absolute;
            top: 0;
            left: 0;
            right: 0;
            bottom: 0;
            background: linear-gradient(45deg, rgba(197, 160, 101, 0.4), rgba(44, 40, 36, 0.2));
        }
        .panels {
            padding: 120px 0;
            background-color: var(--blush);
        }
        .section-header {
            text-align: center;
            margin-bottom: 80px;
        }
        .section-header h3 {
            font-size: 2.5rem;
        }
        .section-header p {
            font-size: 0.9rem;
            text-transform: uppercase;
            letter-spacing: 0.2em;
            color: var(--gold-dark);
        }
        .panel-grid {
            display: grid;
            grid-template-columns: repeat(3, 1fr);
            gap: 30px;
        }
        .panel {
            background-color: var(--cream);
            padding: 40px;
            transition: transform 0.4s ease;
        }
        .panel:hover {
            transform: translateY(-10px);
        }
        .panel-icon {
            width: 60px;
            height: 60px;
            background-color: var(--gold);
            margin-bottom: 30px;
            border-radius: 50%;
            display: flex;
            align-items: center;
            justify-content: center;
            color: white;
            font-size: 1.5rem;
            font-family: var(--font-serif);
        }
        .panel h4 {
            font-size: 1.5rem;
            margin-bottom: 15px;
        }
        .panel p {
            font-size: 0.95rem;
            color: #666;
        }
        .social-proof {
            padding: 80px 0;
            background-color: var(--cream);
            text-align: center;
        }
        .proof-strip {
            display: flex;
            justify-content: center;
            gap: 60px;
            margin-top: 40px;
            flex-wrap: wrap;
        }
        .proof-item {
            text-align: center;
        }
        .proof-number {
            font-family: var(--font-serif);
            font-size: 3rem;
            color: var(--gold);
            display: block;
            line-height: 1;
        }
        .proof-label {
            font-size: 0.75rem;
            text-transform: uppercase;
            letter-spacing: 0.1em;
            margin-top: 10px;
            display: block;
            color: #888;
        }
        .cta-section {
            padding: 150px 0;
            background-color: var(--text);
            color: var(--cream);
            text-align: center;
        }
        .cta-section h2 {
            font-size: 4rem;
            color: var(--gold);
            margin-bottom: 30px;
        }
        .cta-section p {
            font-size: 1.2rem;
            margin-bottom: 50px;
            color: #ccc;
            max-width: 700px;
            margin-left: auto;
            margin-right: auto;
        }
        .cta-section .btn {
            background-color: var(--gold);
        }
        footer {
            padding: 40px 0;
            text-align: center;
            font-size: 0.8rem;
            color: #888;
            background-color: var(--cream);
        }
        @media (max-width: 768px) {
            .hero h1 { font-size: 3rem; }
            .narrative-grid { grid-template-columns: 1fr; }
            .panel-grid { grid-template-columns: 1fr; }
            .proof-strip { gap: 30px; }
            .container { padding: 0 20px; }
        }
    </style>
</head>
<body>

    <div class="container">
        <header>
            <div class="logo">AGNES + VIDEO</div>
            <nav>
                <a href="#" class="nav-link">Campaign</a>
            </nav>
        </header>
    </div>

    <section class="hero">
        <div class="container">
            <h1>GOLDEN HOUR<br>STORIES</h1>
            <p>A curated visual journey capturing the ephemeral beauty of fleeting moments. Experience luxury through light.</p>
            <a href="#cta" class="btn">View Collection</a>
        </div>
    </section>

    <section class="campaign-narrative">
        <div class="container">
            <div class="narrative-grid">
                <div class="narrative-text">
                    <h2>THE ALCHEMY OF LIGHT</h2>
                    <p>Golden Hour Stories is not merely a collection; it is an immersive editorial experience. We explore the intersection of high fashion and natural brilliance, where every frame tells a story of warmth, elegance, and timeless appeal.</p>
                    <p>Our creative drop features exclusive imagery and cinematic video clips designed to elevate your digital presence. Crafted for the discerning eye, this campaign redefines the standard of premium content.</p>
                    <a href="#" class="nav-link" style="border-bottom: 1px solid var(--text); padding-bottom: 5px;">Read the Manifesto</a>
                </div>
                <div class="narrative-visual"></div>
            </div>
        </div>
    </section>

    <section class="panels">
        <div class="container">
            <div class="section-header">
                <p>The Collection</p>
                <h3>THREE PERSPECTIVES</h3>
            </div>
            <div class="panel-grid">
                <div class="panel">
                    <div class="panel-icon">I</div>
                    <h4>Visual Essays</h4>
                    <p>High-resolution editorial photography capturing the essence of sunset hues and shadow play. Perfect for digital campaigns and print inspiration.</p>
                </div>
                <div class="panel">
                    <div class="panel-icon">II</div>
                    <h4>Cinematic Loops</h4>
                    <p>Seamless video loops designed to bring life to static spaces. Experience motion in its most refined form, with a focus on texture and movement.</p>
                </div>
                <div class="panel">
                    <div class="panel-icon">III</div>
                    <h4>Brand Assets</h4>
                    <p>Curated templates and overlays to integrate the Golden Hour aesthetic into your existing brand identity. Elevate your visual language instantly.</p>
                </div>
            </div>
        </div>
    </section>

    <section class="social-proof">
        <div class="container">
            <div class="section-header">
                <p>Impact</p>
            </div>
            <div class="proof-strip">
                <div class="proof-item">
                    <span class="proof-number" data-target="250">0</span>
                    <span class="proof-label">Assets Included</span>
                </div>
                <div class="proof-item">
                    <span class="proof-number" data-target="48">0</span>
                    <span class="proof-label">Countries Reached</span>
                </div>
                <div class="proof-item">
                    <span class="proof-number" data-target="12">0</span>
                    <span class="proof-label">Industry Awards</span>
                </div>
                <div class="proof-item">
                    <span class="proof-number" data-target="100">0</span>
                    <span class="proof-label">Percent Premium</span>
                </div>
            </div>
        </div>
    </section>

    <section id="cta" class="cta-section">
        <div class="container">
            <h2>ACQUIRE THE DROP</h2>
            <p>Join the list of creative directors and agencies transforming their visual narratives. Limited availability for the inaugural release.</p>
            <a href="#" class="btn">Get Access Now</a>
        </div>
    </section>

    <footer>
        <div class="container">
            <p>&copy; 2023 Agnes Image + Video. All rights reserved. Designed for Excellence.</p>
        </div>
    </footer>

    <script>
        document.addEventListener('DOMContentLoaded', function() {
            const counters = document.querySelectorAll('.proof-number');
            const speed = 200;

            const animateCounters = () => {
                counters.forEach(counter => {
                    const target = +counter.getAttribute('data-target');
                    const count = +counter.innerText;
                    const inc = target / speed;

                    if (count < target) {
                        counter.innerText = Math.ceil(count + inc);
                        setTimeout(animateCounters, 20);
                    } else {
                        counter.innerText = target;
                    }
                });
            };

            const observer = new IntersectionObserver((entries) => {
                entries.forEach(entry => {
                    if (entry.isIntersecting) {
                        animateCounters();
                        observer.unobserve(entry.target);
                    }
                });
            }, { threshold: 0.5 });

            const proofSection = document.querySelector('.social-proof');
            if (proofSection) {
                observer.observe(proofSection);
            }
        });
    </script>
</body>
</html>
```

## File: LICENSE
size: 1067
sha: bc8042b36d186963b33815c8da84996c77029fab
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/LICENSE

```text
MIT License

Copyright (c) 2026 Jomes Wang

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

## File: README.zh-CN.md
size: 6630
sha: 9e95e26a55a40eed175ff8137b5e3a92985b74f7
upstream: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/README.zh-CN.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/jomeswang/agnes-ai-skill/blob/HEAD/README.zh-CN.md
