Documentation

This skill covers documentation for the Agentic B2C Developer Toolkit.

Audience and Framing

• Public docs explain capabilities, installation, configuration, and security. Describe outcomes people can request from their assistant; keep agent tool choreography, runtime internals, and implementation rationale in agent skills or contributor docs. Include technical details when they affect a user's choice.
• Write for junior developers and non-developer administrators. Lead with the task, benefit, and visible behavior; explain technical terms when needed for setup. Say "asks for approval" rather than "form elicitation" or "per-request confirmation." Keep protocol state, worker lifetimes, and execution budgets in contributor docs or agent skills. Shared features must cover CLI, IDE, and assistant use; reserve assistant-specific framing for the relevant sections.
• Link to canonical Salesforce Developer Center or Help pages for platform setup, requirements, and behavior. Toolkit guides supplement those workflows with our CLI, MCP, IDE, and skills capabilities; avoid maintaining a competing setup sequence. For Storefront Next, lead with Business Manager storefront setup and reuse its resources; link to the template's push workflow for source deployments. Keep matching agent skills aligned with those recommendations.
• Say "B2C Commerce" rather than "Commerce" alone. Use "IDE Extension" for the editor product. The TypeScript SDK is a supporting foundation, not a primary toolkit product alongside CLI, IDE, and AI tools.
• MCP tool references use compact tool-name/capability tables, access requirements, meaningful limits, and example requests. Link shared configuration/authentication; MCP Configuration covers MCP-specific settings only. Put toolset availability in a consistent Toolsets: field directly below each tool-group heading, not in prose or repeated table columns. Use subgroups when tools have different availability.
• Prefer plugin installation where supported; keep manual setup and toolset customization secondary. A brief linked mention of the Agent Plugins standard is useful; manifest/schema details are not installation guidance.
• MCP exposes skill guidance through skills_read; it does not install those collections as native assistant skills. Separate skills installation is optional, supported alongside MCP or alone. Show collections before their install examples.
• Keep optional project recommendations and copyable assistant instructions in docs/guide/project-setup.md. Link from product pages rather than duplicating the examples. Support standalone skills and MCP use; distinguish recommendations from installation requirements and generated project files.
• Safety Mode guidance leads with supported B2C operations and practical CLI, MCP, and IDE examples. Distinguish blocked actions, supported confirmations, and assistant approvals. Describe first-match rule precedence precisely; put broader agent/tool boundaries in a short scope note, not the introduction.

Shared Visual Patterns

Use the globally registered ExamplePrompt component for requests a reader can give their assistant:

<ExamplePrompt>

> Summarize this campaign's promotions and flag schedule conflicts.

</ExamplePrompt>

Write example prompts as user outcomes, without MCP tool names, toolsets, or instructions to use code mode. Name and explain those capabilities in the surrounding documentation, not in the user's request. Prompts should sound like natural business or development requests. Do not make users ask for policy enforcement, explanations of tool failures, routine verification, or session cleanup; those belong to tools and skills. Include constraints only when they express a real user choice, such as keeping a product offline or reviewing a proposed fix before editing code.

Keep blank lines around the Markdown quote so VitePress parses it. The component provides the upright "Example prompt" label, chat icon, tinted background, and italic prompt text. Preserve the quote in Markdown exports. Ordinary quotations, notes, terminal commands, and agent instructions do not use this treatment.

• Reuse AssistantInstall for client tabs and the shared MCP setup partials for the MCP page and Install AI Tools dialog. Order: Claude, Codex, VS Code, Cursor, OpenCode, Gemini. Keep full instructions in rendered HTML for search and no-JS readers. Put supported install buttons inside their client tab, before instructions.
• Use DocCards for capability links and .workflow-feature for an example prompt paired with an image. Add screenshots or diagrams where they explain a task, not to decorate every section. Use clearly labeled placeholders until real captures are available. Research screenshots in design-references/ stay uncommitted.
• Preserve the site's Salesforce colors and shared typography. Verify visual changes in the browser at desktop and mobile widths; source edits alone do not establish that icons, wrapping, or spacing render correctly.
• For clickable screenshots outside public/, import the image in the page's <script setup> and bind the link's :href to that import. A plain Markdown link to the source image can work in dev but 404 after Vite hashes the asset. Check link targets in a production build with DOCS_BASE_PATH=/pr-672/ (or another subpath), not only in the dev server.

CLI Terminal Images

Use Freeze for compact CLI output images beside the relevant command. Prefer read-only listings, searches, status checks, and local previews. Use real output; choose useful columns and supported result limits before capture. Local sample data is appropriate when labeled as a sample. Do not invent successful output or expose credentials, personal information, or customer data.

Match the existing Custom API image: JetBrains Mono, 14px, #171717 background, window controls, 12px corner radius, no outer background or shadow. Cyan prompts and restrained status colors are sufficient. Aim for a 700px logical frame and roughly 5-12 output lines. Freeze auto-sized PNGs render at 4x resolution; an explicit width disables that scaling, so use padding to keep shorter captures at a consistent width. Keep raw captures and render settings in the locally ignored design-references/ directory.

Keep capture scripts and instructions reusable across machines. Do not commit capture-session diaries, personal paths, or machine-specific activity notes.

Publish reviewed PNGs under docs/public/terminal/. Link the image to its full size using [![descriptive alt text](/terminal/name.png)](/terminal/name.png); describe the command's useful result and significant statuses in the alt text, not just "terminal screenshot." Identify sample data and consequential flags such as offline mode when needed to interpret the result. Avoid transcribing entire tables. The shared CSS limits display width to 680px. Keep copyable command examples in the page. Verify image readability and links on desktop, mobile, and a built site with a URL prefix.

Documentation Structure

The project has three types of documentation:

docs/
├── guide/              # User guides (manually written)
│   ├── index.md
│   ├── installation.md
│   ├── authentication.md
│   └── configuration.md
├── cli/                # CLI reference (manually written)
│   ├── index.md
│   ├── code.md
│   ├── webdav.md
│   ├── jobs.md
│   └── ...
├── api/                # API reference (auto-generated)
│   └── *.md
├── python/             # Python SDK guides (manually written)
│   └── api/            # Python API reference (generated, committed)
└── .vitepress/         # Vitepress configuration
    └── config.mts

Documentation Types

1. User Guides (docs/guide/)

Purpose: Help users get started and understand concepts.

When to update:

• New features that need explanation
• Changes to installation or setup process
• New authentication methods
• Configuration changes

Example structure:

# Getting Started

Introduction to the topic.

## Prerequisites

- Node.js 22+
- pnpm

## Installation

\`\`\`bash
pnpm install -g @salesforce/b2c-cli
\`\`\`

## Next Steps

- [Authentication](./authentication.md)
- [Configuration](./configuration.md)

2. CLI Reference (docs/cli/)

Purpose: Document command syntax, flags, and usage examples.

When to update:

• New commands added
• Flags added, removed, or changed
• Command behavior changes
• New examples needed

Structure per command topic:

# Code Commands

Commands for managing code versions and cartridge deployment.

## b2c code deploy

Deploy cartridges to a B2C Commerce instance.

### Usage

\`\`\`bash
b2c code deploy [PATH] [FLAGS]
\`\`\`

### Arguments

| Argument | Description                  | Required | Default |
| -------- | ---------------------------- | -------- | ------- |
| PATH     | Path to cartridges directory | No       | .       |

### Flags

| Flag                | Short | Description                 | Default |
| ------------------- | ----- | --------------------------- | ------- |
| --server            | -s    | Instance hostname           | -       |
| --code-version      | -v    | Code version name           | -       |
| --cartridge         | -c    | Include specific cartridges | -       |
| --exclude-cartridge | -x    | Exclude cartridges          | -       |

### Examples

\`\`\`bash

# Deploy all cartridges in current directory

b2c code deploy --server dev01.example.com --code-version v1

# Deploy specific cartridges

b2c code deploy ./cartridges -c app_storefront -c app_custom

# Deploy excluding certain cartridges

b2c code deploy -x test_cartridge -x bm_extensions
\`\`\`

### Authentication

Requires WebDAV credentials (username/password) or OAuth.

3. API Reference (docs/api/)

Purpose: Document the SDK programmatic API.

This is auto-generated from TypeScript JSDoc comments using TypeDoc.

Never edit files in docs/api/ directly. Instead:

1. Update JSDoc comments in SDK source files
2. Run pnpm run docs:api to regenerate

4. Python SDK (docs/python/)

Purpose: Guides and API reference for the Python SDK (python/b2c-tooling-sdk/), served under /python/. It is a self-contained section with its own sidebar — don't mirror TypeScript examples into it or add Python tabs to the main guides.

• Guides (docs/python/*.md) are hand-written. Link to the shared docs (/guide/configuration, /cli/auth, /api/) rather than re-explaining shared concepts. The guide sidebar is hand-maintained in config.mts.
• API reference (docs/python/api/) is generated from the Python docstrings (sphinx style) by python/b2c-tooling-sdk/scripts/generate_api_docs.py (griffe; no import of the package) along with docs/python/api/sidebar.json. Unlike docs/api/, the output is committed so the docs build needs no Python; the Python SDK CI job runs the --check mode.

Never edit docs/python/api/ directly. Update the docstrings, then from python/b2c-tooling-sdk/ run make api-docs (or make api-docs-check) and commit the result. New public subpackages must be added to PAGES in the script. Heading anchors are emitted in VitePress's slug form (lowercase, _/. → -) because VitePress rewrites cross-page #hash links that way.

Writing JSDoc for API Docs

Module-Level Documentation

Add to barrel files (index.ts):

/**
 * Authentication strategies for B2C Commerce APIs.
 *
 * This module provides various authentication mechanisms:
 * - OAuth 2.0 client credentials
 * - Basic authentication
 * - API key authentication
 *
 * @example
 * ```typescript
 * import { OAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
 *
 * const auth = new OAuthStrategy({
 *   clientId: 'my-client',
 *   clientSecret: 'my-secret',
 * });
 * ```
 *
 * @module auth
 */

Class Documentation

/**
 * Client for WebDAV file operations on B2C Commerce instances.
 *
 * Supports uploading, downloading, and managing files in various
 * WebDAV roots (Cartridges, IMPEX, Logs, etc.).
 *
 * @example
 * ```typescript
 * const client = new WebDavClient(hostname, auth);
 * await client.put('Cartridges/v1/app_custom/file.js', content);
 * ```
 */
export class WebDavClient {
  /**
   * Creates a new WebDAV client.
   *
   * @param hostname - The B2C Commerce instance hostname
   * @param auth - Authentication strategy to use
   */
  constructor(hostname: string, auth: AuthStrategy) {}
}

Function Documentation

/**
 * Deploys cartridges to a B2C Commerce instance.
 *
 * Discovers cartridges in the specified path, creates a ZIP archive,
 * and uploads via WebDAV.
 *
 * @param instance - The B2C instance to deploy to
 * @param cartridgePath - Path containing cartridge directories
 * @param options - Deployment options
 * @returns Deployment result with uploaded cartridges
 *
 * @example
 * ```typescript
 * const result = await deployCartridges(instance, './cartridges', {
 *   include: ['app_storefront'],
 * });
 * console.log(result.cartridges);
 * ```
 *
 * @throws {DeploymentError} If deployment fails
 */
export async function deployCartridges(
  instance: B2CInstance,
  cartridgePath: string,
  options?: DeployOptions,
): Promise<DeployResult> {}

Type Documentation

/**
 * Configuration for OAuth authentication.
 */
export interface OAuthConfig {
  /** OAuth client ID */
  clientId: string;

  /** OAuth client secret */
  clientSecret: string;

  /** OAuth scopes to request */
  scopes?: string[];
}

Building Documentation

# Generate API docs from JSDoc
pnpm run docs:api

# Start dev server (includes API generation)
pnpm run docs:dev

# Build static site
pnpm run docs:build

# Preview built site
pnpm run docs:preview

Hosted Builds

.github/workflows/docs-preview.yml publishes unreleased docs from main at /pr-next/ on the preview host after every push. PR previews use /pr-<number>/ and are removed when the PR closes. Both build packages and the docs site; neither refreshes published release history from GitHub.

To rebuild manually, dispatch the workflow with no inputs for main, or set pr_number for a PR (including drafts). The workflow always resolves the source commit explicitly. The preview URL is recorded in the workflow summary; PRs also receive a preview comment. Production docs remain tied to stable release tags through deploy-docs.yml.

Agent Discovery on the Docs Site

docs/public/llms.txt is a curated agent entrypoint: CLI installation via npx, MCP/plugin setup, installed docs and skills tools, then selected Markdown references. Keep installation first and details terse; do not expand it into an exhaustive index or llms-full.txt bundle. Update it when setup or core capabilities change.

The footer and HTML rel="describedby" link expose llms.txt. Each page has a rel="alternate" Markdown link matching View as Markdown. Source Markdown is exported at its existing path, with shared includes expanded; directory pages use index.md. Links in llms.txt are relative to its location so stable, dev, and PR previews stay self-contained. Check those references against built files.

Release Notes

/releases/ combines published product changes with optional authored Markdown. Documentation-only releases and Documentation sections do not appear. Shared changes appear once with product labels; dependency updates are expandable. Group changes with the same product labels into unordered lists. Authored highlights remain prose above the generated notes. Use one date heading per day for the right-side outline, followed by Older Releases. Keep the outline aligned with product filters. Do not show a total update count: this page covers a selected period, not the entire release history. Keep authored highlights human-facing: outcomes, relevant limits, and upgrade actions. Do not copy CI mechanics or package plumbing into public prose.

• docs/.vitepress/releases/seed.json is the checked-in history since July 1, 2026, including related IDE and skills artifacts. Local and PR builds need no GitHub access. Change the starting point deliberately with pnpm --filter @salesforce/b2c-dx-docs run releases:refresh --seed-since YYYY-MM-DD.
• pnpm --filter @salesforce/b2c-dx-docs run releases:refresh uses authenticated gh to fetch stable product releases since that date into ignored live.json. Production runs this on every deployment, including doc-only releases. A failed refresh stops deployment. Removing local live.json restores the seed view.

• Add optional entries under docs/releases/_entries/<slug>.md:

  ---
  title: Introducing SCAPI code mode
  date: 2026-09-15
  products: [mcp]
  release: '@salesforce/b2c-dx-mcp@3.0.0'
  ---

  Follow with ordinary Markdown (no Vue/HTML components). With release, the entry adds a highlight above that release's generated changes; it stays hidden until the exact tag is available. Omit release for a standalone announcement. Product IDs: cli, ide, mcp, skills, mrt, sdk. SDK is secondary. The VitePress dev server watches entry edits; restart it after an invalid entry.

• Release rendering runs when VitePress loads its config, including direct vitepress build. Generated partials and Markdown exports are ignored; never hand-edit them. All notes are present in static HTML, local search, and the /releases/index.md export. Filters enhance the static content in the browser.
• Run pnpm --filter @salesforce/b2c-dx-docs run test:releases for parser, merge, editorial, offline-generation, and strict TypeScript checks. The .ts scripts run via tsx and use the repository's shared ESLint rules in lint:agent. Run pnpm --filter @salesforce/b2c-dx-docs run format:releases after edits. Also check the page on desktop and mobile, product filters, Markdown export, and a build with a subpath base.

Guides Search Corpus (b2c docs)

Separate from the Vitepress site above, the SDK bundles a search index that powers b2c docs search / docs read and the MCP docs_* tools. For the Developer Center guides corpus, only lightweight metadata is bundled (packages/b2c-tooling-sdk/data/guides/index.json), including immediate parent and child relationships derived from the published TOCs; the page content itself is fetched live from developer.salesforce.com at read time.

Internal tooling corpus (tooling)

The internal tooling corpus is generated from every Markdown page under docs/guide/, docs/cli/, docs/mcp/, and docs/vscode-extension/. Do not maintain a per-page allowlist for these repository-owned docs. The generator discovers new pages automatically and skips only asset-folder README.md files and frontmatter redirects:

pnpm --filter @salesforce/b2c-tooling-sdk run generate:tooling-index

CI runs check:tooling-index and fails when the committed index is stale. The release workflow and SDK prepack regenerate the index as defense in depth. Because data/tooling/index.json ships in @salesforce/b2c-tooling-sdk, changes to the generated corpus require an SDK changeset.

Regenerate the index from a local Developer Center source directory containing the category directories (for example, b2c-commerce/guides/):

GUIDES_CONTENT_DIR=/path/to/guide-content \
  pnpm --filter @salesforce/b2c-tooling-sdk run generate:guides-index

Only TOC-referenced pages are indexed. The generator (scripts/generate-guides-index.ts) skips any .md file not linked from a guide table-of-contents YAML (e.g. b2c-commerce/guides/index.yml). Orphan files (old pages consolidated elsewhere, drafts) are not published by the docs site, so indexing them would yield dead 404 URLs.

Salesforce Help corpus (help-admin / help-merchant)

A second prose corpus covers help.salesforce.com Business Manager administration and merchandising content, sourced from a local DITA directory containing maps/ and topics/. Set HELP_CONTENT_DIR to that directory. Unlike the guides, Help content is JS-rendered with no fetchable source, so the DITA is converted to Markdown and packed into the committed docs/help-content.tar.gz (extracted into the docs site at build time), with the lightweight index at packages/b2c-tooling-sdk/data/help/index.json:

HELP_CONTENT_DIR=/path/to/help-content \
  pnpm --filter @salesforce/b2c-tooling-sdk run generate:help-corpus

Keep source checkout locations and authentication settings in local environment configuration. Do not include source repository names, hosts, or personal checkout paths in tracked files or release notes.

Source provenance (delta tracking)

Both prose indexes record the upstream git commit they were generated from in a source block at the top of index.json:

"source": { "sha": "<full-sha>", "committedAt": "<ISO date>", "ref": "<branch>" }

Only these opaque values are stored — deliberately no repository URL — so no internal host name or maintainer credential lands in the published package (captured by scripts/source-provenance.ts).

Corpora sourced from the DWAPP archive (Script API, XSD schemas, job steps) are not git-backed, so instead of source they record the platform release: data/script-api/index.json and data/xsd/index.json carry a platformDocVersion (e.g. "DWAPP 26.8"), and data/job-steps/job-steps.json records the same under provenance.platformDocVersion. The version is parsed from the archive by refresh:docs-data and forwarded to generate:docs-index <version>; running that generator manually with no arg preserves whatever version is already committed (it never silently drops it).

When XSD files are added or removed, update packages/b2c-vs-extension/resources/xsd-mappings.json so every schema is mapped, bundled as an import, or explicitly skipped. Run pnpm run build to verify downstream consumers; SDK-only tests do not exercise this check.

Use the recorded SHA to see exactly what changed upstream before a refresh. In the relevant local clone:

# What guide content changed since the committed guides index was generated?
git -C "$GUIDES_CONTENT_DIR" log --oneline <sha>..HEAD -- .

# What Help content changed since the committed help index was generated?
git -C "$HELP_CONTENT_DIR" log --oneline <sha>..HEAD -- .

An empty log means the corpus is already current with that clone; otherwise the listed commits are the delta a regeneration will pick up. Always re-run enrich:docs (missing-only) after a guides refresh so new pages get summaries/keywords, then re-run generate:guides-index to merge them.

The enrichment script defaults to claude-haiku-4-5 (override with DOCS_ENRICH_MODEL) and requires ANTHROPIC_API_KEY; without a key it skips enrichment. It only enriches Developer Center guides. Help summaries come from DITA <shortdesc> and are refreshed with the source content.

Audit published guide entries without a summary after each refresh. The missing-only mode does not update summaries for changed pages, and the sidecar currently records neither source hashes nor model/run metadata. The guides index's source.sha dates index generation, not LLM enrichment. Compare guide source changes against the source snapshot at the last enrichment update to identify potentially stale summaries; use enrich:docs --full when a full rerun is warranted. The enrichment script scans all guide Markdown, including unpublished orphan pages, so its work count can exceed the published index's missing-summary count.

Verifying links (local only)

After regenerating, verify every URL in the index resolves:

pnpm --filter @salesforce/b2c-tooling-sdk run check:guides-links

Run this from a normal network / browser-capable connection. It is not a CI job: the docs CDN (Cloudflare) blanket-403s datacenter IPs, so it verifies nothing from GitHub-hosted runners (every URL comes back blocked). The script fails only on 404/410 (definitively gone); it treats 403/429/5xx/network errors as inconclusive and, if a run is dominated by them, warns and passes rather than reporting false failures. Always run it locally after touching the guides index.

TypeDoc Configuration

Located in typedoc.json:

{
  "entryPoints": [
    "packages/b2c-tooling-sdk/src/auth/index.ts",
    "packages/b2c-tooling-sdk/src/clients/index.ts",
    "packages/b2c-tooling-sdk/src/operations/code/index.ts"
  ],
  "out": "docs/api",
  "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
  "exclude": ["**/*.generated.ts"]
}

When adding new SDK modules, add their barrel file to entryPoints.

VitePress Configuration

Edit docs/.vitepress/config.mts for navigation and sidebar routing. Update both sidebar selection and top-nav activeMatch when moving a page between sections. Use existing theme components in docs/.vitepress/theme/ rather than duplicating styles or installation content.

Claude Code Skills (Plugin)

The skills/b2c-cli/skills/ directory contains skills that teach Claude about using the CLI commands. These are distributed via the plugin.

When to update:

• New CLI commands added
• Existing commands changed
• New usage patterns

Skill format:

---
name: b2c-<topic>
description: Brief description
---

# B2C <Topic> Skill

Overview of the command topic.

## Examples

### <Use Case>

\`\`\`bash

# Comment explaining the command

b2c <topic> <command> [args] [flags]
\`\`\`

### <Another Use Case>

\`\`\`bash
b2c <topic> <command> --flag value
\`\`\`

Documentation Update Checklist

When Adding a CLI Command

1. Update docs/cli/<topic>.md with command documentation
2. Update docs/.vitepress/config.mts sidebar if new topic
3. Update skills/b2c-cli/skills/b2c-<topic>/SKILL.md with examples

When Adding a Guide

1. Add the page to the matching group in the docs/.vitepress/config.mts sidebar
2. Add it to the same section of the All Guides index (docs/guide/workflows.md)
3. Regenerate the tooling index (pnpm --filter @salesforce/b2c-tooling-sdk run generate:tooling-index)

When Adding an SDK Module

1. Write module-level JSDoc in barrel file
2. Write JSDoc for all public classes, functions, types
3. Add entry point to typedoc.json if new module
4. Run pnpm run docs:api to regenerate

When Changing the Python SDK Public API

1. Update the sphinx-style docstrings in python/b2c-tooling-sdk/src/
2. Add new barrel modules to PAGES in scripts/generate_api_docs.py
3. Run make api-docs in python/b2c-tooling-sdk/ and commit docs/python/api/
4. Update docs/python/*.md guides if usage changed

When Changing CLI Behavior

1. Update affected examples in docs/cli/*.md
2. Update affected examples in skills/b2c-cli/skills/*/SKILL.md
3. Update guide pages if conceptual changes

When Adding Configuration Options

1. Update docs/guide/configuration.md
2. Update relevant CLI command docs with new flags
3. Update skills with new flag examples

Navigation Structure

Administrator/operator tasks live in Guides under Operations & Administration. The Operations guide introduces shipped runbooks with business outcomes, example prompts, required access, and useful escalation (including Salesforce Support). Organize it around user capabilities, not individual skills or runbook names. Keep skill selection/procedures agent-facing; a future cross-plugin skill catalog will own individual skill listings. Collection names belong in installation context. Keep agent procedures in skills/b2c-ops, not the human guide. Link new supported tasks from the homepage and MCP where relevant; do not present planned merchant workflows as available. Runbook installation follows the same Agent Skills/MCP patterns, with MCP bundling preferred and standalone skills still supported.

• Docs (/): shared toolkit sidebar for getting started, CLI overview, IDE Extension, and AI Tools. AI Tools contains MCP and Agent Skills; plugin setup belongs on those pages, not a separate Plugins landing page.
• MCP (/mcp/): overview and installation together; children are Configuration, MCP Tools, and Security and Access, in that order.
• Guides (/guide/workflows): task guides with their own expanded groups.
• Reference (/cli/): CLI commands with their own sidebar.
• SDKs: TypeScript SDK (/api/; TypeDoc generates its reference navigation), Python SDK (/python/; guides sidebar plus generated docs/python/api/sidebar.json), and external links to the Script API and B2C Commerce API references.

Keep sidebar labels aligned with page titles; concise entries such as MCP and Introduction are intentional. Preserve published URLs/anchors when reorganizing content. Unpublished branch-only pages need no redirect when removed.

Style Guidelines

• Use code blocks with language hints (bash, typescript)
• Include practical examples for every command/function
• Keep flag tables consistent across command docs
• Use relative links for internal references in the docs site. Agent skills differ: follow the skill reference rules in skills/README.md (skill-name references, Markdown doc URLs with docs IDs)
• Avoid emojis unless specifically requested