@sadrmanesh/commerce-agent-skills 0.0.0-stage → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## [0.3.1] - 2026-10-30
+
+### Added
+
+- The release workflow publishes `@sadrmanesh/commerce-agent-skills` to GitHub Packages after npm, using the workflow's `GITHUB_TOKEN`. npmjs.com remains the main registry.
+- Install docs for GitHub Packages, with the `.npmrc` scope entry, in the installation guide and the README.
+
+### Changed
+
+- The package and every skill are now version 0.3.1.
+
+## [0.3.0] - 2026-10-30
+
+### Added
+
+- Skills for Stripe payments, Iranian payment gateways (Zarinpal request, callback, and verify, with Rial and Toman amounts), inventory across warehouses, returns and refunds, B2B pricing, catalog import and migration, storefront accessibility (WCAG 2.2 AA), storefront performance (Core Web Vitals), and MCP store tooling. Each has a rule, reference notes, and eval fixtures.
+- Node.js checks for Stripe webhook signatures, gateway verify responses, stock allocation, B2B price resolution, import rows, Web Vitals ratings, and MCP tool definitions.
+- `scripts/run-evals.mjs` and `npm run eval`, which score worked examples or a folder of answers against the fixtures, per task, per skill, and overall, with `--skill`, `--min-score`, and `--json`.
+- A "Store operations" category on the docs site.
+- The library is published on npm as `@sadrmanesh/commerce-agent-skills`. `npx @sadrmanesh/commerce-agent-skills init` copies every skill and rule into a project, `add <skill> [<skill> ...]` copies the named ones, and `list` prints them, with `--json`. Skills go to `.agents/skills/` and rules to `.agents/rules/` by default. `--layout root`, `--skills-dir`, `--rules-dir`, `--target`, `--only`, `--no-rules`, `--force`, `--dry-run`, and `--version` are supported, and no network access is needed.
+- The release workflow runs on `vX.Y.Z` tags, creates the GitHub release with the notes from this file, and publishes the package to npm.
+
+### Changed
+
+- `add` copies the matching rule by default. `--no-rules` turns that off, and `--with-rule` is still accepted.
+- The command now works when started through a symlink, as `npx` and global installs do.
+- The npm package ships only the command, skills, rules, and changelog.
+- The validator is stricter. `metadata.version` must equal the `package.json` version. Skills need `## Gotchas`, `## Verification`, and `## Evaluation` sections and a 100 to 320 character description. Rule headings must match skill headings. Every `must_include` term must be taught by the skill, its rule, or its references. Example files must match a task. Reference links must resolve. Every skill must be in exactly one docs category. Docs and website pages must not use em dashes or the zero-width non-joiner.
+- Every skill is now version 0.3.0. Ten skills gained an `## Evaluation` section.
+- The docs site is now built with MkDocs Material. Skill, rule, and guide pages come straight from the repository, with a catalog page per category, search, a dark theme, and a Persian overview.
+
+## 0.2.0 - 2026-10-30
+
+### Added
+
+- Skills for multi-vendor payouts, Shopify apps, a Next.js storefront, Google Merchant product feeds, tax and shipping, subscription billing, fraud and risk review, vector product search, product-description guardrails, and conversion events.
+- Evaluation tasks and a worked example for every skill.
+- A zero-dependency `commerce-agent-skills` command with `list` and `add`. The package is not published to the npm registry.
+- A static docs build, a GitHub Pages workflow, and a manual release workflow that tags a version.
+
+## 0.1.0 - 2026-10-30
+
+### Added
+
+- Skills for WooCommerce plugin development, the WooCommerce REST API, WordPress plugin security, payment gateway integration, product catalog modeling, marketplace search and ranking, checkout, Persian and RTL localization, order and webhook reliability, and product structured data.
+- A plain-Markdown rule for each skill.
+- Node.js checks for catalog documents, WooCommerce webhook signatures, Persian and search text, and product JSON-LD.
+- A skill validator, a README catalog generator, tests, and a GitHub Actions workflow.
+- Installation and format notes under `docs/`.
+
+[0.3.0]: https://github.com/sadrmanesh/commerce-agent-skills/compare/v0.2.0...v0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naser Sadrmanesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# commerce-agent-skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skills and rules for AI coding agents that build e-commerce and marketplace products.
+
+**Documentation:** <https://sadrmanesh.github.io/commerce-agent-skills/>
+
+The skills follow the [Agent Skills](https://agentskills.io/specification) format: a folder, a `SKILL.md` file with `name` and `description`, and optional reference files and scripts. An agent that supports that format can load them. The format does not name an install path. [Installation](docs/installation.md) explains how to point your agent at these folders.
+
+Version 0.3.0 adds store operations to the library. It keeps the twenty skills from 0.1.0 and 0.2.0 and adds Stripe payments, Iranian payment gateways such as Zarinpal, inventory across warehouses, returns and refunds, B2B pricing, catalog import and migration, storefront accessibility, storefront performance, and MCP store tooling. It also adds a stricter validator and an eval runner that scores answers against the fixtures.
+
+## Features
+
+- Twenty-nine skills an agent can load when a task matches the skill description.
+- A matching plain-Markdown rule for each skill, for agents that keep short rules in context.
+- Evaluation tasks and a worked example for every skill, and `scripts/run-evals.mjs` to score answers against them.
+- Reference notes and small Node.js tools where a check is better than another paragraph.
+- A strict validator, a catalog built from the skill files, and a docs build, all run in CI. The validator checks versions, required sections, rule headings, that every eval term is taught by the skill, category coverage, and prose style.
+- An `npx @sadrmanesh/commerce-agent-skills` installer that copies every skill and rule, or the ones you name, into your project.
+
+## Skill catalog
+
+<!-- catalog:start -->
+| Skill | Description |
+| --- | --- |
+| [`woocommerce-plugin-development`](skills/woocommerce-plugin-development/SKILL.md) | Build and change WooCommerce plugins with hooks, CRUD data stores, HPOS-safe order access, nonces, capabilities, and gettext. Use when writing or reviewing a plugin that reads or writes WooCommerce products, orders, customers, or checkout. |
+| [`woocommerce-rest-api`](skills/woocommerce-rest-api/SKILL.md) | Call the WooCommerce REST API at wc/v3, including authentication, pagination, batch writes, and webhook registration, and keep it separate from the Store API. Use when an external system integrates with a WooCommerce store over HTTP. |
+| [`wordpress-plugin-security`](skills/wordpress-plugin-security/SKILL.md) | Review and implement WordPress plugin security: capabilities, nonces, sanitization, escaping, prepared SQL, and REST permission callbacks. Use when adding admin screens, AJAX, uploads, hooks, or REST routes in a WordPress or WooCommerce plugin. |
+| [`payment-gateway-integration`](skills/payment-gateway-integration/SKILL.md) | Integrate a payment provider with idempotent charges, signature-checked webhooks, and an explicit map from provider states to order states. Use when adding or changing checkout payment, capture, refund, or payment notification handling. |
+| [`product-catalog-modeling`](skills/product-catalog-modeling/SKILL.md) | Model a sellable catalog of simple products, variants, attributes, SKUs, and stock, and check the model before importing it. Use when designing product data, variation matrices, inventory rules, or catalog imports. |
+| [`marketplace-search-and-ranking`](skills/marketplace-search-and-ranking/SKILL.md) | Index purchasable catalog units and rank them with text relevance, facets, stock, and language-aware matching for Persian and other languages. Use when building marketplace search, filters, relevance, or multilingual product discovery. |
+| [`checkout-ux-and-conversion`](skills/checkout-ux-and-conversion/SKILL.md) | Design checkout so the full cost is visible before payment, guest purchase works, and field or payment errors can be corrected without losing the cart. Use when changing the checkout flow, address form, payment choice, or order confirmation page. |
+| [`rtl-and-persian-localization`](skills/rtl-and-persian-localization/SKILL.md) | Localize a storefront for Persian (fa_IR) and right-to-left layout: logical CSS, digits, Yeh and Kaf, ZWNJ, currency display, and Gregorian storage. Use when building or reviewing Persian, Farsi, or RTL commerce UI. |
+| [`order-and-webhook-reliability`](skills/order-and-webhook-reliability/SKILL.md) | Accept order and payment webhooks with a raw-body signature check, durable deduplication, and reconciliation against the source of truth. Use when handling order events, payment notifications, or outbound webhook delivery. |
+| [`ecommerce-seo-structured-data`](skills/ecommerce-seo-structured-data/SKILL.md) | Add product JSON-LD that matches the visible offer, including price, currency, availability, and images, without a second conflicting Product node. Use when editing product-page SEO, schema.org markup, or merchant listing data. |
+| [`multi-vendor-payouts`](skills/multi-vendor-payouts/SKILL.md) | Split a marketplace order by vendor, record commission as ledger entries, and pay vendors only settled amounts. Use when adding vendor catalogs, commissions, refunds that cross vendors, or payout batches. |
+| [`shopify-app-development`](skills/shopify-app-development/SKILL.md) | Build a Shopify app with the configured Admin API version, session-token auth for embedded admin requests, and HMAC-verified webhooks. Use when creating or changing a Shopify app, Admin GraphQL call, app proxy, or Shopify webhook handler. |
+| [`headless-nextjs-storefront`](skills/headless-nextjs-storefront/SKILL.md) | Build a Next.js storefront that loads catalog data on the server, keeps admin secrets off the client, and revalidates price and stock. Use when adding product, cart, or checkout UI in a Next.js App Router storefront for WooCommerce or another headless commerce API. |
+| [`google-merchant-product-feeds`](skills/google-merchant-product-feeds/SKILL.md) | Build a Google Merchant Center product feed item with the required id, title, description, link, image, availability, and price fields. Use when exporting products to Merchant Center, Content API items, or a product feed file. |
+| [`tax-and-shipping`](skills/tax-and-shipping/SKILL.md) | Calculate tax and shipping from the destination and the store's configured rules, and store the breakdown on the order. Use when changing tax classes, shipping zones, rates, or the amount shown before payment. |
+| [`subscription-billing`](skills/subscription-billing/SKILL.md) | Model subscription state, renewal charges, proration, and dunning without treating a renewal as a new one-time checkout. Use when adding or changing recurring billing, plan changes, cancellation, or failed renewal recovery. |
+| [`fraud-and-risk-basics`](skills/fraud-and-risk-basics/SKILL.md) | Hold or review risky payments using provider signals, velocity, and 3-D Secure without storing card numbers. Use when adding payment risk checks, a manual review queue, or decline handling for card abuse. |
+| [`vector-product-search`](skills/vector-product-search/SKILL.md) | Add vector retrieval beside lexical product search, with one embedding per purchasable unit and exact SKU lookup kept first. Use when adding embedding search, hybrid ranking, or re-embedding after catalog edits. |
+| [`product-description-guardrails`](skills/product-description-guardrails/SKILL.md) | Generate product titles and descriptions only from catalog facts, and block prices, certifications, and medical claims that are not in the record. Use when writing or reviewing generated product copy, Merchant Center text, or locale-specific descriptions. |
+| [`conversion-event-tracking`](skills/conversion-event-tracking/SKILL.md) | Send commerce analytics events with stable names, item ids, and a purchase event that fires once from a confirmed order. Use when adding or changing view_item, add_to_cart, begin_checkout, purchase, or refund tracking. |
+| [`stripe-payments`](skills/stripe-payments/SKILL.md) | Take card and wallet payments with Stripe PaymentIntents or Checkout Sessions, idempotency keys, and signed webhooks that move the order to paid. Use when adding Stripe to a store, handling Stripe webhooks, or refunding through the Stripe API. |
+| [`iranian-payment-gateways`](skills/iranian-payment-gateways/SKILL.md) | Integrate Zarinpal and other Shaparak redirect gateways with a server-side verify call, Rial and Toman amounts, and one paid transition per authority. Use when adding an Iranian payment gateway or fixing callback, verify, or amount handling for IRR or IRT stores. |
+| [`inventory-and-multi-warehouse`](skills/inventory-and-multi-warehouse/SKILL.md) | Track stock per location with on-hand, reserved, and available quantities, reserve at checkout, and allocate orders across warehouses without overselling. Use when adding warehouses or stores as stock locations, reservations, transfers, or order routing. |
+| [`returns-and-refunds`](skills/returns-and-refunds/SKILL.md) | Run returns as a tracked RMA from request to inspection, refund only what the policy and payment allow, and restock only inspected items. Use when building a returns portal, refund rules, exchanges, store credit, or restocking after a return. |
+| [`b2b-pricing`](skills/b2b-pricing/SKILL.md) | Price for business buyers with customer-group price lists, quantity tiers, contract prices, minimum quantities, net terms, and tax exemption, resolved on the server. Use when adding wholesale or B2B prices, tiered pricing, quotes, or company accounts to a store. |
+| [`catalog-import-and-migration`](skills/catalog-import-and-migration/SKILL.md) | Import, export, and migrate product catalogs with stable SKU keys, a dry run, parent-before-variation order, batched writes, and URL redirects. Use when moving a store between platforms, bulk importing CSV or JSON products, or exporting a catalog for another system. |
+| [`storefront-accessibility`](skills/storefront-accessibility/SKILL.md) | Build product, cart, and checkout pages that meet WCAG 2.2 AA: keyboard use, visible focus, labels and autocomplete, announced errors and cart updates, contrast, and target size. Use when building or reviewing storefront UI, forms, filters, carousels, or checkout for accessibility. |
+| [`storefront-performance`](skills/storefront-performance/SKILL.md) | Improve storefront Core Web Vitals (LCP, INP, CLS) using field data at the 75th percentile, image and font loading, caching of catalog pages, and lighter third-party scripts. Use when product or category pages feel slow, Web Vitals fail, or a theme, app, or script change needs a performance check. |
+| [`mcp-store-tooling`](skills/mcp-store-tooling/SKILL.md) | Design Model Context Protocol servers for stores: read and write tools with annotations, input and output schemas, scopes, dry runs and confirmation for risky writes, resources, and remote auth. Use when exposing a store's catalog, orders, or customers to an agent through MCP, or reviewing such a server. |
+<!-- catalog:end -->
+
+## Install
+
+Install the skills into your project with npx. Node.js 20 or newer is required, and nothing is downloaded after the package itself:
+
+```bash
+npx @sadrmanesh/commerce-agent-skills init
+```
+
+That copies every skill to `.agents/skills/` and every rule to `.agents/rules/`. To pick skills, or to write them where your agent looks:
+
+```bash
+npx @sadrmanesh/commerce-agent-skills list
+npx @sadrmanesh/commerce-agent-skills add woocommerce-plugin-development stripe-payments
+npx @sadrmanesh/commerce-agent-skills init --layout root
+npx @sadrmanesh/commerce-agent-skills init --skills-dir path/to/skills --rules-dir path/to/rules
+```
+
+`init` skips skills that are already installed, `--force` replaces them, and `--dry-run` shows what would be written. From a checkout, `node bin/commerce-agent-skills.mjs` takes the same arguments. Details are in [docs/installation.md](docs/installation.md) and [docs/cli.md](docs/cli.md).
+
+The package is on npmjs.com and, with the same name, on GitHub Packages. npmjs.com is the default; [docs/installation.md](docs/installation.md#install-from-github-packages) has the `.npmrc` lines for GitHub Packages.
+
+## Work on the library
+
+Clone the repository and check the skills:
+
+```bash
+git clone https://github.com/sadrmanesh/commerce-agent-skills.git
+cd commerce-agent-skills
+node scripts/validate-skills.mjs
+```
+
+Node.js 20 or newer is required for the validator, the docs generator, and the command. The docs site also needs Python and MkDocs. This repository is a skill library, not a dependency of the storefront.
+
+## Usage
+
+Agents read `name` and `description` to decide whether a skill applies, then read the `SKILL.md` body. Reference files and scripts are loaded only when the skill points to them. Keep instructions in `SKILL.md` and longer notes under `references/`.
+
+Rules in [`rules/`](rules/) are not skills. They are short constraints you can install as always-on guidance. A skill is for a task. A rule is for every task in that area. See [docs/rules.md](docs/rules.md).
+
+Regenerate the catalog table after a description change:
+
+```bash
+node scripts/generate-catalog.mjs
+node scripts/generate-catalog.mjs --check
+node --test
+```
+
+Score answers against the eval fixtures:
+
+```bash
+node scripts/run-evals.mjs
+node scripts/run-evals.mjs --answers ./answers --min-score 0.8
+```
+
+The first command checks the worked examples. The second reads `answers/<skill>/<task-id>.md`, prints a score per skill, and exits with status 1 below the threshold.
+
+The skill format is documented in [docs/skill-format.md](docs/skill-format.md). Evaluation fixtures and the runner are documented in [docs/evaluations.md](docs/evaluations.md).
+
+## Docs site
+
+The documentation lives at [sadrmanesh.github.io/commerce-agent-skills](https://sadrmanesh.github.io/commerce-agent-skills/). It is built with MkDocs Material, and the skill, rule, and guide pages are generated from this repository by `scripts/build-docs.mjs`, so they always match the files here. `.github/workflows/pages.yml` deploys it on pushes to `main`. See [docs/github-pages.md](docs/github-pages.md).
+
+`.github/workflows/release.yml` runs when a `vX.Y.Z` tag is pushed. It checks that the tag matches `package.json`, runs the validator, evals, and tests, creates the GitHub release if it does not exist, and publishes `@sadrmanesh/commerce-agent-skills` to npm and to GitHub Packages, which uses the workflow's `GITHUB_TOKEN`. Running it by hand with a version tags that version first.
+
+## Roadmap
+
+0.3.0 adds nine store operations skills, the eval runner, stricter validation, and the `npx @sadrmanesh/commerce-agent-skills` installer. The runner does not send tasks to a live agent: it scores answer files you collect.
+
+Later releases can add:
+
+- Runnable reference services for the payout ledger and a feed upload, with the same checks the local scripts already apply.
+- More store platforms, written to the same level of API detail as the WooCommerce and Shopify skills.
+- More payment providers, written like the Stripe and Zarinpal skills.
+- Graded eval rubrics beyond substring checks.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Run the validator before opening a pull request. New skills need a matching rule, a row in `skills/catalog-order.txt`, and a place in `website/categories.json`.
+
+## License
+
+[MIT](LICENSE). Copyright (c) 2026 Naser Sadrmanesh.
+
+## Author
+
+Naser Sadrmanesh
+
+- GitHub: [https://github.com/sadrmanesh](https://github.com/sadrmanesh)
+- Website: [https://sadrmanesh.github.io](https://sadrmanesh.github.io)

package/bin/commerce-agent-skills.mjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { cp, mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseFrontmatter, splitFrontmatter } from "../scripts/lib/frontmatter.mjs";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Where skills and rules land inside a project.
+ * `agents` keeps both under a hidden .agents directory, which many agents scan.
+ * `root` writes skills/ and rules/ at the top of the project.
+ */
+export const LAYOUTS = Object.freeze({
+  agents: Object.freeze({ skills: ".agents/skills", rules: ".agents/rules" }),
+  root: Object.freeze({ skills: "skills", rules: "rules" }),
+});
+
+export const DEFAULT_LAYOUT = "agents";
+
+export function packageSkillsDir(root = packageRoot) {
+  return path.join(root, "skills");
+}
+
+export function packageRulesDir(root = packageRoot) {
+  return path.join(root, "rules");
+}
+
+export async function packageVersion(root = packageRoot) {
+  const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+  return pkg.version;
+}
+
+async function isDirectory(target) {
+  return stat(target).then(
+    (info) => info.isDirectory(),
+    () => false,
+  );
+}
+
+async function isFile(target) {
+  return stat(target).then(
+    (info) => info.isFile(),
+    () => false,
+  );
+}
+
+export async function listSkillRecords(root = packageRoot) {
+  const skillsDir = packageSkillsDir(root);
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  const records = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const skillPath = path.join(skillsDir, entry.name, "SKILL.md");
+    if (!(await isFile(skillPath))) {
+      continue;
+    }
+    const text = await readFile(skillPath, "utf8");
+    const { yaml } = splitFrontmatter(text);
+    const data = parseFrontmatter(yaml);
+    records.push({
+      name: entry.name,
+      description: typeof data.description === "string" ? data.description : "",
+      hasRule: await isFile(path.join(packageRulesDir(root), `${entry.name}.md`)),
+    });
+  }
+  records.sort((a, b) => a.name.localeCompare(b.name));
+  return records;
+}
+
+/**
+ * Resolve the skills and rules directories for an install.
+ * `dir` is the older single-directory form: skills go to `dir`, rules to a
+ * `rules` directory next to it.
+ */
+export function resolveTargets({ target = ".", layout, skillsDir, rulesDir, dir } = {}) {
+  const base = path.resolve(target);
+  if (dir !== undefined) {
+    if (typeof dir !== "string" || dir.trim() === "") {
+      throw new Error("--dir needs a path.");
+    }
+    const skills = path.resolve(base, dir);
+    return {
+      skills,
+      rules: rulesDir ? path.resolve(base, rulesDir) : path.join(path.dirname(skills), "rules"),
+    };
+  }
+  const layoutName = layout ?? DEFAULT_LAYOUT;
+  const preset = LAYOUTS[layoutName];
+  if (!preset) {
+    throw new Error(`Unknown layout: ${layoutName}. Use one of: ${Object.keys(LAYOUTS).join(", ")}.`);
+  }
+  return {
+    skills: path.resolve(base, skillsDir ?? preset.skills),
+    rules: path.resolve(base, rulesDir ?? preset.rules),
+  };
+}
+
+function checkSkillName(name, known) {
+  if (typeof name !== "string" || name === "" || !/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+    throw new Error(`Invalid skill name: ${name || "(empty)"}`);
+  }
+  if (!known.has(name)) {
+    throw new Error(`Unknown skill: ${name}. Run "commerce-agent-skills list" to see the names.`);
+  }
+}
+
+/**
+ * Copy skills (and their rules) into a project.
+ * Returns one entry per skill: { name, status, destination, rulePath }.
+ * status is "added", "replaced", "skipped" (exists, onExisting = "skip"),
+ * or "planned" when dryRun is set.
+ */
+export async function installSkills({
+  names,
+  target = ".",
+  layout,
+  skillsDir,
+  rulesDir,
+  dir,
+  rules = true,
+  force = false,
+  onExisting = "error",
+  dryRun = false,
+  root = packageRoot,
+}) {
+  const records = await listSkillRecords(root);
+  const known = new Map(records.map((record) => [record.name, record]));
+  const wanted = names === undefined ? records.map((record) => record.name) : [...new Set(names)];
+  if (wanted.length === 0) {
+    throw new Error("No skills selected.");
+  }
+  for (const name of wanted) {
+    checkSkillName(name, known);
+  }
+  const targets = resolveTargets({ target, layout, skillsDir, rulesDir, dir });
+
+  const plan = [];
+  for (const name of wanted) {
+    const destination = path.join(targets.skills, name);
+    const exists = await isDirectory(destination);
+    if (exists && !force && onExisting === "error") {
+      throw new Error(`${destination} already exists. Pass --force to replace it.`);
+    }
+    const rulePath = rules && known.get(name).hasRule ? path.join(targets.rules, `${name}.md`) : undefined;
+    plan.push({ name, exists, destination, rulePath });
+  }
+
+  const results = [];
+  for (const item of plan) {
+    if (item.exists && !force) {
+      results.push({ name: item.name, status: "skipped", destination: item.destination });
+      continue;
+    }
+    if (dryRun) {
+      results.push({ name: item.name, status: "planned", destination: item.destination, rulePath: item.rulePath });
+      continue;
+    }
+    await mkdir(path.dirname(item.destination), { recursive: true });
+    if (item.exists) {
+      await rm(item.destination, { recursive: true, force: true });
+    }
+    await cp(path.join(packageSkillsDir(root), item.name), item.destination, { recursive: true });
+    if (item.rulePath) {
+      await mkdir(path.dirname(item.rulePath), { recursive: true });
+      await cp(path.join(packageRulesDir(root), `${item.name}.md`), item.rulePath, { force: true });
+    }
+    results.push({
+      name: item.name,
+      status: item.exists ? "replaced" : "added",
+      destination: item.destination,
+      rulePath: item.rulePath,
+    });
+  }
+  return { targets, results };
+}
+
+/** Copy one skill. Kept for scripts written against 0.2.0. */
+export async function addSkill({ name, dir, force = false, withRule = false, root = packageRoot }) {
+  if (typeof dir !== "string" || dir.trim() === "") {
+    throw new Error("--dir is required.");
+  }
+  const { results } = await installSkills({ names: [name], dir, force, rules: withRule, root });
+  return { destination: results[0].destination, rulePath: results[0].rulePath };
+}
+
+const USAGE = `Usage:
+  commerce-agent-skills list [--json]
+  commerce-agent-skills init [options]
+  commerce-agent-skills add <skill> [<skill> ...] [options]
+
+Commands:
+  list      Print every skill with its description.
+  init      Copy the whole library, or the skills named with --only.
+  add       Copy the named skills.
+
+Options:
+  --target <dir>       Project directory to install into. Default: current directory.
+  --layout <name>      agents (.agents/skills and .agents/rules, default)
+                       or root (skills/ and rules/).
+  --skills-dir <path>  Skills directory, relative to --target. Overrides the layout.
+  --rules-dir <path>   Rules directory, relative to --target. Overrides the layout.
+  --dir <path>         Skills directory for add, with rules in a sibling rules/ directory.
+  --only <a,b>         init: install only these skills.
+  --no-rules           Do not copy the matching rules.
+  --force              Replace skills that are already installed.
+  --dry-run            Print what would be copied and write nothing.
+  -h, --help           Show this help.
+  -v, --version        Print the version.`;
+
+const VALUE_FLAGS = new Set(["--target", "--layout", "--skills-dir", "--rules-dir", "--dir", "--only"]);
+const BOOLEAN_FLAGS = new Set(["--no-rules", "--force", "--dry-run", "--with-rule", "--json", "--help", "-h"]);
+
+export function parseArgs(args) {
+  const options = {};
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg.startsWith("-")) {
+      const [flag, inline] = arg.includes("=") ? [arg.slice(0, arg.indexOf("=")), arg.slice(arg.indexOf("=") + 1)] : [arg, undefined];
+      if (VALUE_FLAGS.has(flag)) {
+        const value = inline ?? args[index + 1];
+        if (inline === undefined) {
+          index += 1;
+        }
+        if (value === undefined || (inline === undefined && value.startsWith("--"))) {
+          throw new Error(`${flag} needs a value.`);
+        }
+        options[flag.slice(2)] = value;
+      } else if (BOOLEAN_FLAGS.has(flag) && inline === undefined) {
+        options[flag === "-h" ? "help" : flag.replace(/^--/, "")] = true;
+      } else {
+        throw new Error(`Unknown option: ${arg}`);
+      }
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { options, positionals };
+}
+
+function display(target) {
+  const relative = path.relative(process.cwd(), target);
+  return relative === "" ? "." : relative.startsWith("..") ? target : relative;
+}
+
+function report({ targets, results }, dryRun) {
+  const verb = dryRun ? "Would add" : "Added";
+  for (const result of results) {
+    if (result.status === "skipped") {
+      console.log(`Skipped ${result.name}: ${display(result.destination)} exists (use --force to replace)`);
+      continue;
+    }
+    const label = result.status === "replaced" ? "Replaced" : verb;
+    const rule = result.rulePath ? ` and ${display(result.rulePath)}` : "";
+    console.log(`${label} ${result.name} at ${display(result.destination)}${rule}`);
+  }
+  const copied = results.filter((result) => result.status !== "skipped").length;
+  console.log(
+    `${dryRun ? "Planned" : "Done"}: ${copied} of ${results.length} skills. Skills: ${display(targets.skills)}, rules: ${display(targets.rules)}`,
+  );
+}
+
+export async function main(argv, root = packageRoot) {
+  const [command, ...rest] = argv;
+  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+    console.log(USAGE);
+    return command === undefined ? 2 : 0;
+  }
+  if (command === "--version" || command === "-v") {
+    console.log(await packageVersion(root));
+    return 0;
+  }
+
+  let parsed;
+  try {
+    parsed = parseArgs(rest);
+  } catch (error) {
+    console.error(error.message);
+    console.error(USAGE);
+    return 2;
+  }
+  const { options, positionals } = parsed;
+  if (options.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  if (command === "list") {
+    if (positionals.length > 0) {
+      console.error(USAGE);
+      return 2;
+    }
+    const records = await listSkillRecords(root);
+    if (options.json) {
+      console.log(JSON.stringify(records.map(({ name, description }) => ({ name, description })), null, 2));
+    } else {
+      for (const record of records) {
+        console.log(`${record.name}\t${record.description}`);
+      }
+    }
+    return 0;
+  }
+
+  if (command === "init" || command === "add") {
+    if (command === "init" && positionals.length > 0) {
+      console.error(`init takes no skill names. Use --only ${positionals.join(",")} or add.`);
+      return 2;
+    }
+    if (command === "add" && positionals.length === 0) {
+      console.error("add needs at least one skill name.");
+      console.error(USAGE);
+      return 2;
+    }
+    if (command === "add" && options.only) {
+      console.error("--only is for init. Pass skill names to add.");
+      return 2;
+    }
+    const names =
+      command === "add"
+        ? positionals
+        : options.only
+          ? options.only.split(",").map((name) => name.trim()).filter(Boolean)
+          : undefined;
+    try {
+      const outcome = await installSkills({
+        names,
+        target: options.target ?? ".",
+        layout: options.layout,
+        skillsDir: options["skills-dir"],
+        rulesDir: options["rules-dir"],
+        dir: options.dir,
+        rules: !options["no-rules"],
+        force: Boolean(options.force),
+        onExisting: command === "init" ? "skip" : "error",
+        dryRun: Boolean(options["dry-run"]),
+        root,
+      });
+      report(outcome, Boolean(options["dry-run"]));
+      return 0;
+    } catch (error) {
+      console.error(error.message);
+      return 1;
+    }
+  }
+
+  console.error(`Unknown command: ${command}`);
+  console.error(USAGE);
+  return 2;
+}
+
+// npx and global installs start the command through a symlink, so compare real paths.
+function realpathSafe(file) {
+  try {
+    return realpathSync(path.resolve(file));
+  } catch {
+    return path.resolve(file);
+  }
+}
+
+const isCli = Boolean(process.argv[1]) && realpathSafe(fileURLToPath(import.meta.url)) === realpathSafe(process.argv[1]);
+
+if (isCli) {
+  process.exitCode = await main(process.argv.slice(2));
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@sadrmanesh/commerce-agent-skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Tool-agnostic skills and rules for AI coding agents that build e-commerce and marketplace products.",
+  "keywords": [
+    "agent-skills",
+    "skills",
+    "ecommerce",
+    "woocommerce",
+    "shopify",
+    "stripe",
+    "marketplace",
+    "coding-agents",
+    "rules",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Naser Sadrmanesh <info.sadrmanesh@gmail.com>",
+  "type": "module",
+  "bin": {
+    "commerce-agent-skills": "./bin/commerce-agent-skills.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "rules",
+    "scripts/lib/frontmatter.mjs",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "validate": "node scripts/validate-skills.mjs",
+    "catalog": "node scripts/generate-catalog.mjs",
+    "catalog:check": "node scripts/generate-catalog.mjs --check",
+    "docs": "node scripts/build-docs.mjs && mkdocs build --strict -f build/mkdocs.yml",
+    "test": "node --test",
+    "eval": "node scripts/run-evals.mjs",
+    "prepublishOnly": "node scripts/validate-skills.mjs && node scripts/generate-catalog.mjs --check && node --test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sadrmanesh/commerce-agent-skills.git"
+  },
+  "homepage": "https://sadrmanesh.github.io/commerce-agent-skills/",
+  "bugs": {
+    "url": "https://github.com/sadrmanesh/commerce-agent-skills/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/rules/b2b-pricing.md

@@ -0,0 +1,11 @@
+# B2B pricing
+
+- Resolve every B2B price on the server with one function shared by catalog, cart, and order.
+- Model prices as price lists with currency, validity, groups or companies, and quantity tiers.
+- Contract prices win when they exist. Otherwise apply one documented rule: lowest price or priority.
+- Use the highest tier whose `minQuantity` the line meets. Show the next tier to the buyer.
+- Enforce minimum quantities and order multiples in the cart.
+- Never cache a group price page for everyone. Vary by group.
+- Net terms need a credit limit check against open invoices.
+- Store tax exemption evidence or the validated VAT id on the order.
+- The price on a placed order line never changes when a list changes.