ebay-mcp 1.10.0 → 1.11.0

package/build/index.js

@@ -3,6 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { validateEnvironmentConfig } from './config/environment.js';
 import { createEbayMcpRuntime } from './mcp/runtime.js';
 import { runSetup } from './scripts/setup.js';
+import { runSkillsWizard } from './scripts/skills.js';
 import { getErrorMessage } from './utils/errors.js';
 import { serverLogger, getLogPaths } from './utils/logger.js';
 import { getCachedUpdateNotice } from './utils/version.js';
@@ -17,6 +18,16 @@ if (args.includes('setup')) {
         process.exit(1);
     }
 }
+if (args.includes('skills')) {
+    try {
+        await runSkillsWizard();
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Skills install failed:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
 /**
  * eBay API MCP Server
  * Provides access to eBay APIs through Model Context Protocol

package/build/scripts/setup.js

@@ -12,6 +12,8 @@ import { getOAuthAuthorizationUrl } from '../config/environment.js';
 import { startCallbackServer } from '../utils/oauth-helper.js';
 import { defineWizard, runWizard, ClackRenderer } from '../utils/setup-wizard.js';
 import { loadExistingConfig, quoteEnvValue } from './setup-shared.js';
+import { runSkillsWizard } from './skills.js';
+import prompts from 'prompts';
 import { configureLLMClient, detectLLMClients } from '../utils/llm-client-detector.js';
 import { runSecurityChecks, displaySecurityResults } from '../utils/security-checker.js';
 import { validateSetup, displayRecommendations } from '../utils/setup-validator.js';
@@ -906,6 +908,22 @@ export async function runSetup() {
     console.log('  3. Try: "Show my eBay seller information"\n');
     console.log(ui.dim('  Documentation: ') + ui.info('https://github.com/YosefHayim/ebay-mcp'));
     console.log(ui.dim('  Get Help:      ') + ui.info('https://github.com/YosefHayim/ebay-mcp/issues\n'));
+    // Optional: offer to install agent skills (Codex / Claude Code / Cursor) so the
+    // user's assistant knows how to drive the tools. Skipped in non-interactive runs.
+    if (process.stdin.isTTY) {
+        const { wantSkills } = (await prompts({
+            type: 'confirm',
+            name: 'wantSkills',
+            message: 'Install eBay AI skills (Codex / Claude Code / Cursor) so your assistant drives the tools faster?',
+            initial: true,
+        }));
+        if (wantSkills) {
+            await runSkillsWizard({ fromSetup: true });
+        }
+        else {
+            showInfo('You can install them later with: npm run skills');
+        }
+    }
 }
 // ─── Entry point ──────────────────────────────────────────────────────────────
 function parseArgs() {

package/build/scripts/skills.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+import prompts from 'prompts';
+import { ALL_PROVIDERS, applyWrite, buildRegistrySnapshot, detectProvider, planWrite, providerLabel, renderSkillTargets, } from '../skills/index.js';
+import { ebayPalette, printHeading, printInfo, printRule, printSuccess, printWarning, ui, } from '../utils/cli-ui.js';
+const ALL_LAYERS = ['using', 'contributing'];
+/** Splits a comma list flag value into trimmed, non-empty tokens. */
+function parseList(value) {
+    return (value ?? '')
+        .split(',')
+        .map((token) => token.trim())
+        .filter(Boolean);
+}
+/** Reads the value after a `--flag value` or `--flag=value` argument. */
+function readFlagValue(argv, flag) {
+    const inline = argv.find((arg) => arg.startsWith(`${flag}=`));
+    if (inline)
+        return inline.slice(flag.length + 1);
+    const index = argv.indexOf(flag);
+    if (index !== -1 && index + 1 < argv.length)
+        return argv[index + 1];
+    return undefined;
+}
+/** Parses skills CLI flags, ignoring the leading `skills` subcommand token. */
+function parseFlags(argv) {
+    const args = argv.filter((arg) => arg !== 'skills');
+    const providers = parseList(readFlagValue(args, '--providers')).filter((value) => ALL_PROVIDERS.includes(value));
+    const layers = parseList(readFlagValue(args, '--layer') ?? readFlagValue(args, '--layers')).filter((value) => ALL_LAYERS.includes(value));
+    return {
+        help: args.includes('--help') || args.includes('-h'),
+        yes: args.includes('--yes') || args.includes('-y'),
+        dryRun: args.includes('--dry-run'),
+        force: args.includes('--force'),
+        global: args.includes('--global'),
+        providers: providers.length > 0 ? providers : undefined,
+        layers: layers.length > 0 ? layers : undefined,
+    };
+}
+/** One-line summary of what an action means, for the preview. */
+function actionLabel(action) {
+    switch (action) {
+        case 'create':
+            return ui.success('create');
+        case 'update':
+            return ui.info('update');
+        case 'unchanged':
+            return ui.dim('unchanged');
+        case 'skip-foreign':
+            return ui.warning('skip (foreign file)');
+    }
+}
+/** Prints the planned writes so the user can review before anything is written. */
+function printPreview(plans) {
+    printHeading('Planned changes');
+    printRule();
+    for (const plan of plans) {
+        const { provider, layer, scope } = plan.target;
+        console.log(`  ${actionLabel(plan.action).padEnd(28)} ${ui.bold(`${provider}/${layer}`)} ${ui.dim(`(${scope})`)}`);
+        console.log(`  ${ui.dim('→ ' + plan.target.path)}`);
+    }
+    printRule();
+}
+/** Prints CLI usage. */
+function printHelp() {
+    console.log(`
+${ui.bold('ebay-mcp skills')}  ${ui.dim('install AI skills for Codex, Claude Code, and Cursor')}
+
+${ui.bold('Usage:')}
+  ebay-mcp skills [options]
+  npm run skills -- [options]
+
+${ui.bold('Options:')}
+  -h, --help              Show this help
+  -y, --yes               Non-interactive; accept detected defaults and flags
+      --providers <list>  Comma list: claude,cursor,codex
+      --layer <list>      Comma list: using,contributing  (default: using)
+      --global            Install to your home dir instead of this project
+      --dry-run           Show planned changes without writing
+      --force             Overwrite a same-named file we did not generate
+
+${ui.bold('Examples:')}
+  ebay-mcp skills
+  ebay-mcp skills --providers cursor,codex --layer using --dry-run
+  ebay-mcp skills --yes
+`);
+}
+/** Resolves the providers to use, preferring flags, else detection at the scope. */
+function resolveDefaultProviders(scope, cwd, home) {
+    return ALL_PROVIDERS.filter((provider) => detectProvider(provider, scope, cwd, home));
+}
+/**
+ * Runs the skills installer end to end: detect → choose providers/layers/scope →
+ * preview → confirm → write. Interactive by default; non-interactive when `--yes`
+ * is passed or stdin is not a TTY (so `npx ebay-mcp skills` in CI won't hang).
+ *
+ * Shared by the `ebay-mcp skills` subcommand, `npm run skills`, and the optional
+ * step at the end of `npm run setup`.
+ *
+ * @param options `argv` overrides process args; `fromSetup` trims the banner.
+ */
+export async function runSkillsWizard(options = {}) {
+    const flags = parseFlags(options.argv ?? process.argv.slice(2));
+    if (flags.help) {
+        printHelp();
+        return;
+    }
+    const cwd = process.cwd();
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? cwd;
+    const snapshot = buildRegistrySnapshot();
+    const nonInteractive = flags.yes || !process.stdin.isTTY;
+    if (!options.fromSetup) {
+        console.log(`\n  ${ebayPalette.blue.bold('eBay MCP')} ${ui.bold('· AI skills installer')}`);
+        console.log(`  ${ui.dim(`Generate skills for Codex, Claude Code, and Cursor from ${snapshot.toolCount} live tools.`)}\n`);
+    }
+    let providers;
+    let layers;
+    let scope;
+    if (nonInteractive) {
+        scope = flags.global ? 'global' : 'project';
+        providers = flags.providers ?? resolveDefaultProviders(scope, cwd, home);
+        layers = flags.layers ?? ['using'];
+        if (providers.length === 0) {
+            printWarning('No AI tools detected and none specified (--providers). Nothing to do.');
+            return;
+        }
+        printInfo(`Non-interactive: ${providers.join(', ')} · ${layers.join(', ')} · ${scope}`);
+    }
+    else {
+        const detectedProject = resolveDefaultProviders('project', cwd, home);
+        let cancelled = false;
+        const onCancel = () => {
+            cancelled = true;
+            return false;
+        };
+        const answers = (await prompts([
+            {
+                type: 'multiselect',
+                name: 'providers',
+                message: 'Install skills for which AI tools?',
+                instructions: false,
+                choices: ALL_PROVIDERS.map((provider) => ({
+                    title: providerLabel(provider),
+                    value: provider,
+                    selected: flags.providers
+                        ? flags.providers.includes(provider)
+                        : detectedProject.includes(provider),
+                })),
+            },
+            {
+                type: 'multiselect',
+                name: 'layers',
+                message: 'Which skills?',
+                instructions: false,
+                choices: [
+                    { title: 'Using — drive the eBay tools', value: 'using', selected: true },
+                    {
+                        title: 'Contributing — work on the ebay-mcp repo',
+                        value: 'contributing',
+                        selected: flags.layers?.includes('contributing') ?? false,
+                    },
+                ],
+            },
+            {
+                type: 'select',
+                name: 'scope',
+                message: 'Where should they be installed?',
+                choices: [
+                    { title: 'This project (recommended)', value: 'project' },
+                    { title: 'Global — my home dir (Cursor stays project-local)', value: 'global' },
+                ],
+                initial: flags.global ? 1 : 0,
+            },
+        ], { onCancel }));
+        if (cancelled) {
+            printWarning('Cancelled — nothing written.');
+            return;
+        }
+        providers = answers.providers ?? [];
+        layers = answers.layers ?? [];
+        scope = answers.scope ?? 'project';
+        if (providers.length === 0 || layers.length === 0) {
+            printWarning('Nothing selected — nothing written.');
+            return;
+        }
+    }
+    const rendered = renderSkillTargets({ providers, layers, scope, cwd, home, snapshot });
+    const plans = rendered.map((item) => planWrite(item.target, item.payload));
+    printPreview(plans);
+    if (flags.dryRun) {
+        printInfo('Dry run — no files written.');
+        return;
+    }
+    const foreign = plans.filter((plan) => plan.action === 'skip-foreign');
+    if (foreign.length > 0 && !flags.force) {
+        printWarning(`${foreign.length} file(s) exist that this tool did not generate and will be skipped. Re-run with --force to overwrite.`);
+    }
+    if (!nonInteractive) {
+        const writable = plans.filter((plan) => plan.action !== 'unchanged' && !(plan.action === 'skip-foreign' && !flags.force)).length;
+        if (writable === 0) {
+            printInfo('Everything is already up to date.');
+            return;
+        }
+        let cancelled = false;
+        const { go } = (await prompts({ type: 'confirm', name: 'go', message: `Write ${writable} file(s)?`, initial: true }, {
+            onCancel: () => {
+                cancelled = true;
+                return false;
+            },
+        }));
+        if (cancelled || !go) {
+            printWarning('Cancelled — nothing written.');
+            return;
+        }
+    }
+    // Re-plan each write against current disk state so that two managed-block
+    // targets sharing one file (both Codex layers → one AGENTS.md) compose instead
+    // of the second clobbering the first.
+    let written = 0;
+    for (const item of rendered) {
+        const plan = planWrite(item.target, item.payload);
+        const result = applyWrite(plan, { dryRun: false, force: flags.force });
+        if (result.written) {
+            written += 1;
+            printSuccess(`${result.action} ${plan.target.path}`);
+        }
+    }
+    printHeading('Done');
+    printInfo(`${written} file(s) written. Restart your AI tool so it picks up the new skills.`);
+}
+const entryPath = process.argv[1] ? resolve(process.argv[1]) : undefined;
+const modulePath = resolve(fileURLToPath(import.meta.url));
+if (entryPath && modulePath === entryPath) {
+    runSkillsWizard().catch((error) => {
+        console.error(ui.error('\n  Skills install failed:'), error);
+        process.exit(1);
+    });
+}

package/build/skills/content.js

@@ -0,0 +1,141 @@
+/** Renders the live family index as a Markdown table. */
+function familyTable(snapshot) {
+    const rows = snapshot.families
+        .map((family) => `| ${family.title} | ${family.count} | ${family.blurb} |`)
+        .join('\n');
+    return ['| Family | Tools | Covers |', '| --- | --- | --- |', rows].join('\n');
+}
+/**
+ * Builds the "using" skill: how a developer's AI should drive the eBay MCP
+ * tools. Workflow-first and lean — the per-tool schemas are already visible via
+ * MCP `tools/list`, so this focuses on sequencing, auth, and disambiguation that
+ * tool discovery can't convey. The family index is injected live from the
+ * registry snapshot.
+ *
+ * @param snapshot Live tool count and family index.
+ * @returns The provider-neutral skill document.
+ */
+export function buildUsingDoc(snapshot) {
+    return {
+        slug: 'ebay-mcp-using',
+        title: 'Using the eBay MCP tools',
+        description: `Drive eBay's Sell APIs through the ebay-mcp server: ${snapshot.toolCount} tools for listings, orders, marketing, and analytics. Use when creating or revising listings, fulfilling orders, issuing refunds, running Promoted Listings campaigns, or debugging eBay auth/rate-limit errors.`,
+        intro: `The \`ebay-mcp\` server exposes **${snapshot.toolCount} tools across 100% of eBay's Sell APIs**, running locally over MCP. Every tool is named \`ebay_<verb>_<noun>\` (plus two ChatGPT-connector tools, \`search\`/\`fetch\`). You already see each tool's input schema via \`tools/list\` — this skill covers what discovery can't: which tools to chain, what eBay requires first, and how to read its errors.`,
+        sections: [
+            {
+                heading: 'Authentication & environment',
+                body: [
+                    '- **Two auth tiers.** An app token allows ≈1,000 requests/day; user OAuth allows ≈10k–50k/day. Most write operations require user OAuth.',
+                    '- **A 401 / "access denied" is almost always a scope or environment problem**, not a malformed request. Check `ebay_get_token_status`, then re-run `npm run setup` if a scope is missing.',
+                    '- **Sandbox and production are separate worlds** — separate credentials and separate data. Confirm `EBAY_ENVIRONMENT` before investigating "missing" data.',
+                    '- **Marketplace & language headers matter.** Calls honor `EBAY_MARKETPLACE_ID` (e.g. `EBAY_US`) and `Content-Language` (e.g. `en-US`); a wrong pair causes empty or rejected results.',
+                ].join('\n'),
+            },
+            {
+                heading: 'Core workflows',
+                body: [
+                    '**Publish a fixed-price listing (REST Inventory model).**',
+                    '1. One-time account setup: `ebay_opt_in_to_program` (business-policy management), then `ebay_create_payment_policy`, `ebay_create_return_policy`, `ebay_create_fulfillment_policy` for reusable policy IDs, and `ebay_create_or_replace_inventory_location` for a `merchantLocationKey`.',
+                    '2. `ebay_create_inventory_item` (SKU + product details + availability).',
+                    '3. `ebay_create_offer` (SKU, marketplace, price, the policy IDs, location).',
+                    '4. `ebay_publish_offer` (offerId) → a live `listingId`. Use `ebay_bulk_publish_offer` for many at once.',
+                    '',
+                    '**Pick the right category & required item specifics first.**',
+                    '`ebay_get_default_category_tree_id` (marketplace) → `ebay_get_category_suggestions` (query) → `ebay_get_item_aspects_for_category` to learn the required aspects to put on the inventory item.',
+                    '',
+                    '**Fulfill an order.**',
+                    '`ebay_get_orders` (filter unfulfilled) → `ebay_get_order` (detail) → `ebay_create_shipping_fulfillment` (tracking number + carrier).',
+                    '',
+                    '**Refund or handle a payment dispute.**',
+                    'Voluntary refund: `ebay_issue_refund`. Disputes: `ebay_get_payment_dispute_summaries` → `ebay_get_payment_dispute` → `ebay_accept_payment_dispute` (or contest it).',
+                    '',
+                    '**Promote listings (Promoted Listings).**',
+                    '`ebay_create_campaign` → `ebay_bulk_create_ads_by_inventory_reference`. The Marketing family also covers promotions and reports.',
+                    '',
+                    '**Legacy XML path (Trading API).**',
+                    '`ebay_create_listing` / `ebay_revise_listing` / `ebay_relist_item` / `ebay_end_listing`, list via `ebay_get_active_listings`. Use only when you specifically need the legacy flow — do not mix it with the REST Inventory model for the same SKU.',
+                    '',
+                    '**Diagnose failing calls.**',
+                    '`ebay_get_token_status` (auth valid/expiring?) → `ebay_get_rate_limits` / `ebay_get_user_rate_limits` (quota hit?) → `ebay_get_api_status` (eBay-side outage?).',
+                ].join('\n'),
+            },
+            {
+                heading: 'Gotchas & disambiguation',
+                body: [
+                    '- **Two listing models.** REST Inventory (`inventory_item` → `offer` → `publish`) vs legacy Trading (XML). Pick one per SKU and stay in it.',
+                    '- **Offers need policies + a location first.** A "policy not found" error usually means the one-time account setup was skipped.',
+                    '- **`search` and `fetch` are ChatGPT-connector only** — ignore them when driving the Sell API directly.',
+                    '- **Write actions are real.** `publish`, `issue_refund`, `end_listing`, and any `bulk_*` change live seller data — confirm intent before calling.',
+                ].join('\n'),
+            },
+            {
+                heading: `Tool families (${snapshot.toolCount} tools)`,
+                body: familyTable(snapshot),
+            },
+        ],
+    };
+}
+/**
+ * Builds the "contributing" skill: how an AI working on the ebay-mcp repo should
+ * operate. Mirrors AGENTS.md (validation commands, module map, the add-a-tool
+ * flow, conventions) against the real `src/tools/categories/` layout.
+ *
+ * @param snapshot Live tool count and family index.
+ * @returns The provider-neutral skill document.
+ */
+export function buildContributingDoc(snapshot) {
+    return {
+        slug: 'ebay-mcp-contributing',
+        title: 'Contributing to ebay-mcp',
+        description: `Work on the ebay-mcp server itself: ${snapshot.toolCount} tools across eBay's Sell APIs (TypeScript/ESM, Zod, OpenAPI-generated types). Use when adding or changing eBay tools/endpoints, wiring the registry, or running the project's checks.`,
+        intro: `A local MCP server exposing **${snapshot.toolCount} tools across 100% of eBay's Sell APIs** — TypeScript/Node.js (ESM), \`@modelcontextprotocol/sdk\`, Zod validation, OpenAPI-generated types. Entry points: \`src/index.ts\` (STDIO) and \`src/server-http.ts\` (HTTP).`,
+        sections: [
+            {
+                heading: 'Validation (run before a PR)',
+                body: [
+                    '```bash',
+                    'npm run check     # tsc --noEmit + eslint + prettier --check  (must pass)',
+                    'npm test          # vitest run',
+                    'npm run build     # tsc + tsc-alias → build/',
+                    '```',
+                ].join('\n'),
+            },
+            {
+                heading: 'Module map (`src/`)',
+                body: [
+                    '| Path | Owns |',
+                    '| --- | --- |',
+                    '| `index.ts` / `server-http.ts` | MCP entry points (STDIO / HTTP) |',
+                    '| `api/` | eBay API client implementations (one area per file) |',
+                    '| `auth/` | OAuth 2.0 flow and token management |',
+                    '| `config/` | Environment loading, constants, marketplace defaults |',
+                    '| `tools/` | Tool wiring — `registry.ts`, `contracts.ts`, `define-tool.ts`, and `categories/` (13 family files that co-locate each tool definition with its handler via `defineTool`) |',
+                    "| `skills/` | Agent-skills generator (this skill's source) |",
+                    '| `schemas/` | Shared Zod schemas |',
+                    "| `types/` | TypeScript types — **auto-generated** from OpenAPI specs (don't hand-edit) |",
+                    '| `scripts/` | CLI tooling: `setup.ts`, `skills.ts`, `dev-sync.ts`, `diagnostics.ts` |',
+                    '| `utils/` | Shared utilities (logging, http, errors) |',
+                ].join('\n'),
+            },
+            {
+                heading: 'Add a tool or endpoint',
+                body: [
+                    '1. `npm run sync` — download the latest eBay specs, regenerate types, report missing endpoints.',
+                    '2. Add the API method in `src/api/`.',
+                    '3. Add a `defineTool({ ... handler })` entry in the matching `src/tools/categories/<family>.ts` — definition and handler live together; `registry.ts` derives everything from `categories/index.ts`.',
+                    '4. Add tests in `tests/`.',
+                    '5. `npm run check && npm test`.',
+                ].join('\n'),
+            },
+            {
+                heading: 'Conventions',
+                body: [
+                    '- **No `any`** — specific types; prefer narrowing over assertions. `types/` is generated, so model new shapes from the specs.',
+                    '- Validate tool inputs with Zod; derive related schemas rather than duplicating fields.',
+                    '- Commit with Conventional Commits (releases are changeset-driven).',
+                    '- Logs go to **stderr** only — stdout is reserved for the MCP protocol.',
+                ].join('\n'),
+            },
+        ],
+    };
+}

package/build/skills/index.js

@@ -0,0 +1,54 @@
+import { buildRegistrySnapshot } from '../skills/registry-snapshot.js';
+import { buildContributingDoc, buildUsingDoc } from '../skills/content.js';
+import { renderSkill } from '../skills/render.js';
+import { resolveTargets } from '../skills/targets.js';
+import { planWrite } from '../skills/install.js';
+export * from '../skills/types.js';
+export { buildRegistrySnapshot } from '../skills/registry-snapshot.js';
+export { buildUsingDoc, buildContributingDoc } from '../skills/content.js';
+export { renderSkill, renderClaudeSkill, renderCursorRule, renderCodexSection, } from '../skills/render.js';
+export { ALL_PROVIDERS, providerLabel, supportsScope, detectProvider, resolveTargets, } from '../skills/targets.js';
+export { planWrite, applyWrite } from '../skills/install.js';
+/**
+ * Returns the canonical document for a layer with the live registry injected.
+ *
+ * @param layer Which audience the skill serves.
+ * @param snapshot Live registry snapshot (defaults to a fresh one).
+ */
+export function buildSkillDoc(layer, snapshot = buildRegistrySnapshot()) {
+    return layer === 'using' ? buildUsingDoc(snapshot) : buildContributingDoc(snapshot);
+}
+/**
+ * The end-to-end core: resolves targets for the chosen providers × layers,
+ * renders each into its provider's native format, and returns idempotent write
+ * plans — without touching disk. Both the wizard and tests build on this.
+ *
+ * @param options Providers, layers, scope, and optional cwd/home/snapshot overrides.
+ * @returns One {@link RenderedTarget} per provider/layer target.
+ */
+export function renderSkillTargets(options) {
+    const snapshot = options.snapshot ?? buildRegistrySnapshot();
+    const docByLayer = {
+        using: buildUsingDoc(snapshot),
+        contributing: buildContributingDoc(snapshot),
+    };
+    const targets = resolveTargets(options.providers, options.layers, options.scope, options.cwd, options.home);
+    return targets.map((target) => ({
+        target,
+        payload: renderSkill(target.provider, docByLayer[target.layer], target.layer),
+    }));
+}
+/**
+ * Builds preview write plans for the chosen providers × layers. Note: when two
+ * managed-block targets share a file (both Codex layers → one `AGENTS.md`), each
+ * plan here is computed against the same on-disk content, so apply each write
+ * by re-planning from {@link RenderedTarget} (see the wizard) rather than
+ * applying these plans directly — otherwise the second same-file write would not
+ * see the first.
+ *
+ * @param options Providers, layers, scope, and optional cwd/home/snapshot overrides.
+ * @returns One {@link WritePlan} per provider/layer target.
+ */
+export function buildSkillPlans(options) {
+    return renderSkillTargets(options).map((rendered) => planWrite(rendered.target, rendered.payload));
+}

package/build/skills/install.js

@@ -0,0 +1,75 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import { blockEnd, blockStart, isOwnedByUs } from '../skills/markers.js';
+/** Wraps managed-block inner content between this layer's delimiters. */
+function wrapBlock(layer, inner) {
+    return `${blockStart(layer)}\n${inner}\n${blockEnd(layer)}`;
+}
+/**
+ * Replaces our managed block in `existing`, or appends it if absent — preserving
+ * all surrounding user content. Idempotent: feeding the result back in produces
+ * identical output.
+ */
+function mergeManagedBlock(existing, layer, inner) {
+    const start = blockStart(layer);
+    const end = blockEnd(layer);
+    const block = wrapBlock(layer, inner);
+    const startIdx = existing.indexOf(start);
+    const endIdx = existing.indexOf(end);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        return existing.slice(0, startIdx) + block + existing.slice(endIdx + end.length);
+    }
+    const prefix = existing.trim().length > 0 ? `${existing.replace(/\s+$/, '')}\n\n` : '';
+    return `${prefix}${block}\n`;
+}
+/**
+ * Computes what a write would do without touching disk.
+ *
+ * - Owned files (Claude/Cursor): `create` when absent, `update`/`unchanged` when
+ *   ours, `skip-foreign` when a same-named file exists that we did not write.
+ * - Managed blocks (Codex `AGENTS.md`): the block is merged into existing
+ *   content, so the result is `create`/`update`/`unchanged` and user text is
+ *   always preserved (never `skip-foreign`).
+ *
+ * @param target Resolved destination.
+ * @param payload Rendered content — a full file for owned targets, inner block
+ *   content for managed targets.
+ * @returns The planned action and the exact bytes that would be written.
+ */
+export function planWrite(target, payload) {
+    const exists = existsSync(target.path);
+    const previousContents = exists ? readFileSync(target.path, 'utf-8') : undefined;
+    if (target.kind === 'managed-block') {
+        const nextContents = mergeManagedBlock(previousContents ?? '', target.layer, payload);
+        const action = !exists ? 'create' : nextContents === previousContents ? 'unchanged' : 'update';
+        return { target, action, nextContents, previousContents };
+    }
+    // owned-file
+    if (!exists) {
+        return { target, action: 'create', nextContents: payload };
+    }
+    if (!isOwnedByUs(previousContents ?? '', target.layer)) {
+        return { target, action: 'skip-foreign', nextContents: payload, previousContents };
+    }
+    const action = previousContents === payload ? 'unchanged' : 'update';
+    return { target, action, nextContents: payload, previousContents };
+}
+/**
+ * Applies a write plan. Skips no-op writes (`unchanged`) and refuses to clobber
+ * a foreign owned file unless `force` is set. `dryRun` computes the result
+ * without writing.
+ *
+ * @param plan The plan from {@link planWrite}.
+ * @param options `dryRun` to preview only; `force` to overwrite a foreign file.
+ * @returns Whether the file was written.
+ */
+export function applyWrite(plan, options = {}) {
+    const isNoop = plan.action === 'unchanged';
+    const isBlockedForeign = plan.action === 'skip-foreign' && !options.force;
+    if (options.dryRun || isNoop || isBlockedForeign) {
+        return { target: plan.target, action: plan.action, written: false };
+    }
+    mkdirSync(dirname(plan.target.path), { recursive: true });
+    writeFileSync(plan.target.path, plan.nextContents, 'utf-8');
+    return { target: plan.target, action: plan.action, written: true };
+}

package/build/skills/markers.js

@@ -0,0 +1,25 @@
+/**
+ * HTML-comment markers that tag generated content as ours. Both owned files
+ * (Claude `SKILL.md`, Cursor `.mdc`) and managed blocks (Codex `AGENTS.md`) use
+ * the same layer-scoped namespace so re-runs find and replace exactly what a
+ * prior run wrote — and never touch a user's own content.
+ *
+ * Markers are HTML comments, which render invisibly in Markdown across all three
+ * tools.
+ */
+/** Single-line marker embedded near the top of an owned file to prove ownership. */
+export function ownershipMarker(layer) {
+    return `<!-- ebay-mcp:skill:${layer} (generated — re-run \`ebay-mcp skills\` to update) -->`;
+}
+/** Opening delimiter of a managed block inside a shared file. */
+export function blockStart(layer) {
+    return `<!-- ebay-mcp:skill:${layer}:start -->`;
+}
+/** Closing delimiter of a managed block inside a shared file. */
+export function blockEnd(layer) {
+    return `<!-- ebay-mcp:skill:${layer}:end -->`;
+}
+/** True when file contents already contain content we generated for this layer. */
+export function isOwnedByUs(contents, layer) {
+    return contents.includes(`ebay-mcp:skill:${layer}`); // matches ownership marker or block delimiters
+}

package/build/skills/registry-snapshot.js

@@ -0,0 +1,38 @@
+import { toolCategories } from '../tools/categories/index.js';
+/**
+ * Human descriptions for each tool family, keyed by the category `key` exported
+ * from the registry. Kept here (next to the snapshot) so copy lives in one place
+ * while counts stay live; an unknown key falls back to its registry title.
+ */
+const FAMILY_BLURBS = {
+    connector: 'ChatGPT connector protocol tools (`search`/`fetch`) — not used when driving the API directly',
+    'token-management': 'OAuth URL, token status, refresh, and credential diagnostics',
+    account: 'Business policies (payment, return, fulfillment), privileges, program opt-in, sales tax',
+    inventory: 'Inventory items, offers, locations, inventory groups, bulk publish — the REST listing model',
+    fulfillment: 'Orders, shipping fulfillments, refunds, and payment disputes',
+    marketing: 'Promoted Listings campaigns, ads, promotions, and marketing reports',
+    analytics: 'Seller standards, traffic reports, and customer-service metrics',
+    metadata: 'Marketplace policies, item conditions, listing constraints, automotive compatibility',
+    taxonomy: 'Category trees, category suggestions, and required item aspects',
+    communication: 'Buyer messages, member messages, and notification settings',
+    other: 'Feedback, recommendations, and assorted Sell-API helpers',
+    developer: 'API status, rate limits, client registration, and signing keys',
+    trading: 'Legacy Trading API (XML) — create / revise / relist / end fixed-price listings',
+};
+/**
+ * Builds a {@link RegistrySnapshot} from the live tool registry so a rendered
+ * skill always reflects the real catalogue. Counts come from {@link toolCategories}
+ * (the single source of truth for registry families); blurbs are static copy.
+ *
+ * @returns The current tool count and per-family index, in registry order.
+ */
+export function buildRegistrySnapshot() {
+    const families = toolCategories.map((category) => ({
+        key: category.key,
+        title: category.title,
+        count: category.entries.length,
+        blurb: FAMILY_BLURBS[category.key] ?? category.title,
+    }));
+    const toolCount = families.reduce((sum, family) => sum + family.count, 0);
+    return { toolCount, families };
+}

package/build/skills/render.js

@@ -0,0 +1,75 @@
+import { ownershipMarker } from '../skills/markers.js';
+/**
+ * Composes the shared Markdown body (title + intro + sections) at a given
+ * heading level. `baseLevel` 1 yields a standalone document (`#` title, `##`
+ * sections) for owned files; level 2 yields an embeddable section (`##` title,
+ * `###` sections) for a managed block inside a user's file.
+ */
+function renderBody(doc, baseLevel) {
+    const heading = (level) => '#'.repeat(level);
+    const parts = [`${heading(baseLevel)} ${doc.title}`, '', doc.intro];
+    for (const section of doc.sections) {
+        parts.push('', `${heading(baseLevel + 1)} ${section.heading}`, '', section.body);
+    }
+    return parts.join('\n');
+}
+/** YAML frontmatter scalar that is safe for arbitrary text (JSON strings are valid YAML). */
+function yamlString(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Renders a Claude Code skill file (`SKILL.md`): YAML frontmatter (`name`,
+ * `description`) so the model can invoke it on demand, an ownership marker, then
+ * the shared body.
+ */
+export function renderClaudeSkill(doc, layer) {
+    const frontmatter = [
+        '---',
+        `name: ${doc.slug}`,
+        `description: ${yamlString(doc.description)}`,
+        '---',
+    ];
+    return [...frontmatter, ownershipMarker(layer), '', renderBody(doc, 1), ''].join('\n');
+}
+/**
+ * Renders a Cursor rule file (`.mdc`): frontmatter with a `description` trigger
+ * and `alwaysApply: false` (agent-requested, not file-glob scoped, since eBay
+ * tools aren't tied to particular source files), an ownership marker, then body.
+ */
+export function renderCursorRule(doc, layer) {
+    const frontmatter = [
+        '---',
+        `description: ${yamlString(doc.description)}`,
+        'alwaysApply: false',
+        '---',
+    ];
+    return [...frontmatter, ownershipMarker(layer), '', renderBody(doc, 1), ''].join('\n');
+}
+/**
+ * Renders the inner content for a Codex `AGENTS.md` managed block: a level-2
+ * section with no frontmatter, so it nests cleanly under a user's existing
+ * top-level heading. The install step wraps this with block delimiters.
+ */
+export function renderCodexSection(doc) {
+    return renderBody(doc, 2);
+}
+/**
+ * Renders the payload for one provider. Owned-file providers (Claude, Cursor)
+ * return a complete file; the managed-block provider (Codex) returns inner
+ * content that {@link import('./install.js')} wraps with markers.
+ *
+ * @param provider Target tool.
+ * @param doc Canonical skill document.
+ * @param layer Skill layer (for the ownership marker).
+ * @returns The string payload for this provider.
+ */
+export function renderSkill(provider, doc, layer) {
+    switch (provider) {
+        case 'claude':
+            return renderClaudeSkill(doc, layer);
+        case 'cursor':
+            return renderCursorRule(doc, layer);
+        case 'codex':
+            return renderCodexSection(doc);
+    }
+}

package/build/skills/targets.js

@@ -0,0 +1,93 @@
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+/** All providers we can render for, in display order. */
+export const ALL_PROVIDERS = ['claude', 'cursor', 'codex'];
+/** Human label for a provider, used in the wizard and reports. */
+export function providerLabel(provider) {
+    switch (provider) {
+        case 'claude':
+            return 'Claude Code (.claude/skills)';
+        case 'cursor':
+            return 'Cursor (.cursor/rules)';
+        case 'codex':
+            return 'Codex (AGENTS.md)';
+    }
+}
+/**
+ * Whether a provider supports a given scope. Cursor only reads project-local
+ * rule files, so it has no global scope.
+ */
+export function supportsScope(provider, scope) {
+    if (provider === 'cursor')
+        return scope === 'project';
+    return true;
+}
+/** The filename slug for a layer, shared by Claude skill dirs and Cursor rule files. */
+function slug(layer) {
+    return `ebay-mcp-${layer}`;
+}
+/** Absolute path of the rendered file for a provider/layer/scope. */
+function resolvePath(provider, layer, scope, cwd, home) {
+    const base = scope === 'project' ? cwd : home;
+    switch (provider) {
+        case 'claude':
+            return join(base, '.claude', 'skills', slug(layer), 'SKILL.md');
+        case 'cursor':
+            return join(cwd, '.cursor', 'rules', `${slug(layer)}.mdc`);
+        case 'codex':
+            return scope === 'project' ? join(cwd, 'AGENTS.md') : join(home, '.codex', 'AGENTS.md');
+    }
+}
+/** Codex shares one `AGENTS.md` (managed block); the others own their own file. */
+function targetKind(provider) {
+    return provider === 'codex' ? 'managed-block' : 'owned-file';
+}
+/**
+ * Detects whether a provider already has a footprint at this scope, so the
+ * wizard can pre-select the tools a developer actually uses. Looks for the
+ * provider's instruction directory/file rather than the MCP client config —
+ * this is about where agent instructions live, which the MCP detector does not
+ * model.
+ */
+export function detectProvider(provider, scope, cwd, home) {
+    switch (provider) {
+        case 'claude':
+            return existsSync(join(scope === 'project' ? cwd : home, '.claude'));
+        case 'cursor':
+            return existsSync(join(cwd, '.cursor'));
+        case 'codex':
+            return scope === 'project'
+                ? existsSync(join(cwd, 'AGENTS.md'))
+                : existsSync(join(home, '.codex'));
+    }
+}
+/**
+ * Resolves the concrete write targets for the chosen providers × layers at a
+ * scope. Cursor is coerced to project scope (it has no global rules), so it is
+ * never silently dropped when a user picks "global".
+ *
+ * @param providers Selected providers.
+ * @param layers Selected skill layers.
+ * @param scope Requested scope.
+ * @param cwd Project root (defaults to `process.cwd()`).
+ * @param home User home (defaults to `os.homedir()`).
+ * @returns One {@link SkillTarget} per provider/layer.
+ */
+export function resolveTargets(providers, layers, scope, cwd = process.cwd(), home = homedir()) {
+    const targets = [];
+    for (const provider of providers) {
+        const effectiveScope = supportsScope(provider, scope) ? scope : 'project';
+        for (const layer of layers) {
+            targets.push({
+                provider,
+                scope: effectiveScope,
+                layer,
+                path: resolvePath(provider, layer, effectiveScope, cwd, home),
+                kind: targetKind(provider),
+                detected: detectProvider(provider, effectiveScope, cwd, home),
+            });
+        }
+    }
+    return targets;
+}

package/build/skills/types.js

@@ -0,0 +1,12 @@
+/**
+ * Shared types for the agent-skills generator.
+ *
+ * The skills feature renders one canonical, provider-neutral document per layer
+ * ({@link SkillLayer}) into each AI tool's native instruction format
+ * ({@link SkillProvider}) and installs it into a project or the user's home
+ * ({@link SkillScope}). These types model that pipeline: authored content
+ * ({@link SkillDoc}) + a live registry snapshot ({@link RegistrySnapshot}) →
+ * resolved write locations ({@link SkillTarget}) → idempotent write plans
+ * ({@link WritePlan}).
+ */
+export {};

package/build/tools/categories/index.js

@@ -12,24 +12,31 @@ import { otherEntries, claudeEntries } from './other.js';
 import { developerEntries } from './developer.js';
 import { tradingEntries } from './trading.js';
 /**
- * Registered tool entries in registry execution order. Connector tools (`search`/
- * `fetch`) are registered ahead of the eBay API tools, matching the prior registry.
+ * Registered tool families in registry execution order. Connector tools
+ * (`search`/`fetch`) are registered ahead of the eBay API tools, matching the
+ * prior registry. {@link registeredEntries} is derived from this list, so adding
+ * a family here both registers its tools and surfaces it in the family index.
  */
-export const registeredEntries = [
-    ...connectorEntries,
-    ...tokenManagementEntries,
-    ...accountEntries,
-    ...inventoryEntries,
-    ...fulfillmentEntries,
-    ...marketingEntries,
-    ...analyticsEntries,
-    ...metadataEntries,
-    ...taxonomyEntries,
-    ...communicationEntries,
-    ...otherEntries,
-    ...developerEntries,
-    ...tradingEntries,
+export const toolCategories = [
+    { key: 'connector', title: 'Connector', entries: connectorEntries },
+    { key: 'token-management', title: 'Token Management', entries: tokenManagementEntries },
+    { key: 'account', title: 'Account', entries: accountEntries },
+    { key: 'inventory', title: 'Inventory', entries: inventoryEntries },
+    { key: 'fulfillment', title: 'Fulfillment', entries: fulfillmentEntries },
+    { key: 'marketing', title: 'Marketing', entries: marketingEntries },
+    { key: 'analytics', title: 'Analytics', entries: analyticsEntries },
+    { key: 'metadata', title: 'Metadata', entries: metadataEntries },
+    { key: 'taxonomy', title: 'Taxonomy', entries: taxonomyEntries },
+    { key: 'communication', title: 'Communication', entries: communicationEntries },
+    { key: 'other', title: 'Other', entries: otherEntries },
+    { key: 'developer', title: 'Developer', entries: developerEntries },
+    { key: 'trading', title: 'Trading', entries: tradingEntries },
 ];
+/**
+ * Registered tool entries in registry execution order, flattened from
+ * {@link toolCategories}.
+ */
+export const registeredEntries = toolCategories.flatMap((category) => category.entries);
 /**
  * Handler-only entries: callable via `executeTool`/`getToolHandler` but intentionally
  * not advertised to MCP clients (no registered definition). Preserves prior behavior

package/build/utils/cli-ui.js

@@ -0,0 +1,47 @@
+import chalk from 'chalk';
+/**
+ * Shared terminal styling for the project's interactive CLIs.
+ *
+ * These helpers print to stdout, which is correct for the setup/skills wizards
+ * (the stdout-is-reserved rule applies to the MCP *server* runtime, not CLI
+ * tooling). The eBay brand palette matches the setup wizard.
+ */
+export const ebayPalette = {
+    red: chalk.hex('#E53238'),
+    blue: chalk.hex('#0064D2'),
+    yellow: chalk.hex('#F5AF02'),
+    green: chalk.hex('#86B817'),
+};
+/** Semantic text styles used across CLI output. */
+export const ui = {
+    dim: chalk.dim,
+    bold: chalk.bold,
+    success: chalk.green,
+    warning: chalk.yellow,
+    error: chalk.red,
+    info: chalk.cyan,
+};
+/** Prints a green success line. */
+export function printSuccess(message) {
+    console.log(`  ${ui.success('✓')} ${message}`);
+}
+/** Prints a yellow warning line. */
+export function printWarning(message) {
+    console.log(`  ${ui.warning('⚠')} ${message}`);
+}
+/** Prints a red error line. */
+export function printError(message) {
+    console.log(`  ${ui.error('✗')} ${message}`);
+}
+/** Prints a cyan info line. */
+export function printInfo(message) {
+    console.log(`  ${ui.info('ℹ')} ${message}`);
+}
+/** Prints a bold section heading preceded by a blank line. */
+export function printHeading(title) {
+    console.log(`\n  ${ui.bold(title)}`);
+}
+/** Prints a dim horizontal rule. */
+export function printRule(width = 56) {
+    console.log('  ' + ui.dim('─'.repeat(width)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ebay-mcp",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Model Context Protocol (MCP) server that exposes 100% of eBay's Sell APIs (332 tools across 270 endpoints) to AI assistants like Claude, Cursor, and Cline, covering inventory, order fulfillment, marketing, analytics, and developer tools with OAuth authentication and refresh-token support.",
   "type": "module",
   "main": "build/index.js",
@@ -32,6 +32,7 @@
     "build/mcp/**/*.js",
     "build/schemas/**/*.js",
     "build/scripts/**/*.js",
+    "build/skills/**/*.js",
     "build/tools/**/*.js",
     "build/utils/**/*.js",
     "build/types/index.js",
@@ -106,6 +107,7 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "setup": "tsx src/scripts/setup.ts",
+    "skills": "tsx src/scripts/skills.ts",
     "sync": "tsx src/scripts/dev-sync.ts",
     "diagnose": "tsx src/scripts/diagnostics.ts",
     "typecheck": "tsc --noEmit",