Merge pull request #6 from replicate/zeke/split-into-four-skills

docs: split monolithic skill into five focused skills

Author: zeke

.claude-plugin/marketplace.json

@@ -7,9 +7,29 @@
   },
   "plugins": [
     {
-      "name": "replicate",
-      "source": "./",
-      "description": "Skills for building AI-powered apps with Replicate"
+      "name": "find-models",
+      "source": "skills/find-models",
+      "description": "Find AI models on Replicate using search and curated collections."
+    },
+    {
+      "name": "compare-models",
+      "source": "skills/compare-models",
+      "description": "Compare Replicate models by cost, speed, quality, and capabilities."
+    },
+    {
+      "name": "run-models",
+      "source": "skills/run-models",
+      "description": "Run AI models on Replicate via predictions, webhooks, and streaming."
+    },
+    {
+      "name": "prompt-images",
+      "source": "skills/prompt-images",
+      "description": "Prompting techniques for AI image generation and editing models on Replicate."
+    },
+    {
+      "name": "prompt-videos",
+      "source": "skills/prompt-videos",
+      "description": "Prompting techniques for AI video generation models on Replicate."
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "replicate",
-  "description": "Skills for building AI-powered apps with Replicate",
-  "version": "1.0.0",
+  "description": "Skills for finding, comparing, running, and prompting AI models on Replicate",
+  "version": "2.0.0",
   "author": {
     "name": "Replicate"
   }

.github/workflows/ci.yml

@@ -33,4 +33,8 @@ jobs:
           CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
         run: |
           npx clawhub@latest login --token "$CLAWHUB_TOKEN"
-          npx clawhub@latest publish skills/replicate --slug replicate --name "Replicate"
+          npx clawhub@latest publish skills/find-models --slug replicate-find-models --name "Replicate: Find Models"
+          npx clawhub@latest publish skills/compare-models --slug replicate-compare-models --name "Replicate: Compare Models"
+          npx clawhub@latest publish skills/run-models --slug replicate-run-models --name "Replicate: Run Models"
+          npx clawhub@latest publish skills/prompt-images --slug replicate-prompt-images --name "Replicate: Prompt Images"
+          npx clawhub@latest publish skills/prompt-videos --slug replicate-prompt-videos --name "Replicate: Prompt Videos"

AGENTS.md

@@ -2,27 +2,32 @@
 
 ## Purpose
 
-This repo publishes a single Agent Skills document for Replicate.
-
-Keep it short and focused: a human- and agent-readable guide to discovering models, inspecting schemas, running predictions, and handling outputs.
+This repo publishes Agent Skills for Replicate: focused guides for finding, comparing, running, and prompting AI models.
 
 ## Files that matter
 
-- `skills/replicate/SKILL.md` is the canonical skill.
-- `.mcp.json` points to the remote MCP server.
-- `.claude-plugin/` contains marketplace metadata for Claude Code.
+- `skills/find-models/SKILL.md` — search, collections, schemas, picking the right model.
+- `skills/compare-models/SKILL.md` — evaluating models by cost, speed, quality, and capabilities.
+- `skills/run-models/SKILL.md` — predictions, polling, webhooks, streaming, file I/O, concurrency, multi-model workflows.
+- `skills/prompt-images/SKILL.md` — prompting techniques for image generation and editing models.
+- `skills/prompt-videos/SKILL.md` — prompting techniques for video generation models.
+- `script/lint` — validates the skills.
+- `.mcp.json` — points to the remote MCP server.
+- `.claude-plugin/` — marketplace metadata for Claude Code.
 
 ## Editing guidelines
 
-- Keep `SKILL.md` concise and practical. Prefer bullet lists over long prose.
-- Treat `https://api.replicate.com/openapi.json` as the source of truth.
-- Keep mentions of deprecated or unofficial endpoints out of the skill.
+- Keep each `SKILL.md` concise and practical. Prefer bullet lists over long prose.
+- Every code snippet must be runnable. The test runner executes them all.
+- Treat `https://api.replicate.com/openapi.json` as the source of truth for API details.
 - Do not add language-specific client guidance unless explicitly requested.
 
 ## Linting
 
-Lint before committing changes:
-
 ```
-script/lint
+script/lint skills/find-models
+script/lint skills/compare-models
+script/lint skills/run-models
+script/lint skills/prompt-images
+script/lint skills/prompt-videos
 ```

README.md

@@ -1,9 +1,13 @@
 # Replicate Skills
 
+A collection of [Agent Skills](https://agentskills.io) for building AI-powered apps with [Replicate](https://replicate.com).
 
-A collection of [Agent Skills](https://agentskills.io) for building AI-powered apps with [Replicate](https://replicate.com). 
+Skills included:
 
-Discover, compare, and run AI models using Replicate's API.
+- **find-models** — search for models, browse collections, read schemas, pick the right model
+- **compare-models** — evaluate models by cost, speed, quality, and capabilities
+- **run-models** — create predictions, poll, use webhooks, stream, handle files, run concurrently
+- **prompt-images** — prompting techniques for image generation and editing models
 
 ## Installing
 

script/lint

@@ -12,23 +12,35 @@ cd "$(dirname "$0")/.."
 
 [ -z "$DEBUG" ] || set -x
 
-SKILL_PATH="${1:-skills/replicate}"
-
-echo "==> Validating Agent Skills in $SKILL_PATH"
-
-if command -v uv >/dev/null 2>&1; then
-  uvx --from skills-ref agentskills validate "$SKILL_PATH"
-  exit 0
+if [ $# -gt 0 ]; then
+  SKILL_PATHS="$*"
+else
+  SKILL_PATHS=""
+  for d in skills/*/; do
+    [ -f "$d/SKILL.md" ] && SKILL_PATHS="$SKILL_PATHS $d"
+  done
 fi
 
-PYTHON_BIN="${PYTHON_BIN:-python3}"
-if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
-  if command -v python >/dev/null 2>&1; then
-    PYTHON_BIN=python
-  else
-    echo "python not found. Install Python 3 or uv to run skills-ref." >&2
-    exit 1
+validate() {
+  if command -v uv >/dev/null 2>&1; then
+    uvx --from skills-ref agentskills validate "$1"
+    return
   fi
-fi
 
-"$PYTHON_BIN" -m skills_ref validate "$SKILL_PATH"
+  PYTHON_BIN="${PYTHON_BIN:-python3}"
+  if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
+    if command -v python >/dev/null 2>&1; then
+      PYTHON_BIN=python
+    else
+      echo "python not found. Install Python 3 or uv to run skills-ref." >&2
+      exit 1
+    fi
+  fi
+
+  "$PYTHON_BIN" -m skills_ref validate "$1"
+}
+
+for SKILL_PATH in $SKILL_PATHS; do
+  echo "==> Validating Agent Skills in $SKILL_PATH"
+  validate "$SKILL_PATH"
+done

skills/compare-models/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: compare-models
+description: Compare Replicate models by cost, speed, quality, and capabilities.
+---
+
+## Docs
+
+- Reference: <https://replicate.com/docs/llms.txt>
+- OpenAPI schema: <https://api.replicate.com/openapi.json>
+- MCP server: <https://mcp.replicate.com>
+- Per-model docs: `https://replicate.com/{owner}/{model}/llms.txt`
+- Set `Accept: text/markdown` when requesting docs pages for Markdown responses.
+
+## Workflow
+
+1. Search or browse collections to build a shortlist of candidate models.
+2. Fetch each model's schema to compare inputs, outputs, and capabilities.
+3. Check pricing from model metadata or the Replicate website.
+4. Run a small batch of test predictions to compare output quality.
+5. Pick the model that best fits your constraints (cost, latency, quality).
+
+## What to compare
+
+- **Speed**: Check `metrics.predict_time` on completed predictions for actual inference time. Official models are always warm. Community models can cold-boot.
+- **Cost**: Official models have predictable per-run pricing. Community models charge by compute time (GPU-seconds). Run a few predictions and check the `metrics` field for actual cost.
+- **Quality**: Run the same prompts through each model and compare outputs. Quality is subjective. Match it to your use case, not a leaderboard.
+- **Capabilities**: Compare input schemas for supported features (reference images, masks, aspect ratios, streaming, multi-image input). Check output formats.
+
+## Key tradeoffs
+
+- Lowest cost: smaller/distilled models. Accept slower inference and lower quality.
+- Lowest latency: official models or schnell/turbo variants. Accept higher cost per run.
+- Highest quality: pro/max/quality variants. Accept slower inference and higher cost.
+- Most control: models with ControlNet, masks, or reference images. Accept more complex input setup.
+
+## Official vs community models
+
+- Official models: always warm, stable APIs, predictable pricing, maintained by Replicate.
+- Community models: may cold-boot, require version pinning, maintained by the author.
+- If a community model meets your needs and an official model doesn't, consider creating a deployment for consistent uptime.
+
+## Prompting guidance
+
+For prompting techniques and task-specific guidance:
+
+- Image generation and editing: see the [prompt-images](../prompt-images/SKILL.md) skill.
+- Video generation: see the [prompt-videos](../prompt-videos/SKILL.md) skill.

skills/find-models/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: find-models
+description: Find AI models on Replicate using search and curated collections.
+---
+
+## Docs
+
+- Reference: <https://replicate.com/docs/llms.txt>
+- OpenAPI schema: <https://api.replicate.com/openapi.json>
+- MCP server: <https://mcp.replicate.com>
+- Per-model docs: `https://replicate.com/{owner}/{model}/llms.txt`
+- Set `Accept: text/markdown` when requesting docs pages for Markdown responses.
+
+## Search
+
+- Use the search API (`GET /v1/search?query=...`) to find models by task. Returns models, collections, and docs.
+- Search returns metadata for each model including `tags`, `generated_description`, and `run_count`.
+- The search API also returns matching collections alongside model results.
+- Avoid listing all models via API. It's a firehose. Use targeted queries.
+
+## Collections
+
+- Collections are curated groups of models maintained by Replicate staff.
+- The `official` collection contains always-warm models with stable APIs and predictable pricing.
+- Use collections to narrow a shortlist before deep comparison.
+- List collections with `GET /v1/collections`. Get one by slug with `GET /v1/collections/{slug}`.
+
+## Reading model schemas
+
+- Every model exposes its input/output schema via the models API (`GET /v1/models/{owner}/{name}`).
+- Schema path: `model.latest_version.openapi_schema.components.schemas.Input.properties`
+- Each property may include: `type`, `description`, `default`, `minimum`/`maximum`, `enum`, `format` (e.g. `uri` for file inputs).
+- Always fetch the schema before running a model. Schemas change.
+
+## Picking the right model
+
+- Prefer official models. They're always warm (no cold boot), have stable APIs, and predictable pricing.
+- Prefer the latest version. If search returns v2.5 and v3.0, use v3.
+- Run count can be misleading. Old models accumulate runs over time but may be outdated. A model with 10M runs from 2023 is likely worse than a model with 100K runs from 2025.
+- Prefer recently released models. The AI space moves fast.
+- Check model tags to help filter by task (`image-generation`, `video`, `audio`, etc.).
+
+## Model identifiers
+
+- **Official models** use `owner/name` format (e.g. `black-forest-labs/flux-2-klein-9b`). Routes to the latest version automatically.
+- **Community models** require `owner/name:version_id`. You must pin a specific version. Community models can cold-boot and take time to start.
+- If you must use a community model, be aware that it can take a long time to boot. You can create always-on deployments, but you pay for model uptime.