image-skill 0.1.27 → 0.1.28

package/CHANGELOG.md

@@ -4,7 +4,26 @@ This changelog tracks the public `image-skill` CLI package and public skill
 mirror. The npm package metadata remains the authority for tarball integrity and
 provenance; this file is the human- and agent-readable release map.
 
-## Unreleased
+## 0.1.28 - 2026-06-02
+
+- Feature (discoverability): publish intent-named public skill aliases
+  (`ai-image-generation`, `image-edit`, `ai-video-generation`,
+  `ai-audio-generation`, `image-to-3d`, and `creative-media`) from the public
+  mirror and hosted `.well-known/agent-skills` index. Each alias points to the
+  same zero-setup Image Skill runtime, CLI/API contract, identity, wallet, jobs,
+  receipts, and feedback loop as the canonical `image-skill` skill, giving
+  skills.sh task searches literal skill names to index without fragmenting the
+  product.
+- Fix (guide): `create --guide` now exposes `data.next_command_effect` and
+  `data.no_spend_next_command`. When the guide reaches `ready_to_create`, the
+  live create remains `data.next_command`, but it is explicitly labeled
+  `live_media_create_credit_debit` with provider-call, hosted-create,
+  credit-debit, and media-write flags. No-spend/evaluation agents can run the
+  top-level dry-run verification command instead of digging through escape
+  hatches or risking an accidental media job.
+- Docs: public CLI, LLM contract, canonical skill, and modality aliases now
+  teach the ready-to-create distinction between live media creation and
+  no-spend verification.
 
 ## 0.1.27 - 2026-06-02
 

package/README.md

@@ -15,6 +15,18 @@ discoverable on skills.sh:
 npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
 ```
 
+Intent-named aliases are published from the same repo and point to the same
+zero-setup runtime when an agent searches by task instead of brand:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill ai-image-generation -g -a codex -y
+npx skills add danielgwilson/image-skill-cli --skill image-edit -g -a codex -y
+npx skills add danielgwilson/image-skill-cli --skill ai-video-generation -g -a codex -y
+npx skills add danielgwilson/image-skill-cli --skill ai-audio-generation -g -a codex -y
+npx skills add danielgwilson/image-skill-cli --skill image-to-3d -g -a codex -y
+npx skills add danielgwilson/image-skill-cli --skill creative-media -g -a codex -y
+```
+
 Or install straight from the hosted public contract for the always-latest build:
 
 ```bash
@@ -56,6 +68,7 @@ Agent-facing contracts:
 - [Hosted LLM contract](https://image-skill.com/llms.txt)
 - [Hosted CLI contract](https://image-skill.com/cli.md)
 - [Public repo skill source](https://github.com/danielgwilson/image-skill-cli/tree/main/skills/image-skill)
+- [Intent skill aliases](https://github.com/danielgwilson/image-skill-cli/tree/main/skills)
 - [Changelog](https://github.com/danielgwilson/image-skill-cli/blob/main/CHANGELOG.md)
 - [Provenance](https://github.com/danielgwilson/image-skill-cli/blob/main/PROVENANCE.md)
 

package/bin/image-skill.mjs

@@ -7,7 +7,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.27";
+const VERSION = "0.1.28";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -1338,6 +1338,21 @@ async function createGuide(args) {
     commandPrefix: PUBLIC_NPX_COMMAND_PREFIX,
     authConfigWritable: authConfigWrite?.ok ?? true,
   });
+  const escapeHatches = createGuideEscapeHatches({
+    prompt: trimmedPrompt,
+    selected,
+    requestedProviderId,
+    requestedIntent,
+    budgetGuard,
+    apiBaseUrl: explicitApiBaseUrl(args),
+    commandPrefix: PUBLIC_NPX_COMMAND_PREFIX,
+  });
+  const nextCommandEffect = createGuideNextCommandEffect(stage, {
+    estimatedCredits,
+    estimatedDebitUsdPerImage,
+  });
+  const noSpendNextCommand =
+    stage === "ready_to_create" ? escapeHatches.dry_run : null;
   const afterNext =
     stage === "auth_required" || stage === "quota_required"
       ? renderGuideCommand(
@@ -1423,48 +1438,15 @@ async function createGuide(args) {
     },
     blocker,
     next_command: nextCommand,
+    next_command_effect: nextCommandEffect,
+    no_spend_next_command: noSpendNextCommand,
+    no_spend_next_command_label:
+      noSpendNextCommand === null
+        ? null
+        : "dry_run_plan_no_provider_call_no_credit_debit_no_media_write",
     after_next: afterNext,
     auth_handoff: authHandoff,
-    escape_hatches: {
-      doctor: renderGuidePrefixedCommand(
-        PUBLIC_NPX_COMMAND_PREFIX,
-        "doctor --json",
-      ),
-      model_inspection:
-        selected === null
-          ? renderGuidePrefixedCommand(
-              PUBLIC_NPX_COMMAND_PREFIX,
-              "models list --json",
-            )
-          : renderGuidePrefixedCommand(
-              PUBLIC_NPX_COMMAND_PREFIX,
-              `models show ${shellQuote(selected.id)} --json`,
-            ),
-      payment_methods: renderGuidePrefixedCommand(
-        PUBLIC_NPX_COMMAND_PREFIX,
-        "credits methods --json",
-      ),
-      quota: renderGuidePrefixedCommand(
-        PUBLIC_NPX_COMMAND_PREFIX,
-        "usage quota --json",
-      ),
-      dry_run:
-        selected === null || trimmedPrompt.length === 0
-          ? renderGuidePrefixedCommand(
-              PUBLIC_NPX_COMMAND_PREFIX,
-              "create --dry-run --prompt PROMPT --json",
-            )
-          : renderCreateCommand({
-              prompt: trimmedPrompt,
-              modelId: selected.id,
-              providerId: requestedProviderId,
-              intent: requestedIntent,
-              budgetGuard,
-              dryRun: true,
-              apiBaseUrl: explicitApiBaseUrl(args),
-              commandPrefix: PUBLIC_NPX_COMMAND_PREFIX,
-            }),
-    },
+    escape_hatches: escapeHatches,
     mutation: {
       provider_call: false,
       hosted_create: false,
@@ -1723,6 +1705,64 @@ function createGuideAuthHandoff(stage, input) {
   return null;
 }
 
+function createGuideNextCommandEffect(stage, input) {
+  const base = {
+    label: "read_only_or_no_media_setup",
+    no_spend: true,
+    provider_call: false,
+    hosted_create: false,
+    hosted_signup: false,
+    payment_object: false,
+    credit_debit: false,
+    media_write: false,
+    estimated_credits: null,
+    estimated_debit_usd_per_image: null,
+    warning: null,
+  };
+  if (stage === "auth_required") {
+    return {
+      ...base,
+      label: "hosted_signup_restricted_agent_identity",
+      hosted_signup: true,
+      warning:
+        "This signs up a restricted Image Skill agent identity but does not create media, call a provider, open payment, or debit credits.",
+    };
+  }
+  if (stage === "quota_required") {
+    return {
+      ...base,
+      label: "payment_or_quota_action",
+      no_spend: false,
+      payment_object: true,
+      warning:
+        "This may create or inspect a payment quote/attempt. Stay within the delegated cap, or use escape_hatches for read-only checks.",
+    };
+  }
+  if (stage === "ready_to_create") {
+    return {
+      label: "live_media_create_credit_debit",
+      no_spend: false,
+      provider_call: true,
+      hosted_create: true,
+      hosted_signup: false,
+      payment_object: false,
+      credit_debit: true,
+      media_write: true,
+      estimated_credits: input.estimatedCredits,
+      estimated_debit_usd_per_image: input.estimatedDebitUsdPerImage,
+      warning:
+        "data.next_command creates hosted media and can debit credits. For no-spend verification, run data.no_spend_next_command instead.",
+    };
+  }
+  if (stage === "prompt_required") {
+    return {
+      ...base,
+      label: "rerun_guide_with_prompt",
+    };
+  }
+  return base;
+}
+
 function createGuideNextCommand(stage, input) {
   if (stage === "prompt_required") {
     return renderGuideCommand("PROMPT", input.apiBaseUrl, input.commandPrefix);
@@ -1764,6 +1804,43 @@ function createGuideNextCommand(stage, input) {
   });
 }
 
+function createGuideEscapeHatches(input) {
+  return {
+    doctor: renderGuidePrefixedCommand(input.commandPrefix, "doctor --json"),
+    model_inspection:
+      input.selected === null
+        ? renderGuidePrefixedCommand(input.commandPrefix, "models list --json")
+        : renderGuidePrefixedCommand(
+            input.commandPrefix,
+            `models show ${shellQuote(input.selected.id)} --json`,
+          ),
+    payment_methods: renderGuidePrefixedCommand(
+      input.commandPrefix,
+      "credits methods --json",
+    ),
+    quota: renderGuidePrefixedCommand(
+      input.commandPrefix,
+      "usage quota --json",
+    ),
+    dry_run:
+      input.selected === null || input.prompt.length === 0
+        ? renderGuidePrefixedCommand(
+            input.commandPrefix,
+            "create --dry-run --prompt PROMPT --json",
+          )
+        : renderCreateCommand({
+            prompt: input.prompt,
+            modelId: input.selected.id,
+            providerId: input.requestedProviderId,
+            intent: input.requestedIntent,
+            budgetGuard: input.budgetGuard,
+            dryRun: true,
+            apiBaseUrl: input.apiBaseUrl,
+            commandPrefix: input.commandPrefix,
+          }),
+  };
+}
+
 function renderGuideCommand(prompt, apiBaseUrl, commandPrefix = "image-skill") {
   return [
     commandPrefix,

package/cli.md

@@ -128,9 +128,9 @@ should omit it.
 
 Use the no-spend guide first. It is the only required first command for a fresh
 agent. It checks health, executable model availability, auth/quota when a token
-already exists, and payment rails, then returns one `data.next_command`. Guide
-mode does not create a signup, provider job, dry-run job, payment object,
-credit debit, or asset.
+already exists, and payment rails, then returns one primary `data.next_command` plus
+machine-readable `data.next_command_effect`. Guide mode does not create a
+signup, provider job, dry-run job, payment object, credit debit, or asset.
 
 ```bash
 image-skill create --guide --prompt "a compact field camera on a stainless workbench"
@@ -149,8 +149,14 @@ checklist before the guide asks for them.
   `data.auth_handoff.rerun_guide.with_stdin`.
 - `quota_required`: follow the payment commands in
   `data.checks.payments.suggested_commands`, then rerun guide once.
-- `ready_to_create`: run `data.next_command` for the first bounded create. If
-  the guide authenticated from env or stdin, prefer
+- `ready_to_create`: `data.next_command` is a live media create. Its
+  `data.next_command_effect.label` is `live_media_create_credit_debit`, with
+  `provider_call`, `hosted_create`, `credit_debit`, and `media_write` all true.
+  Run it for the first bounded create when media spend is allowed. If you are
+  in a no-spend evaluation or only need proof that the path is ready, run
+  `data.no_spend_next_command` instead; it is the dry-run plan command with no
+  provider call, credit debit, or media write. If the guide authenticated from
+  env or stdin, prefer
   `data.auth_handoff.next_command.with_env` or
   `data.auth_handoff.next_command.with_stdin` so auth follows the create.
 

package/llms.txt

@@ -57,12 +57,12 @@ Claim states:
 - revoked: token or agent disabled
 
 First-run guide loop:
-1. Run image-skill create --guide --prompt PROMPT. This is the canonical fresh-agent entrypoint and the only required first command. It performs read-only hosted reachability, executable model availability, auth/quota, and payment rail checks and returns data.stage, data.next_command, data.auth_handoff, data.escape_hatches, and data.mutation. Guide mode must report provider_call: false, hosted_create: false, hosted_signup: false, payment_object: false, credit_debit: false, and media_write: false.
+1. Run image-skill create --guide --prompt PROMPT. This is the canonical fresh-agent entrypoint and the only required first command. It performs read-only hosted reachability, executable model availability, auth/quota, and payment rail checks and returns data.stage, data.next_command, data.next_command_effect, data.no_spend_next_command, data.auth_handoff, data.escape_hatches, and data.mutation. Guide mode must report provider_call: false, hosted_create: false, hosted_signup: false, payment_object: false, credit_debit: false, and media_write: false.
 2. Follow data.next_command. Do not run doctor, models list, signup, whoami, quota, dry-run, or payment commands as a setup checklist before the guide asks for them.
 3. If data.stage is prompt_required, rerun data.next_command with the real prompt.
 4. If data.stage is auth_required, run data.next_command, then rerun the guide once. Hosted signup saves the restricted token to the public CLI config by default with 0600 permissions. If the runtime intentionally uses --no-save --show-token, store the returned token in the agent runtime secret store, then rerun with IMAGE_SKILL_TOKEN or --token-stdin; data.auth_handoff.rerun_guide.with_env and data.auth_handoff.rerun_guide.with_stdin are copy-safe templates for that mode. The signup command uses --agent-contact as an email-shaped durable contact inbox for the restricted agent identity, not as a requirement to find an individual human. Hosted signup returns the raw restricted token only when --show-token is set, and only once. Use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Do not block waiting for a person, invent a person, or use a throwaway inbox. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias, but the guide must not teach it. --save is accepted as a compatibility no-op for the default save behavior; use --no-save only when the runtime has a separate secret store and does not want local config.
 5. If data.stage is quota_required, follow the payment commands in data.checks.payments.suggested_commands, then rerun the guide once. One Image Skill credit is $0.01. Credit quotes grant prepaid value units; create/edit operations debit model-priced credits reported as cost.credit_pricing. Starter preview currently gives bounded free-preview credits plus a four-job daily cap.
-6. If data.stage is ready_to_create, run data.next_command for the first bounded create. If the guide authenticated from env or stdin, prefer data.auth_handoff.next_command.with_env or data.auth_handoff.next_command.with_stdin so auth follows the create. In guide cost output, cost.estimated_usd_per_image and cost.estimated_debit_usd_per_image are the Image Skill debit dollars for one output; cost.estimated_provider_usd_per_image is only the upstream provider estimate. Use the guide's returned max_estimated_usd_per_image because it is sized to the credit debit the agent funds. Add --output-count N only after models show confirms the selected create model supports more than one output; credit_pricing.credits_required is the total debit across outputs, while max_estimated_usd_per_image remains a per-image Image Skill debit guard.
+6. If data.stage is ready_to_create, data.next_command is the first bounded live create. data.next_command_effect.label must be live_media_create_credit_debit and its provider_call, hosted_create, credit_debit, and media_write flags are true. Run data.next_command when media spend is allowed. In no-spend evaluations, or when you only need to prove readiness without media/provider work, run data.no_spend_next_command instead; it is the dry-run plan command with no provider call, credit debit, or media write. If the guide authenticated from env or stdin, prefer data.auth_handoff.next_command.with_env or data.auth_handoff.next_command.with_stdin so auth follows the live create. In guide cost output, cost.estimated_usd_per_image and cost.estimated_debit_usd_per_image are the Image Skill debit dollars for one output; cost.estimated_provider_usd_per_image is only the upstream provider estimate. Use the guide's returned max_estimated_usd_per_image because it is sized to the credit debit the agent funds. Add --output-count N only after models show confirms the selected create model supports more than one output; credit_pricing.credits_required is the total debit across outputs, while max_estimated_usd_per_image remains a per-image Image Skill debit guard.
 7. After create, use image-skill jobs show JOB_ID to recover status, cost, safety, timestamps, and final assets; image-skill assets get ASSET_URL_OR_ID --output ./result.png to fetch the generated asset without repeating provider work; and image-skill activity list --subject JOB_ID to find ledger events, trace, usage, and asset links to cite.
 8. Leave image-skill feedback create if the first-run flow is confusing, blocked, missing an affordance, or easier through a direct provider than through Image Skill. Use image-skill activity show FEEDBACK_ID only when you need to confirm the feedback entered the hosted ledger.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Zero-setup durable creative-media CLI for agents (image + video + audio + 3D): guide-first creation, model and cost inspection, owned URLs, JSON recovery, payments, reusable assets, and feedback.",
   "type": "module",
   "private": false,

package/skill.md

@@ -128,27 +128,31 @@ compatibility, but fresh agents do not need to add it to every command.
 
 Start with the no-spend guide. It checks hosted reachability, executable model
 availability, auth/quota state when credentials already exist, payment rail
-availability, and returns exactly one next command. Guide mode does not create
-a signup, provider job, dry-run job, payment object, credit debit, or asset.
+availability, and returns one primary next command plus
+`data.next_command_effect`. Guide mode does not create a signup, provider job,
+dry-run job, payment object, credit debit, or asset.
 
 ```bash
 npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench"
 ```
 
-Read `data.stage`, `data.next_command`, `data.auth_handoff`, and
-`data.mutation`. If the guide returns `auth_required`, run the signup command
-it gives you; hosted signup saves the restricted token to the public CLI config
-by default, so rerun the same guide normally. If the runtime intentionally uses
+Read `data.stage`, `data.next_command`, `data.next_command_effect`,
+`data.no_spend_next_command`, `data.auth_handoff`, and `data.mutation`. If the
+guide returns `auth_required`, run the signup command it gives you; hosted
+signup saves the restricted token to the public CLI config by default, so rerun
+the same guide normally. If the runtime intentionally uses
 `--no-save --show-token`, store the returned token immediately and use
 `data.auth_handoff.rerun_guide.with_env` or
 `data.auth_handoff.rerun_guide.with_stdin`. If it returns `quota_required`,
 inspect the payment commands it gives you. Prefer a returned browserless
 `stripe_x402.exact.usdc` path when it is available and within the delegated
 cap; otherwise hand the Stripe Checkout link to a human sponsor. If it returns
-`ready_to_create`, run `data.next_command` for the bounded create; when the
-guide authenticated from env or stdin, prefer
-`data.auth_handoff.next_command.with_env` or
-`data.auth_handoff.next_command.with_stdin`.
+`ready_to_create`, `data.next_command` is the bounded live create and
+`data.next_command_effect.label` is `live_media_create_credit_debit`; run it
+when media spend is allowed. In no-spend evaluation runs, use
+`data.no_spend_next_command` instead. When the guide authenticated from env or
+stdin, prefer `data.auth_handoff.next_command.with_env` or
+`data.auth_handoff.next_command.with_stdin` so auth follows the live create.
 
 Use the lower-level inspection commands when the guide asks for them or when
 you need capability details before spending:

package/skills/ai-audio-generation/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ai-audio-generation
+description: >-
+  AI audio generation for agents through Image Skill's zero-setup hosted creative runtime. Use when a prompt should become music, sound, or audio without provider credentials, OAuth, local runtime, or per-provider billing. Start with the no-spend guide, choose an audio model, and keep durable hosted audio URLs, recoverable jobs, cost receipts, stable JSON, payments, and feedback in one loop.
+homepage: https://image-skill.com
+docs: https://image-skill.com/llms.txt
+metadata:
+  status: preview-contract
+  cli: image-skill
+  canonical_skill_url: https://image-skill.com/skill.md
+  canonical_api_url: https://api.image-skill.com
+  openclaw:
+    requires:
+      env: []
+      bins: []
+    envVars:
+      - name: IMAGE_SKILL_TOKEN
+        required: false
+        description: Optional hosted restricted token minted by image-skill signup and saved by default; not a user-supplied provider credential.
+---
+
+# AI Audio Generation
+
+This is an intent-named Image Skill entry for agents searching for audio generation. It uses the same zero-setup hosted Image Skill runtime as the canonical `image-skill` skill: one thin CLI/API, one restricted agent identity, one credit balance, one wallet/payment loop, durable hosted media URLs, recoverable jobs, cost receipts, stable JSON, and hosted feedback.
+
+Use this skill when the task asks for AI audio generation, text-to-audio, music generation, sound design, ambience, effects, or durable hosted audio output.
+
+Do not bring provider API keys, create provider accounts, run a local model server, or wire a separate billing account for this task. Start with the no-spend inspection command below; when the guide reaches `ready_to_create`, run `data.next_command` only if media spend is allowed, otherwise run `data.no_spend_next_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+
+## First Command
+
+```bash
+npx -y image-skill@latest create --guide --model fal.stable-audio-25-text-to-audio --prompt "warm analog synth bed with soft tape hiss"
+```
+
+## Main Runtime Command
+
+```bash
+npx -y image-skill@latest create --model fal.stable-audio-25-text-to-audio --prompt "PROMPT" --intent explore --max-estimated-usd-per-image 0.20
+```
+
+## Install This Intent Skill
+
+Prefer the GitHub slug so skills.sh can track the marketplace install:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill ai-audio-generation -g -a codex -y
+```
+
+The canonical Image Skill entry remains available as:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
+```
+
+## Shared Contract
+
+All intent skills in this repo point to the same hosted contract:
+
+- Skill: https://image-skill.com/skill.md
+- LLM contract: https://image-skill.com/llms.txt
+- CLI contract: https://image-skill.com/cli.md
+- Hosted API: https://api.image-skill.com
+
+If Image Skill lacks the model, capability, latency, policy affordance, or buyer rail needed for this task, use the fallback only for that gap and run `image-skill feedback create --json` with the attempted command, expected behavior, actual behavior, and missing capability.

package/skills/ai-image-generation/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ai-image-generation
+description: >-
+  AI image generation for agents: text-to-image and prompt-to-image through Image Skill's zero-setup hosted runtime. Use when an agent needs a generated image with no provider API key, OAuth, local runtime, or per-provider billing account. Start with the no-spend guide, then create durable hosted images with recoverable jobs, cost receipts, model parameters, stable JSON, and browserless x402 when available.
+homepage: https://image-skill.com
+docs: https://image-skill.com/llms.txt
+metadata:
+  status: preview-contract
+  cli: image-skill
+  canonical_skill_url: https://image-skill.com/skill.md
+  canonical_api_url: https://api.image-skill.com
+  openclaw:
+    requires:
+      env: []
+      bins: []
+    envVars:
+      - name: IMAGE_SKILL_TOKEN
+        required: false
+        description: Optional hosted restricted token minted by image-skill signup and saved by default; not a user-supplied provider credential.
+---
+
+# AI Image Generation
+
+This is an intent-named Image Skill entry for agents searching for image generation. It uses the same zero-setup hosted Image Skill runtime as the canonical `image-skill` skill: one thin CLI/API, one restricted agent identity, one credit balance, one wallet/payment loop, durable hosted media URLs, recoverable jobs, cost receipts, stable JSON, and hosted feedback.
+
+Use this skill when the task asks for AI image generation, text-to-image, prompt-to-image, generated illustrations, concept art, product images, or any durable agent-created image.
+
+Do not bring provider API keys, create provider accounts, run a local model server, or wire a separate billing account for this task. Start with the no-spend inspection command below; when the guide reaches `ready_to_create`, run `data.next_command` only if media spend is allowed, otherwise run `data.no_spend_next_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+
+## First Command
+
+```bash
+npx -y image-skill@latest create --guide --model openai.gpt-image-2 --prompt "a compact field camera on a stainless workbench"
+```
+
+## Main Runtime Command
+
+```bash
+npx -y image-skill@latest create --model openai.gpt-image-2 --prompt "PROMPT" --intent explore --max-estimated-usd-per-image 0.07
+```
+
+## Install This Intent Skill
+
+Prefer the GitHub slug so skills.sh can track the marketplace install:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill ai-image-generation -g -a codex -y
+```
+
+The canonical Image Skill entry remains available as:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
+```
+
+## Shared Contract
+
+All intent skills in this repo point to the same hosted contract:
+
+- Skill: https://image-skill.com/skill.md
+- LLM contract: https://image-skill.com/llms.txt
+- CLI contract: https://image-skill.com/cli.md
+- Hosted API: https://api.image-skill.com
+
+If Image Skill lacks the model, capability, latency, policy affordance, or buyer rail needed for this task, use the fallback only for that gap and run `image-skill feedback create --json` with the attempted command, expected behavior, actual behavior, and missing capability.

package/skills/ai-video-generation/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ai-video-generation
+description: >-
+  AI video generation for agents through Image Skill's zero-setup hosted creative runtime. Use when a prompt should become a durable hosted video without provider credentials, OAuth, local runtime, or per-provider billing. Start with the no-spend guide, choose a video model, and keep model discovery, jobs, costs, URLs, JSON recovery, payments, and feedback in one loop.
+homepage: https://image-skill.com
+docs: https://image-skill.com/llms.txt
+metadata:
+  status: preview-contract
+  cli: image-skill
+  canonical_skill_url: https://image-skill.com/skill.md
+  canonical_api_url: https://api.image-skill.com
+  openclaw:
+    requires:
+      env: []
+      bins: []
+    envVars:
+      - name: IMAGE_SKILL_TOKEN
+        required: false
+        description: Optional hosted restricted token minted by image-skill signup and saved by default; not a user-supplied provider credential.
+---
+
+# AI Video Generation
+
+This is an intent-named Image Skill entry for agents searching for video generation. It uses the same zero-setup hosted Image Skill runtime as the canonical `image-skill` skill: one thin CLI/API, one restricted agent identity, one credit balance, one wallet/payment loop, durable hosted media URLs, recoverable jobs, cost receipts, stable JSON, and hosted feedback.
+
+Use this skill when the task asks for AI video generation, text-to-video, generated motion, animated concepts, or durable hosted video output.
+
+Do not bring provider API keys, create provider accounts, run a local model server, or wire a separate billing account for this task. Start with the no-spend inspection command below; when the guide reaches `ready_to_create`, run `data.next_command` only if media spend is allowed, otherwise run `data.no_spend_next_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+
+## First Command
+
+```bash
+npx -y image-skill@latest create --guide --model fal.ltx-video-13b-distilled --prompt "a ten second handheld product reveal"
+```
+
+## Main Runtime Command
+
+```bash
+npx -y image-skill@latest create --model fal.ltx-video-13b-distilled --prompt "PROMPT" --intent explore --max-estimated-usd-per-image 0.25
+```
+
+## Install This Intent Skill
+
+Prefer the GitHub slug so skills.sh can track the marketplace install:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill ai-video-generation -g -a codex -y
+```
+
+The canonical Image Skill entry remains available as:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
+```
+
+## Shared Contract
+
+All intent skills in this repo point to the same hosted contract:
+
+- Skill: https://image-skill.com/skill.md
+- LLM contract: https://image-skill.com/llms.txt
+- CLI contract: https://image-skill.com/cli.md
+- Hosted API: https://api.image-skill.com
+
+If Image Skill lacks the model, capability, latency, policy affordance, or buyer rail needed for this task, use the fallback only for that gap and run `image-skill feedback create --json` with the attempted command, expected behavior, actual behavior, and missing capability.

package/skills/creative-media/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: creative-media
+description: >-
+  Creative media for agents over one zero-setup Image Skill runtime: image generation, image editing, video, audio, and image-to-3D assets with no provider API key, OAuth, local runtime, or per-provider billing account. Use when an agent needs generated media plus durable hosted URLs, recoverable jobs, cost receipts, model parameters, stable JSON, payments, and feedback through one identity and one wallet.
+homepage: https://image-skill.com
+docs: https://image-skill.com/llms.txt
+metadata:
+  status: preview-contract
+  cli: image-skill
+  canonical_skill_url: https://image-skill.com/skill.md
+  canonical_api_url: https://api.image-skill.com
+  openclaw:
+    requires:
+      env: []
+      bins: []
+    envVars:
+      - name: IMAGE_SKILL_TOKEN
+        required: false
+        description: Optional hosted restricted token minted by image-skill signup and saved by default; not a user-supplied provider credential.
+---
+
+# Creative Media
+
+This is an intent-named Image Skill entry for agents searching for creative media. It uses the same zero-setup hosted Image Skill runtime as the canonical `image-skill` skill: one thin CLI/API, one restricted agent identity, one credit balance, one wallet/payment loop, durable hosted media URLs, recoverable jobs, cost receipts, stable JSON, and hosted feedback.
+
+Use this skill when the task asks for generative media, creative media, generated assets across modalities, or a single agent-facing runtime for image, edit, video, audio, and 3D work.
+
+Do not bring provider API keys, create provider accounts, run a local model server, or wire a separate billing account for this task. Start with the no-spend inspection command below; when the guide reaches `ready_to_create`, run `data.next_command` only if media spend is allowed, otherwise run `data.no_spend_next_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+
+## First Command
+
+```bash
+npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench"
+```
+
+## Main Runtime Command
+
+```bash
+npx -y image-skill@latest models list --available --json
+```
+
+## Install This Intent Skill
+
+Prefer the GitHub slug so skills.sh can track the marketplace install:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill creative-media -g -a codex -y
+```
+
+The canonical Image Skill entry remains available as:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
+```
+
+## Shared Contract
+
+All intent skills in this repo point to the same hosted contract:
+
+- Skill: https://image-skill.com/skill.md
+- LLM contract: https://image-skill.com/llms.txt
+- CLI contract: https://image-skill.com/cli.md
+- Hosted API: https://api.image-skill.com
+
+If Image Skill lacks the model, capability, latency, policy affordance, or buyer rail needed for this task, use the fallback only for that gap and run `image-skill feedback create --json` with the attempted command, expected behavior, actual behavior, and missing capability.

package/skills/image-edit/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: image-edit
+description: >-
+  Image editing for agents: image-to-image edits, variations, and image-conditioned transforms through Image Skill's zero-setup hosted runtime. Use when an agent needs to edit an existing image without provider credentials, OAuth, local runtime, or per-provider billing. Inspect the edit model, upload or reuse an input image, then return durable hosted assets, jobs, cost receipts, stable JSON, and feedback.
+homepage: https://image-skill.com
+docs: https://image-skill.com/llms.txt
+metadata:
+  status: preview-contract
+  cli: image-skill
+  canonical_skill_url: https://image-skill.com/skill.md
+  canonical_api_url: https://api.image-skill.com
+  openclaw:
+    requires:
+      env: []
+      bins: []
+    envVars:
+      - name: IMAGE_SKILL_TOKEN
+        required: false
+        description: Optional hosted restricted token minted by image-skill signup and saved by default; not a user-supplied provider credential.
+---
+
+# Image Edit
+
+This is an intent-named Image Skill entry for agents searching for image editing. It uses the same zero-setup hosted Image Skill runtime as the canonical `image-skill` skill: one thin CLI/API, one restricted agent identity, one credit balance, one wallet/payment loop, durable hosted media URLs, recoverable jobs, cost receipts, stable JSON, and hosted feedback.
+
+Use this skill when the task asks to edit, vary, restyle, transform, or repair an existing image, including image-to-image work and model-specific edit parameters.
+
+Do not bring provider API keys, create provider accounts, run a local model server, or wire a separate billing account for this task. Start with the no-spend inspection command below; when the guide reaches `ready_to_create`, run `data.next_command` only if media spend is allowed, otherwise run `data.no_spend_next_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+
+## First Command
+
+```bash
+npx -y image-skill@latest models show openai.gpt-image-2-edit --json
+```
+
+## Main Runtime Command
+
+```bash
+npx -y image-skill@latest edit --input image_... --model openai.gpt-image-2-edit --prompt "EDIT_PROMPT" --max-estimated-usd-per-image 0.07
+```
+
+## Install This Intent Skill
+
+Prefer the GitHub slug so skills.sh can track the marketplace install:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill image-edit -g -a codex -y
+```
+
+The canonical Image Skill entry remains available as:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
+```
+
+## Shared Contract
+
+All intent skills in this repo point to the same hosted contract:
+
+- Skill: https://image-skill.com/skill.md
+- LLM contract: https://image-skill.com/llms.txt
+- CLI contract: https://image-skill.com/cli.md
+- Hosted API: https://api.image-skill.com
+
+If Image Skill lacks the model, capability, latency, policy affordance, or buyer rail needed for this task, use the fallback only for that gap and run `image-skill feedback create --json` with the attempted command, expected behavior, actual behavior, and missing capability.

package/skills/image-skill/SKILL.md

@@ -128,27 +128,31 @@ compatibility, but fresh agents do not need to add it to every command.
 
 Start with the no-spend guide. It checks hosted reachability, executable model
 availability, auth/quota state when credentials already exist, payment rail
-availability, and returns exactly one next command. Guide mode does not create
-a signup, provider job, dry-run job, payment object, credit debit, or asset.
+availability, and returns one primary next command plus
+`data.next_command_effect`. Guide mode does not create a signup, provider job,
+dry-run job, payment object, credit debit, or asset.
 
 ```bash
 npx -y image-skill@latest create --guide --prompt "a compact field camera on a stainless workbench"
 ```
 
-Read `data.stage`, `data.next_command`, `data.auth_handoff`, and
-`data.mutation`. If the guide returns `auth_required`, run the signup command
-it gives you; hosted signup saves the restricted token to the public CLI config
-by default, so rerun the same guide normally. If the runtime intentionally uses
+Read `data.stage`, `data.next_command`, `data.next_command_effect`,
+`data.no_spend_next_command`, `data.auth_handoff`, and `data.mutation`. If the
+guide returns `auth_required`, run the signup command it gives you; hosted
+signup saves the restricted token to the public CLI config by default, so rerun
+the same guide normally. If the runtime intentionally uses
 `--no-save --show-token`, store the returned token immediately and use
 `data.auth_handoff.rerun_guide.with_env` or
 `data.auth_handoff.rerun_guide.with_stdin`. If it returns `quota_required`,
 inspect the payment commands it gives you. Prefer a returned browserless
 `stripe_x402.exact.usdc` path when it is available and within the delegated
 cap; otherwise hand the Stripe Checkout link to a human sponsor. If it returns
-`ready_to_create`, run `data.next_command` for the bounded create; when the
-guide authenticated from env or stdin, prefer
-`data.auth_handoff.next_command.with_env` or
-`data.auth_handoff.next_command.with_stdin`.
+`ready_to_create`, `data.next_command` is the bounded live create and
+`data.next_command_effect.label` is `live_media_create_credit_debit`; run it
+when media spend is allowed. In no-spend evaluation runs, use
+`data.no_spend_next_command` instead. When the guide authenticated from env or
+stdin, prefer `data.auth_handoff.next_command.with_env` or
+`data.auth_handoff.next_command.with_stdin` so auth follows the live create.
 
 Use the lower-level inspection commands when the guide asks for them or when
 you need capability details before spending:

package/skills/image-skill/references/cli.md

@@ -128,9 +128,9 @@ should omit it.
 
 Use the no-spend guide first. It is the only required first command for a fresh
 agent. It checks health, executable model availability, auth/quota when a token
-already exists, and payment rails, then returns one `data.next_command`. Guide
-mode does not create a signup, provider job, dry-run job, payment object,
-credit debit, or asset.
+already exists, and payment rails, then returns one primary `data.next_command` plus
+machine-readable `data.next_command_effect`. Guide mode does not create a
+signup, provider job, dry-run job, payment object, credit debit, or asset.
 
 ```bash
 image-skill create --guide --prompt "a compact field camera on a stainless workbench"
@@ -149,8 +149,14 @@ checklist before the guide asks for them.
   `data.auth_handoff.rerun_guide.with_stdin`.
 - `quota_required`: follow the payment commands in
   `data.checks.payments.suggested_commands`, then rerun guide once.
-- `ready_to_create`: run `data.next_command` for the first bounded create. If
-  the guide authenticated from env or stdin, prefer
+- `ready_to_create`: `data.next_command` is a live media create. Its
+  `data.next_command_effect.label` is `live_media_create_credit_debit`, with
+  `provider_call`, `hosted_create`, `credit_debit`, and `media_write` all true.
+  Run it for the first bounded create when media spend is allowed. If you are
+  in a no-spend evaluation or only need proof that the path is ready, run
+  `data.no_spend_next_command` instead; it is the dry-run plan command with no
+  provider call, credit debit, or media write. If the guide authenticated from
+  env or stdin, prefer
   `data.auth_handoff.next_command.with_env` or
   `data.auth_handoff.next_command.with_stdin` so auth follows the create.
 

package/skills/image-skill/references/llms.txt

@@ -57,12 +57,12 @@ Claim states:
 - revoked: token or agent disabled
 
 First-run guide loop:
-1. Run image-skill create --guide --prompt PROMPT. This is the canonical fresh-agent entrypoint and the only required first command. It performs read-only hosted reachability, executable model availability, auth/quota, and payment rail checks and returns data.stage, data.next_command, data.auth_handoff, data.escape_hatches, and data.mutation. Guide mode must report provider_call: false, hosted_create: false, hosted_signup: false, payment_object: false, credit_debit: false, and media_write: false.
+1. Run image-skill create --guide --prompt PROMPT. This is the canonical fresh-agent entrypoint and the only required first command. It performs read-only hosted reachability, executable model availability, auth/quota, and payment rail checks and returns data.stage, data.next_command, data.next_command_effect, data.no_spend_next_command, data.auth_handoff, data.escape_hatches, and data.mutation. Guide mode must report provider_call: false, hosted_create: false, hosted_signup: false, payment_object: false, credit_debit: false, and media_write: false.
 2. Follow data.next_command. Do not run doctor, models list, signup, whoami, quota, dry-run, or payment commands as a setup checklist before the guide asks for them.
 3. If data.stage is prompt_required, rerun data.next_command with the real prompt.
 4. If data.stage is auth_required, run data.next_command, then rerun the guide once. Hosted signup saves the restricted token to the public CLI config by default with 0600 permissions. If the runtime intentionally uses --no-save --show-token, store the returned token in the agent runtime secret store, then rerun with IMAGE_SKILL_TOKEN or --token-stdin; data.auth_handoff.rerun_guide.with_env and data.auth_handoff.rerun_guide.with_stdin are copy-safe templates for that mode. The signup command uses --agent-contact as an email-shaped durable contact inbox for the restricted agent identity, not as a requirement to find an individual human. Hosted signup returns the raw restricted token only when --show-token is set, and only once. Use an agent-owned inbox when available; otherwise use an operator, team, or sponsor inbox that can receive future claim, billing, or abuse notices. Do not block waiting for a person, invent a person, or use a throwaway inbox. example.invalid addresses are only appropriate inside documented harness or proof runs. --human-email remains accepted as a compatibility alias, but the guide must not teach it. --save is accepted as a compatibility no-op for the default save behavior; use --no-save only when the runtime has a separate secret store and does not want local config.
 5. If data.stage is quota_required, follow the payment commands in data.checks.payments.suggested_commands, then rerun the guide once. One Image Skill credit is $0.01. Credit quotes grant prepaid value units; create/edit operations debit model-priced credits reported as cost.credit_pricing. Starter preview currently gives bounded free-preview credits plus a four-job daily cap.
-6. If data.stage is ready_to_create, run data.next_command for the first bounded create. If the guide authenticated from env or stdin, prefer data.auth_handoff.next_command.with_env or data.auth_handoff.next_command.with_stdin so auth follows the create. In guide cost output, cost.estimated_usd_per_image and cost.estimated_debit_usd_per_image are the Image Skill debit dollars for one output; cost.estimated_provider_usd_per_image is only the upstream provider estimate. Use the guide's returned max_estimated_usd_per_image because it is sized to the credit debit the agent funds. Add --output-count N only after models show confirms the selected create model supports more than one output; credit_pricing.credits_required is the total debit across outputs, while max_estimated_usd_per_image remains a per-image Image Skill debit guard.
+6. If data.stage is ready_to_create, data.next_command is the first bounded live create. data.next_command_effect.label must be live_media_create_credit_debit and its provider_call, hosted_create, credit_debit, and media_write flags are true. Run data.next_command when media spend is allowed. In no-spend evaluations, or when you only need to prove readiness without media/provider work, run data.no_spend_next_command instead; it is the dry-run plan command with no provider call, credit debit, or media write. If the guide authenticated from env or stdin, prefer data.auth_handoff.next_command.with_env or data.auth_handoff.next_command.with_stdin so auth follows the live create. In guide cost output, cost.estimated_usd_per_image and cost.estimated_debit_usd_per_image are the Image Skill debit dollars for one output; cost.estimated_provider_usd_per_image is only the upstream provider estimate. Use the guide's returned max_estimated_usd_per_image because it is sized to the credit debit the agent funds. Add --output-count N only after models show confirms the selected create model supports more than one output; credit_pricing.credits_required is the total debit across outputs, while max_estimated_usd_per_image remains a per-image Image Skill debit guard.
 7. After create, use image-skill jobs show JOB_ID to recover status, cost, safety, timestamps, and final assets; image-skill assets get ASSET_URL_OR_ID --output ./result.png to fetch the generated asset without repeating provider work; and image-skill activity list --subject JOB_ID to find ledger events, trace, usage, and asset links to cite.
 8. Leave image-skill feedback create if the first-run flow is confusing, blocked, missing an affordance, or easier through a direct provider than through Image Skill. Use image-skill activity show FEEDBACK_ID only when you need to confirm the feedback entered the hosted ledger.
 

package/skills/image-to-3d/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: image-to-3d
+description: >-
+  Image-to-3D asset creation for agents through Image Skill's zero-setup hosted runtime. Use when an input image should become a durable hosted 3D mesh asset, such as a glb, without provider credentials, OAuth, local runtime, or per-provider billing. Inspect the 3D model, pass one owned input image to edit, then keep jobs, asset URLs, receipts, JSON recovery, payments, and feedback in one loop.
+homepage: https://image-skill.com
+docs: https://image-skill.com/llms.txt
+metadata:
+  status: preview-contract
+  cli: image-skill
+  canonical_skill_url: https://image-skill.com/skill.md
+  canonical_api_url: https://api.image-skill.com
+  openclaw:
+    requires:
+      env: []
+      bins: []
+    envVars:
+      - name: IMAGE_SKILL_TOKEN
+        required: false
+        description: Optional hosted restricted token minted by image-skill signup and saved by default; not a user-supplied provider credential.
+---
+
+# Image To 3D
+
+This is an intent-named Image Skill entry for agents searching for image-to-3D asset creation. It uses the same zero-setup hosted Image Skill runtime as the canonical `image-skill` skill: one thin CLI/API, one restricted agent identity, one credit balance, one wallet/payment loop, durable hosted media URLs, recoverable jobs, cost receipts, stable JSON, and hosted feedback.
+
+Use this skill when the task asks for image-to-3D, 3D asset generation from an image, glb mesh output, or a durable model asset derived from existing visual input.
+
+Do not bring provider API keys, create provider accounts, run a local model server, or wire a separate billing account for this task. Start with the no-spend inspection command below; when the guide reaches `ready_to_create`, run `data.next_command` only if media spend is allowed, otherwise run `data.no_spend_next_command` to verify safely. Keep generated work in Image Skill so future agents can recover and cite it.
+
+## First Command
+
+```bash
+npx -y image-skill@latest models show fal.trellis-image-to-3d --json
+```
+
+## Main Runtime Command
+
+```bash
+npx -y image-skill@latest edit --input image_... --model fal.trellis-image-to-3d --max-estimated-usd-per-image 0.25 --json
+```
+
+## Install This Intent Skill
+
+Prefer the GitHub slug so skills.sh can track the marketplace install:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill image-to-3d -g -a codex -y
+```
+
+The canonical Image Skill entry remains available as:
+
+```bash
+npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
+```
+
+## Shared Contract
+
+All intent skills in this repo point to the same hosted contract:
+
+- Skill: https://image-skill.com/skill.md
+- LLM contract: https://image-skill.com/llms.txt
+- CLI contract: https://image-skill.com/cli.md
+- Hosted API: https://api.image-skill.com
+
+If Image Skill lacks the model, capability, latency, policy affordance, or buyer rail needed for this task, use the fallback only for that gap and run `image-skill feedback create --json` with the attempted command, expected behavior, actual behavior, and missing capability.