Next Commerce AI Skills

Pre-built skills that give AI coding agents deep knowledge of the Next Commerce platform — APIs, CLI workflows, architecture patterns, and gotchas — so they can work autonomously on your store.

Skills are structured markdown files. Any AI tool that accepts a context file or system prompt can use them. They work with Claude Code, OpenAI Codex, Cursor, GitHub Copilot, and any other agent that reads markdown.

Skills

Skill	What It Does	When to Use
Theme Figma Handoff	Prepare Figma storefront designs for implementation: source validation, section classification, asset manifests, Spark divergence ledger, matching visual refs, and documented coverage gaps	You have a Figma storefront/PDP/homepage design and need a low-inference handoff before next-theme-dev implements it
Theme Development	Build and customize storefront themes, including DTL templates, ntk CLI, Tailwind CSS, settings, side cart, active-theme publish safeguards, and visual QA	You're editing theme files, setting up a new storefront, publishing a bounded change, or debugging template and styling issues
Bulk Fulfillment Sync	Update orders to Fulfilled with tracking numbers from a CSV	Your fulfillment provider shipped orders but tracking didn't sync back — orders stuck in Processing
Bulk Fulfillment Move	Move fulfillment orders between warehouse locations in bulk — by order-number file or by Product ID / SKU list	Switching fulfillment providers, or moving every FO containing a given SKU/product to a new location
Bulk Subscription Actions	Pause, cancel, or PATCH explicit subscription fields for a list of subscription IDs	Merchant wants to bulk-pause until a date, set supplied renewal timestamps, bulk-cancel, or migrate subscriptions between gateways
Daily Ops Risk Scan	Read-only scan for Incomplete orders, Rejected orders, and Delivery Tracking failures/staleness	You want a daily queue of risky orders and stuck shipments to reduce support friction and dispute risk
New Campaign Setup	Scaffold and fully configure a new Next Commerce campaign repo — brand init, starter template, campaigns.json seed, API key, store details, and analytics in one pass	Starting a new Next Commerce campaign for a brand

For design-led theme work, run next-theme-figma before next-theme-dev. Both skills expect real screenshot evidence for visual QA, but they reuse tools already available to the agent or operator and support manual capture. They do not require a bundled browser automation package or screenshot service. When a Theme Development task targets an active theme, the skill adds an exact file manifest, rollback source, upload-count checks, and served-revision verification.

Each skill directory contains two documents: a README.md — a plain-language guide for the person running the skill (what it does, what you need, how to ask for it), written for non-technical readers — and a SKILL.md, the technical instructions the AI agent follows. Skill-specific detail lives in those per-skill docs, not here. Related skills cross-reference each other in their READMEs (for example, next-theme-figma runs upstream of next-theme-dev, and next-campaigns-setup documents its boundary with the campaigns-os package).

Quick Start

Recommended: Local Guided Installer

For most Next Commerce users, the most reliable path is to clone this repo and run the bundled installer. It previews changes before writing, supports common local agent profiles, and does not depend on external installer UX changing over time.

Clone and run the guided installer:

git clone https://github.com/NextCommerceCo/skills.git
cd skills
./skills.sh

Preview or install directly:

./skills.sh status
./skills.sh install codex
./skills.sh install codex next-ops-scan
./skills.sh status --target /tmp/next-skills next-ops-scan
./skills.sh dry-run --target /tmp/next-skills next-ops-scan

status is read-only and prints both the source and installed SKILL.md versions. A stale row means the installed semantic version is older; modified means the versions match but files differ; local-newer prevents a newer local copy from being mistaken for an ordinary refresh; and unknown-version means one side does not use the required X.Y.Z format. Use dry-run before install when reviewing several targets.

Targets:

• claude -> ~/.claude/skills
• codex -> ~/.codex/skills
• agents -> ~/.agents/skills
• all -> all of the above

Restart local agent sessions after updating skills so the refreshed instructions are loaded.

Updating an existing skill directory uses rsync so the destination path remains present while files are refreshed. Install rsync before using skills.sh on minimal environments that do not include it by default.

Ask Your AI Tool to Install

If you use an AI coding tool, you can also ask it to run the local guided installer for you:

Install the Next Commerce AI skill I need from https://github.com/NextCommerceCo/skills. Prefer cloning the repo and running ./skills.sh, choosing the installation location for my current AI tool. If a local checkout is not appropriate, use the public npx skills installer or load the relevant SKILL.md as context.

Tell it which skill you want, or ask it to inspect skills.json and choose the relevant one.

No-Checkout Install

If you want a one-liner without keeping a local checkout, use the skills CLI. It can pull SKILL.md files from GitHub and install them into many agent-specific skill directories.

Install all skills globally for your detected agent:

npx skills add NextCommerceCo/skills -g

Install a single skill globally for Codex:

npx skills add NextCommerceCo/skills -g -a codex --skill next-theme-dev

List available skills without installing:

npx skills add NextCommerceCo/skills --list

Target a specific agent:

npx skills add NextCommerceCo/skills -g -a claude-code

Skip prompts for scripted installs:

npx skills add NextCommerceCo/skills -g -a codex --skill next-ops-scan -y

Use npx skills update to refresh skills installed through the skills CLI.

Manual Fallback

Each skill is plain markdown. If your tool does not support native skill directories or the installers above, load the relevant SKILL.md as a system prompt, context file, rule, or chat upload according to that tool's conventions.

Machine-Readable Index

For AI agents that need to programmatically discover available skills, skills.json provides a structured manifest with skill IDs, descriptions, trigger phrases, and prerequisites. Agents can fetch this single file to decide which skill to load.

Prerequisites

Each skill lists its own requirements in the file. Common across all skills:

• Access to a Next Commerce store
• An API key with the scopes specified by the skill (create at Dashboard > Settings > API Access)

Contributing

Each skill is a directory containing a SKILL.md (the agent's technical instructions) and a README.md (a plain-language guide for the person running the skill). To add a new skill:

1. Create a directory with a descriptive name (e.g., next-my-skill/)
2. Add a SKILL.md with YAML frontmatter (name, version, description, allowed-tools) followed by the skill instructions in markdown
3. Add a "Using This Skill" section that points to the repo install guidance
4. Add a README.md written for non-technical readers: what the skill does, what the person needs, and how to ask for it — plain language, no code examples (use tables for data examples and [!IMPORTANT] callouts for things that matter)
5. Add an entry to skills.json
6. Update this README's skills table and any installer notes that should mention the skill
7. Run ./skills.sh status to confirm the local installer can discover the skill
8. Bump the skill version in both SKILL.md and skills.json
9. Run python3 scripts/check_skill_versions.py --base origin/main
10. Open a PR

Skill versioning

Every tracked file inside a skill directory is part of that skill's versioned package. A PR that changes any file under next-*/ must advance that skill's version in both its SKILL.md frontmatter and skills.json entry.

• Patch: fixes or clarifies existing behavior, safety rules, validation, or routing without adding a new execution surface.
• Minor: adds a new command, automation lane, detector/check family, output contract, or approved write surface.
• Major: changes ownership, safety posture, default side effects, or removes a supported contract.

CI compares each changed skill package with the pull request's base commit and rejects missing or non-increasing version bumps.

Issue tracking

Work in this repo is tracked with GitHub Issues and coordinated on the org-level Operations. Kanban board (Todo / In Progress / Done). New issues are added to the board automatically by the add-to-project workflow.

Before starting work on an issue: check it is not assigned to someone else, assign yourself (gh issue edit <n> --add-assignee @me), and move the card to In Progress. Open PRs with Closes #<n>; when the issue closes on merge, the board's built-in "Item closed" automation moves the card to Done. Contributors have a /next-board skill that wraps these board operations.