README.md

Creative AI Skills for Codex, Claude Code, Cursor, and any Agent Skills-compatible runtime.

WeShop Skills turns plain-language creative requests into production-ready image, video, product, portrait, layout, and spatial workflows powered by WeShop OpenAPI. Install the complete collection or pick only the Skills you need.

This repository contains 137 focused creative Skills + 1 user-authoring Skill. Higher-level selection lives in the protected routing/guide.md package resource, and maintained compositions live in workflows/catalog.json. Neither is installed or exposed as a Skill.

Package boundaries

• skills/ contains the 138 independently discoverable user-facing and authoring Skills.
• routing/ contains protected, host-addressed selection guidance. It is not a Skill, Tool, executor, or second Agent loop.
• workflows/ contains maintained cross-Skill dependency definitions and their execution boundary. Workflows are not Skills.
• shared/ contains Package-owned guidance shared by several Skills, such as model selection. Skills link to it only when the current task needs that decision.
• scripts/weshop-skills.mjs installs and updates Skill content; it is not the media-generation CLI.
• A native host Tool or the separately versioned official weshop CLI owns execution. Tool schemas, credentials, approval, receipts, retries, and artifact delivery are not duplicated in this Package.

This keeps routine Skill releases independent from the executable CLI and from any host application's release cycle.

🚀 Install with one prompt

Open Codex, Claude Code, or Cursor and paste this:

Install the latest stable `weshop-skill-package` from npm globally, run `weshop-skills install` for the agent you are running in, verify the managed Skill installation, and tell me whether I need to restart the agent. Do not ask me to paste or print my WeShop API key. Preserve all user-owned custom Skills.

The Agent should use the npm package and install the Skills into its own global Skill directory.

📦 Install manually

1. Download the latest stable package

npm install -g weshop-skill-package@latest
weshop-skills version

Node.js 22 LTS and npm are required. The npm package is public and does not require a GitHub checkout. Its version always matches the corresponding stable GitHub Release.

2. Choose your agent

weshop-skills install --agent codex

weshop-skills install --agent claude

weshop-skills install --agent cursor

Restart the agent after the first installation so it can discover the new Skills.

For another Agent Skills-compatible runtime or a project-local setup, choose the destination explicitly:

weshop-skills install --all --target /absolute/path/to/skills

Use weshop-skills list to inspect the package or install one Skill by name instead of the full collection.

3. Check for and install updates

Compare the version installed on your machine with the latest version published to npm:

weshop-skills version
npm view weshop-skill-package version

You can also use npm's outdated report. It prints nothing when the global package is current:

npm outdated -g weshop-skill-package

Every stable GitHub Release publishes the same version to npm. Upgrade explicitly to the current latest version, then synchronize managed installations:

npm install -g weshop-skill-package@latest
weshop-skills sync --all
weshop-skills status --all

By default, managed installations are symlinks. Existing symlinked Skills follow the upgraded npm package immediately, while sync --all also installs newly added official Skills. Copy installations are refreshed only by sync. Restart the Agent after an update when it caches Skill metadata.

Package updates never scan, modify, upload, or delete user-owned custom Skills. Custom drafts remain under ~/.weshop-skill-package/custom-skills/, and user-installed custom Skills remain owned by the user.

To follow future releases without running a command, use GitHub Releases, subscribe through the repository's Watch → Custom → Releases option, or follow the release Atom feed.

By default, installation uses symlinks. Add --copy if you need an isolated copy:

weshop-skills install --agent codex --copy

4. Configure WeShop OpenAPI

Get a key from WeShop OpenAPI, then provide it only to the trusted local process that performs generation:

read -s WESHOP_API_KEY && export WESHOP_API_KEY
weshop-skills api-key check

Never paste the key into chat, source files, frontend code, Git history, URLs, or command arguments.

💬 Use it

You do not need to memorize Skill names. Compatible hosts expose a category-grouped registry, use the protected routing guide only when the owner is not obvious, and load the selected Skill on demand. Only real cross-Skill dependencies or independently valuable deliverables enter a maintained workflow definition.

Try prompts like:

Turn this product photo into a clean white-background marketplace hero image. Keep the product shape, label, and colors unchanged.

Put this jacket on the model, preserve the garment logo and fit, then create a matching lifestyle campaign image.

Remove the person in the background, expand this photo to 16:9, and animate it into a five-second cinematic shot.

Create one minimal logo for NORTHLINE COFFEE: an original N plus mountain-path symbol in black and cream.

You can also invoke a Skill directly, for example $remove-background, $virtual-try-on, $create-logo, or $generate-video.

Create your own Skill

Ask for a reusable user-owned Skill in plain language. $create-custom-skill owns the complete local lifecycle: it creates or revises an isolated draft, checks structure and routing boundaries, and installs it locally after validation. The create, save, import, or upload request itself authorizes that local installation; only conflicts or higher-risk side effects stop for separate permission. Independent review begins only if you later ask to contribute the Skill to the official package.

Save the workflow we just completed as my own reusable Skill. Keep it local, compare it with similar installed Skills, run intake and validation, then install it into my local Skill directory.

Drafts default to ~/.weshop-skill-package/custom-skills/ and are not visible to the Agent until intake and validation pass. They remain user-owned and are not overwritten by package updates. Deterministic scaffolding and mechanical review are also available:

weshop-skills custom init my-custom-skill
weshop-skills custom check ~/.weshop-skill-package/custom-skills/my-custom-skill

✨ What you get

For compound work, the Host reads one definition from workflows/catalog.json, connects accepted outputs to downstream inputs, and lets each selected Skill own its operation. The Host Runtime remains responsible for tools, approval, authentication, receipts, recovery, and publication.

Routing guidance

routing/guide.md is a protected package resource, not a Skill or plan compiler. When routing is needed, the Agent reads it once and selects:

• one complete-outcome Skill;
• one maintained workflow for real cross-Skill dependencies or independently requested deliverables; or
• one route-changing clarification.

Its bounded common-task map accelerates frequent work without becoming a keyword classifier or closed operation enum. workflows/catalog.json is the machine-readable authority for the maintained compositions. Runtime Skill availability remains authoritative.

The routing guide considers only outcome, supplied input roles, preservation constraints, requested deliverables, current-evidence needs, and route-changing ambiguity. Host policy, memory, permissions, execution state, receipts, and recovery remain owned by the Agent Runtime. There is no Router Tool roundtrip or second Agent loop.

Complete Skill inventory 🧩

The skills/ directory contains 137 creative Skills and one platform-tooling Skill—138 Skills in total. Routing and workflow resources are deliberately outside this directory, so ordinary Agent Skills discovery cannot expose or shadow them. Categories below are for browsing only.

Client catalog contract

Published packages include catalog/skills.json, a versioned, client-neutral catalog generated from the installed SKILL.md files. Its 138 public entries cover the 137 Atom Skills and the user-authoring Skill; the two system-only routing Skills are intentionally hidden from the client catalog. It provides each public Skill's cover reference, category and tags, description, usage summary and examples, plus up to three differentiated related Skills. Clients may use it for presentation, but must continue to discover and execute Skills from SKILL.md: the catalog is optional so individually copied Skills, older package versions, and third-party/custom directories remain compatible.

List them from your terminal:

weshop-skills list

Install only what you need:

weshop-skills install create-logo --agent codex

⌨️ Official WeShop CLI

Execution uses a native WeShop tool exposed by the agent when available. Otherwise it uses only the official weshop CLI. Install and verify it separately:

npm install -g weshop-cli
weshop --version
weshop --help

Use its native Agent commands:

weshop gpt-image --help
weshop gpt-image --prompt "Create a clean geometric logo"

The label GPT Image 2 maps to the Agent ID gpt-image, not gpt-image-2. The official CLI does not support list-agents; use weshop --help or weshop info <agent>.

If weshop is absent, stop before upload or generation and install it; this repository intentionally contains no OpenAPI client or execution fallback. An authentication, validation, timeout, or ambiguous submission error is not a signal to change clients or retry the create call.

🔄 Inspect updates

Inspect one managed Skill at any time, or compare the local package version with npm:

weshop-skills status create-logo --agent codex
weshop-skills version
npm view weshop-skill-package version

status checks installed Skill content; it does not query npm. Use the two version commands above to determine whether a new package release exists.

🏗️ For maintainers

Start with CONTRIBUTING.md and the maintainer guide. The repository includes separate workflows for creating a Skill and adapting an external project to WeShop.

Useful commands:

🔒 Security

• WESHOP_API_KEY is read from the environment and sent only to https://openapi.weshop.ai.
• Every generation uses a durable operation key before submission.
• A missing or ambiguous execution receipt blocks automatic resubmission to avoid duplicate output and spend.
• Accepted runs are polled by execution ID; downstream download or publication failures do not trigger regeneration.

📄 License

Available under the MIT License.

Built with ❤️ by the WeShop AI team.