project skill refinement

Author: clavery

.claude/skills/api-client-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-client-development
-description: Creating API clients with OpenAPI specs, authentication, and OAuth scopes for SCAPI and similar APIs
+description: Creating typed API clients with OpenAPI specs, authentication, and OAuth scopes for SCAPI and similar APIs. Use when adding a new SCAPI client, generating types from an OpenAPI spec, setting up OAuth middleware, or integrating a new Commerce API endpoint.
 metadata:
   internal: true
 ---
@@ -438,6 +438,16 @@ const {data, error} = await client.GET('/endpoint', {...});
 
 ---
 
+## Troubleshooting
+
+**OAuth scope errors (401/403 from SCAPI)**: Ensure the client factory calls `auth.withAdditionalScopes()` with both the domain scope (e.g., `sfcc.custom-apis`) and the tenant-specific scope (`SALESFORCE_COMMERCE_API:<tenantId>`). Use `buildTenantScope()` to strip the `f_ecom_` prefix from tenant IDs before building scopes.
+
+**Type generation failures**: Check that the OpenAPI spec in `specs/` is valid YAML/JSON. Run `pnpm --filter @salesforce/b2c-tooling-sdk run generate:types` and inspect the output. Common issues: spec references external files that aren't present, or uses OpenAPI features not supported by openapi-typescript.
+
+**Middleware ordering issues**: Auth middleware should be added first (`client.use(createAuthMiddleware(...))`), then logging. In openapi-fetch, middleware runs in reverse registration order for requests, so auth registered first means it runs last — ensuring the logging middleware sees the final request with auth headers.
+
+**`organizationId` mismatch**: SCAPI path parameters need the `f_ecom_` prefix (use `toOrganizationId()`), while OAuth scopes need the raw tenant ID (use `toTenantId()`). Mixing these up causes 404s or scope errors.
+
 ## Checklist: New SCAPI Client
 
 1. Add OpenAPI spec to `specs/`

.claude/skills/cli-command-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cli-command-development
-description: Creating new CLI commands and topics for the B2C CLI using oclif
+description: Creating new CLI commands and topics for the B2C CLI using oclif. Use when adding a new command, creating a topic, adding flags or arguments, implementing table output, or extending BaseCommand/OAuthCommand/InstanceCommand.
 metadata:
   internal: true
 ---
@@ -323,6 +323,16 @@ if (error) {
 
 See [API Client Development](../api-client-development/SKILL.md#error-handling) for supported error patterns.
 
+## Troubleshooting
+
+**Command not found after creating file**: Ensure the file is in the correct `packages/b2c-cli/src/commands/` subdirectory matching the intended command path. Run `pnpm --filter @salesforce/b2c-cli run build` to regenerate the oclif manifest. For new topics, add the topic to `package.json` under `oclif.topics`.
+
+**Flag parsing errors**: Check that flag names use kebab-case in the `static flags` definition. The `char` shorthand must be a single character. If using `dependsOn`, the referenced flag must exist in the same command's flags.
+
+**Missing i18n keys**: The `t()` function falls back to the default string (second argument), so missing keys won't crash at runtime. However, keep key paths consistent with the `commands.<topic>.<command>.<key>` pattern for future localization.
+
+**"requireX" methods not available**: Verify the command extends the correct base class. `requireServer()` is on `InstanceCommand`, `requireOAuthCredentials()` is on `OAuthCommand`, `requireMrtCredentials()` is on `MrtCommand`. Check the class hierarchy if a method is missing.
+
 ## Creating a Command Checklist
 
 1. Create file at `packages/b2c-cli/src/commands/<topic>/<command>.ts`

.claude/skills/documentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: documentation
-description: Updating user guides, CLI reference, and API documentation for the B2C CLI project
+description: Updating user guides, CLI reference, and API documentation for the B2C CLI project. Use when adding or changing CLI command docs, writing JSDoc for TypeDoc generation, updating Vitepress sidebar config, or creating new guide pages.
 metadata:
   internal: true
 ---

.claude/skills/sdk-module-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sdk-module-development
-description: Adding new modules and exports to the @salesforce/b2c-tooling-sdk package
+description: Adding new modules and exports to the @salesforce/b2c-tooling-sdk package. Use when creating a new SDK module, adding barrel file exports, configuring package.json exports, or building client factory functions.
 metadata:
   internal: true
 ---

.claude/skills/testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing
-description: Writing tests for the B2C CLI project using Mocha, Chai, and MSW
+description: Writing tests for the B2C CLI project using Mocha, Chai, and MSW. Use when writing unit or integration tests, mocking HTTP requests with MSW, testing CLI commands with oclif, isolating config in tests, or setting up test coverage.
 metadata:
   internal: true
 ---
@@ -438,71 +438,7 @@ it('handles server flag', async () => {
 
 ## Testing CLI Commands with oclif
 
-### Integration Tests with runCommand
-
-Use `@oclif/test`'s `runCommand()` for integration-style tests:
-
-```typescript
-import { runCommand } from '@oclif/test';
-import { expect } from 'chai';
-
-describe('ods list', () => {
-  it('runs without errors', async () => {
-    const { error } = await runCommand('ods list --help');
-    expect(error).to.be.undefined;
-  });
-});
-```
-
-### SDK Base Command Integration Tests
-
-The SDK includes a test fixture at `test/fixtures/test-cli/` for integration testing base command behavior. See `test/cli/base-command.integration.test.ts` for examples.
-
-### When to Use Each Approach
-
-| Approach | Use For |
-|----------|---------|
-| Unit tests with `stubParse` | Testing protected method logic in isolation |
-| Integration tests with fixture | Testing full command lifecycle, flag parsing |
-| `runCommand()` in b2c-cli | Testing actual CLI commands |
-
-## E2E Tests
-
-E2E tests run against real infrastructure and are skipped without credentials:
-
-```typescript
-describe('ODS Lifecycle E2E', function () {
-  this.timeout(360_000); // 6 minutes
-
-  const CLI_BIN = path.resolve(__dirname, '../../../bin/run.js');
-
-  before(function () {
-    if (!process.env.SFCC_CLIENT_ID || !process.env.SFCC_CLIENT_SECRET) {
-      this.skip();
-    }
-  });
-
-  async function runCLI(args: string[]) {
-    return execa('node', [CLI_BIN, ...args], {
-      env: { ...process.env, SFCC_LOG_LEVEL: 'silent' },
-      reject: false,
-    });
-  }
-
-  it('creates a sandbox', async function () {
-    this.timeout(300_000);
-
-    const result = await runCLI([
-      'ods', 'create',
-      '--realm', process.env.TEST_REALM!,
-      '--ttl', '24',
-      '--json',
-    ]);
-
-    expect(result.exitCode).to.equal(0);
-  });
-});
-```
+See [CLI Command Testing Patterns](./references/CLI-COMMAND-TESTING.md) for integration tests with `runCommand`, SDK base command fixture tests, E2E test patterns, and when to use each approach.
 
 ## Coverage
 
@@ -515,30 +451,19 @@ open coverage/index.html
 
 ## Test Helpers Reference
 
-### CLI Package (`packages/b2c-cli/test/helpers/`)
+See [Test Helpers Reference](./references/HELPERS.md) for a full list of helpers available in both the CLI and SDK packages.
 
-| Helper | Purpose |
-|--------|---------|
-| `runSilent(fn)` | Capture and suppress stdout/stderr from command execution |
-| `stubParse(command, flags, args)` | Stub oclif's parse method with flags (includes silent log level) |
-| `createTestCommand(CommandClass, config, flags, args)` | Create command instance with stubbed parse |
-| `createIsolatedConfigHooks()` | Mocha hooks for config isolation |
-| `createIsolatedEnvHooks()` | Mocha hooks for env var isolation |
+## Troubleshooting
 
-### SDK Package (`packages/b2c-tooling-sdk/test/helpers/`)
+**MSW handler not matching requests**: Verify the URL pattern in `http.get()`/`http.post()` matches the full URL including base path. Use `onUnhandledRequest: 'error'` in `server.listen()` to surface unmatched requests. Check that the HTTP method matches (e.g., `http.all()` for WebDAV methods like MKCOL/PROPFIND).
 
-| Helper | Purpose |
-|--------|---------|
-| `MockAuthStrategy` | Mock authentication for API clients |
-| `stubParse(command, flags, args)` | Stub oclif's parse method (includes silent log level) |
-| `createNullStream()` | Create a writable stream that discards output |
-| `CapturingStream` | Writable stream that captures output for assertions |
+**Config or env vars leaking between tests**: Always pair `isolateConfig()` with `restoreConfig()` in `beforeEach`/`afterEach`. Missing `restoreConfig()` causes subsequent tests to run with cleared env vars. Use `sinon.restore()` in `afterEach` to clean up all stubs.
 
-### SDK Test Utils (exported from package)
+**Import path errors ("module not found")**: Use package exports (`@salesforce/b2c-tooling-sdk/clients`) not relative paths. If a new export was added, ensure it's in `package.json` `exports` with the `development` condition pointing to the `.ts` source file.
 
-```typescript
-import { isolateConfig, restoreConfig } from '@salesforce/b2c-tooling-sdk/test-utils';
-```
+**Fake timers break MSW**: MSW v2 uses microtasks internally. Never use `@sinonjs/fake-timers` or `sinon.useFakeTimers()` in tests that use MSW. Use `pollInterval: 10` for fast polling tests instead.
+
+**Test output is noisy**: Use `runSilent()` to suppress stdout/stderr from commands. The `stubParse` helper automatically sets `'log-level': 'silent'` to quiet pino logger output.
 
 ## Writing Tests Checklist
 

.claude/skills/testing/references/CLI-COMMAND-TESTING.md

@@ -0,0 +1,69 @@
+# CLI Command Testing Patterns
+
+## Testing CLI Commands with oclif
+
+### Integration Tests with runCommand
+
+Use `@oclif/test`'s `runCommand()` for integration-style tests:
+
+```typescript
+import { runCommand } from '@oclif/test';
+import { expect } from 'chai';
+
+describe('ods list', () => {
+  it('runs without errors', async () => {
+    const { error } = await runCommand('ods list --help');
+    expect(error).to.be.undefined;
+  });
+});
+```
+
+### SDK Base Command Integration Tests
+
+The SDK includes a test fixture at `test/fixtures/test-cli/` for integration testing base command behavior. See `test/cli/base-command.integration.test.ts` for examples.
+
+### When to Use Each Approach
+
+| Approach | Use For |
+|----------|---------|
+| Unit tests with `stubParse` | Testing protected method logic in isolation |
+| Integration tests with fixture | Testing full command lifecycle, flag parsing |
+| `runCommand()` in b2c-cli | Testing actual CLI commands |
+
+## E2E Tests
+
+E2E tests run against real infrastructure and are skipped without credentials:
+
+```typescript
+describe('ODS Lifecycle E2E', function () {
+  this.timeout(360_000); // 6 minutes
+
+  const CLI_BIN = path.resolve(__dirname, '../../../bin/run.js');
+
+  before(function () {
+    if (!process.env.SFCC_CLIENT_ID || !process.env.SFCC_CLIENT_SECRET) {
+      this.skip();
+    }
+  });
+
+  async function runCLI(args: string[]) {
+    return execa('node', [CLI_BIN, ...args], {
+      env: { ...process.env, SFCC_LOG_LEVEL: 'silent' },
+      reject: false,
+    });
+  }
+
+  it('creates a sandbox', async function () {
+    this.timeout(300_000);
+
+    const result = await runCLI([
+      'ods', 'create',
+      '--realm', process.env.TEST_REALM!,
+      '--ttl', '24',
+      '--json',
+    ]);
+
+    expect(result.exitCode).to.equal(0);
+  });
+});
+```

.claude/skills/testing/references/HELPERS.md

@@ -0,0 +1,26 @@
+# Test Helpers Reference
+
+## CLI Package (`packages/b2c-cli/test/helpers/`)
+
+| Helper | Purpose |
+|--------|---------|
+| `runSilent(fn)` | Capture and suppress stdout/stderr from command execution |
+| `stubParse(command, flags, args)` | Stub oclif's parse method with flags (includes silent log level) |
+| `createTestCommand(CommandClass, config, flags, args)` | Create command instance with stubbed parse |
+| `createIsolatedConfigHooks()` | Mocha hooks for config isolation |
+| `createIsolatedEnvHooks()` | Mocha hooks for env var isolation |
+
+## SDK Package (`packages/b2c-tooling-sdk/test/helpers/`)
+
+| Helper | Purpose |
+|--------|---------|
+| `MockAuthStrategy` | Mock authentication for API clients |
+| `stubParse(command, flags, args)` | Stub oclif's parse method (includes silent log level) |
+| `createNullStream()` | Create a writable stream that discards output |
+| `CapturingStream` | Writable stream that captures output for assertions |
+
+## SDK Test Utils (exported from package)
+
+```typescript
+import { isolateConfig, restoreConfig } from '@salesforce/b2c-tooling-sdk/test-utils';
+```