feat: introduce Skill for working with the CLI

README.md

@@ -1,11 +1,13 @@
 <img src="https://github.com/Shopify/cli/blob/main/assets/logo.png?raw=true" width="150"/>
 
 # Shopify CLI
+
 <a href="http://twitter.com/ShopifyDevs"><img src="https://img.shields.io/twitter/follow/ShopifyDevs?style=flat-square" alt="Twitter Followers"></a>
 <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License">
 <a href="https://github.com/Shopify/cli/actions/workflows/shopify-cli.yml">![badge](https://github.com/Shopify/cli/actions/workflows/shopify-cli.yml/badge.svg)</a>
 
 With the Shopify command line interface (Shopify CLI 3.0), you can:
+
 - initialize, build, dev, and deploy Shopify apps, extensions, functions and themes
 - build custom storefronts and manage their hosting
 
@@ -24,6 +26,7 @@ Install the latest version of  [Node.js](https://nodejs.org/en/download/) and [n
 When you’re building a Shopify app, you can initialize your project using your preferred package manager. A single command will install all the dependencies you need — including Shopify CLI itself.
 
 Initialize your project using one of the following commands:
+
 - `npm init @shopify/app@latest` (installed by default with Node)
 - `pnpm create @shopify/create-app@latest`
 - `yarn create @shopify/app`
@@ -47,12 +50,35 @@ Learn more in the docs: [Shopify CLI for themes](https://shopify.dev/docs/storef
 
 ## Developing Hydrogen custom storefronts with Shopify CLI ##
 
-The Hydrogen code lives here: https://github.com/Shopify/hydrogen/tree/main/packages/cli
+The Hydrogen code lives here: <https://github.com/Shopify/hydrogen/tree/main/packages/cli>
 
 Learn more in the docs: [Shopify CLI for Hydrogen storefronts](https://shopify.dev/docs/custom-storefronts/hydrogen/cli)
 
 <p>&nbsp;</p>
 
+## Agent Skill
+
+The repo includes an [Agent Skill](https://agentskills.io) at `skills/shopify-cli/` that injects Shopify CLI knowledge directly into the agent's context. This follows the open [Agent Skills format](https://agentskills.io/specification) and works with any compatible agent — Claude Code, Cursor, Gemini CLI, VS Code, and others.
+
+The skill is auto-discovered based on task context (e.g. when the user mentions Shopify themes or apps). It works with or without the MCP server:
+
+- **With the MCP server:** The agent uses MCP tools for execution (structured responses, auto-parsed JSON, auth detection)
+- **Without the MCP server:** The agent runs `shopify` commands directly via shell
+
+Install the skill with the [skills CLI](https://skills.sh):
+
+```sh
+npx skills add Shopify/cli --skill shopify-cli
+```
+
+Or using the full path:
+
+```sh
+npx skills add https://github.com/Shopify/cli/tree/main/skills/shopify-cli
+```
+
+<p>&nbsp;</p>
+
 ## Help 🖐
 
 If you encounter issues using the CLI or have feedback you'd like to share with us, below are some options:

skills/shopify-cli/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: shopify-cli
+description: Runs Shopify CLI commands for theme and app development. Handles theme push, pull, dev, check, publish, and app dev, deploy, build. Use when the user mentions Shopify themes, Shopify apps, Liquid templates, storefronts, or needs to interact with a Shopify store.
+metadata:
+  author: shopify
+  version: "1.0"
+---
+
+# Shopify CLI
+
+Runs [Shopify CLI](https://shopify.dev/docs/api/shopify-cli) commands for theme and app development workflows.
+
+## Non-interactive execution
+
+The CLI is designed for interactive terminal use. For AI-assisted execution, always apply these flags:
+
+- `--force` or `-f` to skip confirmation prompts
+- `--no-color` to disable ANSI escape codes
+- `--json` when available for structured, parseable output
+- `theme check` uses `--output json` instead of `--json`
+
+## Store resolution
+
+Before running any store-scoped command, determine the target store:
+
+1. Check if the user specified a store in their request
+2. Look for `shopify.theme.toml` or `shopify.app.toml` in the project
+3. Check if `SHOPIFY_FLAG_STORE` env var is set
+4. If none found, ask the user
+
+## Authentication
+
+If a command fails with an auth error ("not logged in", "session expired"):
+
+1. Run `shopify auth login --store <store>` (allow ~2 minutes for browser OAuth)
+2. Retry the original command after login succeeds
+
+## Command reference
+
+### Theme commands
+
+| Task | Command | Notes |
+|------|---------|-------|
+| List themes | `shopify theme list --json` | Returns theme IDs, names, roles |
+| Theme info | `shopify theme info --json` | Details about a theme |
+| Push | `shopify theme push --force --json` | Upload local to remote |
+| Pull | `shopify theme pull --force` | Download remote to local |
+| Check quality | `shopify theme check --output json` | Theme Check linting |
+| Dev server | `shopify theme dev` | Long-running — start in separate terminal |
+| Publish | `shopify theme publish --force` | Make a theme live |
+| Delete | `shopify theme delete --force` | Remove a theme |
+| Rename | `shopify theme rename --name <name>` | Rename a theme |
+| Duplicate | `shopify theme duplicate --force --json` | Copy a theme |
+| Init | `shopify theme init <name>` | Scaffold from starter theme |
+| Package | `shopify theme package` | Create .zip for distribution |
+| Share | `shopify theme share` | Create shareable preview link |
+| Profile | `shopify theme profile --json` | Liquid performance profiling |
+| Metafields | `shopify theme metafields pull --force` | Download metafield definitions |
+
+### App commands
+
+| Task | Command | Notes |
+|------|---------|-------|
+| Dev server | `shopify app dev` | Long-running — start in separate terminal |
+| Deploy | `shopify app deploy --force` | Deploy app to Shopify |
+| Build | `shopify app build` | Build the app |
+| Generate extension | `shopify app generate extension` | Scaffold a new extension |
+| App info | `shopify app info --json` | App configuration details |
+| Function run | `shopify app function run` | Run a function locally |
+| Execute query | `shopify app execute --query <gql>` | Run Admin API GraphQL query/mutation on a store |
+| Execute from file | `shopify app execute --query-file <path>` | Run query from a `.graphql` file |
+| Bulk execute | `shopify app bulk execute --query <gql> --watch` | Run bulk query/mutation; `--watch` waits for results |
+| Bulk status | `shopify app bulk status` | Check status of bulk operations |
+| Release | `shopify app release --version <v>` | Release an app version |
+| Versions list | `shopify app versions list --json` | List deployed versions |
+
+### Auth commands
+
+| Task | Command |
+|------|---------|
+| Log in | `shopify auth login --store <store>` |
+| Log out | `shopify auth logout` |
+
+## Key flags
+
+- `--store <url>` / `-s` — target store (e.g. `my-store.myshopify.com`)
+- `--theme <id-or-name>` / `-t` — target theme
+- `--path <dir>` — project directory (default: cwd)
+- `--json` — structured output
+- `--force` / `-f` — skip confirmation prompts
+- `--no-color` — disable ANSI colors
+- `--only <glob>` / `--ignore <glob>` — filter files for push/pull
+- `--development` / `-d` — target the development theme
+- `--live` / `-l` — target the live theme
+- `--query <gql>` / `-q` — GraphQL query or mutation string (execute commands)
+- `--query-file <path>` — path to `.graphql` file (mutually exclusive with `--query`)
+- `--variables <json>` / `-v` — GraphQL variables as JSON (execute commands)
+- `--variable-file <path>` — path to JSON/JSONL file with variables
+- `--output-file <path>` — write results to file instead of stdout
+- `--version <api-version>` — Admin API version (defaults to latest stable)
+- `--watch` — wait for bulk operation results before exiting
+
+## Workflows
+
+See [references/workflows.md](references/workflows.md) for common multi-step workflows including:
+- Creating a new theme
+- Iterating on an existing theme
+- Creating and deploying an app
+
+## Discovery
+
+Run `shopify <topic> --help` or `shopify <topic> <command> --help` to discover commands and flags not listed above.
+
+## Output handling
+
+- Parse `--json` output as structured data and summarize for the user
+- For non-JSON output, present the relevant portions
+- Long-running commands (`theme dev`, `app dev`) should be started in a separate terminal, not through an MCP server or automated tool
+
+## Interactive commands
+
+Some commands prompt for input that `--force` cannot suppress. These may hang when run non-interactively:
+- `app init` — prompts for template and app name
+- `app generate extension` — prompts for extension type and name (use `--template` and `--name` to pre-fill)
+- `theme dev` / `app dev` — long-running server processes (start in a separate terminal)
+
+If a command appears to hang, it is likely waiting for interactive input. Cancel it and check `--help` for flags that provide the needed values.
+
+## Destructive commands
+
+Before running commands that delete, publish, or deploy, always confirm with the user first:
+- `theme delete` — permanently removes a theme
+- `theme publish` — makes a theme live (replaces the current live theme)
+- `app deploy` — deploys to production
+- `app release` — releases an app version to users
+- `app execute` / `app bulk execute` — mutations are only allowed on dev stores

skills/shopify-cli/references/workflows.md

@@ -0,0 +1,138 @@
+# Shopify CLI Workflows
+
+Common multi-step workflows for theme and app development.
+
+## Create a new theme
+
+```bash
+shopify theme init my-theme
+cd my-theme
+shopify theme dev --store <store>
+```
+
+The `init` command clones the Skeleton starter theme. Use `--clone-url <url>` to start from a different repo, or `--latest` to pin to the latest release tag.
+
+## Iterate on an existing theme
+
+```bash
+# Pull the latest version of a theme to work on locally
+shopify theme pull --theme <id-or-name> --force
+
+# Or pull the live theme
+shopify theme pull --live --force
+
+# Start the dev server for live preview while editing
+shopify theme dev --store <store>
+
+# Make edits to Liquid, CSS, JSON files as needed...
+
+# Check for errors before pushing
+shopify theme check --output json
+
+# Push changes back to the store
+shopify theme push --force --json
+```
+
+Use `--development` / `-d` with push/pull to target the development theme specifically. Use `--only` and `--ignore` to limit which files are synced (e.g. `--only "sections/*"` or `--ignore "config/settings_data.json"`).
+
+## Create a new app
+
+```bash
+# Interactive — prompts for template and name
+shopify app init
+cd <app-directory>
+
+# Start local dev server (long-running — run in separate terminal)
+shopify app dev
+```
+
+Note: `app init` is interactive and will prompt for a template and app name. It cannot be fully automated with flags.
+
+## Add an extension to an app
+
+```bash
+# Interactive — prompts for extension type and name
+shopify app generate extension
+```
+
+Note: `app generate extension` is interactive. Use `--template <type>` and `--name <name>` to pre-fill values, but the CLI may still prompt for additional configuration.
+
+## Build, deploy, and release an app
+
+```bash
+# Build the app
+shopify app build
+
+# Deploy to Shopify (creates a new version)
+shopify app deploy --force
+
+# Release a specific version to users
+shopify app release --version <version>
+
+# Check app info and configuration
+shopify app info --json
+
+# List deployed versions
+shopify app versions list --json
+```
+
+## Execute GraphQL queries against a store
+
+```bash
+# Run an inline query
+shopify app execute --query '{ shop { name } }' --store <store>
+
+# Run a query from a file
+shopify app execute --query-file my-query.graphql --store <store>
+
+# Pass variables and save output
+shopify app execute --query-file mutation.graphql --variables '{"id":"gid://shopify/Product/123"}' --output-file result.json --store <store>
+
+# Use a specific API version
+shopify app execute --query '{ shop { name } }' --version 2024-10 --store <store>
+```
+
+Mutations are only allowed on dev stores. The app must be installed on the target store.
+
+## Bulk operations
+
+```bash
+# Run a bulk query and wait for results
+shopify app bulk execute --query '{ products { edges { node { id title } } } }' --watch --store <store>
+
+# Run a bulk mutation from a file with JSONL variables
+shopify app bulk execute --query-file bulk-mutation.graphql --variable-file items.jsonl --watch --output-file results.jsonl --store <store>
+
+# Check status of running bulk operations
+shopify app bulk status --store <store>
+```
+
+Use `--watch` to wait for results before exiting. Without it, the command submits the operation and returns immediately. Use `--output-file` with `--watch` to save results to a file.
+
+## App function development
+
+```bash
+# Run a function locally
+shopify app function run --path <function-dir>
+
+# Generate function types
+shopify app function typegen --path <function-dir>
+```
+
+## Check and push (theme quality gate)
+
+```bash
+shopify theme check --output json
+# If no errors:
+shopify theme push --force --json
+```
+
+## List and inspect themes
+
+```bash
+# List all themes
+shopify theme list --json
+
+# Get details about a specific theme
+shopify theme info --theme <id-or-name> --json
+```