Skip to content

Add B2C Commerce agent skills and docs commands #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
clavery wants to merge 11 commits into
base: main
Choose a base branch
from
Open

Add B2C Commerce agent skills and docs commands #34

clavery wants to merge 11 commits into from
+164,194 −73

Conversation

@clavery
Copy link
Collaborator

@clavery clavery commented Jan 10, 2026 •
edited
Loading

Note this PR is extremely huge because it contains a copy of the script API docs, XSDs and other derived documentation

Summary

This PR adds 14 user-facing agent skills for B2C Commerce development guidance, plus a developer skill for authoring new skills. All XML examples validated against official XSD schemas.

Additionally, this PR adds a new docs command topic to the B2C CLI for searching and reading bundled Script API documentation and XSD schemas.

Developer Skills (plugins/b2c/skills/)

Skill Description
b2c-custom-job-steps Task and chunk-oriented job step creation with steptypes.json
b2c-controllers SFRA server module and classic controller patterns
b2c-isml ISML template tags, expressions, and location constraints
b2c-forms Form XML definitions and SFRA form handling
b2c-localization Resource bundles, locale fallback, and i18n patterns
b2c-business-manager-extensions BM menu items, actions, and form extensions
b2c-page-designer Page and component meta definitions and scripts
b2c-metadata System object extensions, custom objects, site preferences
b2c-webservices HTTP/FTP/SOAP service integrations with Service Framework
b2c-logging Script logging with Logger, Log, and LogNDC classes
b2c-custom-caches Custom cache definition and usage with CacheMgr/Cache classes
b2c-hooks Hook registration, HookMgr, OCAPI/SCAPI hooks, system hooks

CLI Skills (plugins/b2c-cli/skills/)

Skill Description
b2c-site-import-export Site archive import/export using b2c job commands
b2c-webdav WebDAV operations with comprehensive log file reference
b2c-docs Search and read bundled Script API documentation and XSD schemas

Contributor Skills (.claude/skills/)

Skill Description
skill-authoring Guide for creating and maintaining user-facing agent skills

New CLI Commands: docs Topic

New commands for accessing bundled B2C Commerce documentation offline:

Command Description
b2c docs search <query> Fuzzy search Script API documentation
b2c docs read <class> Read documentation for a class (renders markdown in terminal)
b2c docs schema [name] Read XSD schema files for import/export formats
b2c docs download <dir> Download fresh documentation from a B2C instance

Features:

  • 519 bundled Script API markdown files
  • 54 bundled XSD schema files
  • Fuzzy search with Fuse.js
  • Terminal markdown rendering with marked-terminal
  • --raw flag for piping markdown output
  • --json flag for programmatic access
  • --list flag to enumerate all available docs/schemas

Documentation

  • Updated docs/guide/agent-skills.md to describe plugins generally instead of listing every skill
  • Links to GitHub directories for browsing available skills
  • Added Cursor and VS Code documentation links for skills configuration

Validation

All skills validated against:

  • Official B2C Commerce documentation (commerce-cloud-docs)
  • XSD schemas from dwre-tools/dwredocs/xsd/
  • Real metadata export examples
  • Script API documentation (sfcc-b2c-offline-docs)

Key XSD Validations Applied

  1. steptypes.json - Must be at cartridge root, not inside cartridge/
  2. preferences.xml - Uses <custom-preferences>/<preference> structure (not <custom-preference>)
  3. Value definitions - Uses <display> element (not <display-value>)
  4. Custom object data - Uses <object-attribute> directly (not <custom-attributes>/<custom-attribute>)
  5. services.xml - Validated against services.xsd (2014-09-26 namespace)
  6. ISML tags - Location constraints documented (<isprint> only in body, etc.)

Skill Highlights

b2c-hooks (new)

  • Hook registration via package.json and hooks.json
  • HookMgr API for calling and checking hooks
  • OCAPI/SCAPI hooks (before/after/modifyResponse patterns)
  • System hooks (calculate, payment, order)
  • Custom extension points
  • Passing data between hooks via request.custom
  • Remote includes in modifyResponse hooks
  • Custom properties (c_ prefix) in API responses
  • SCAPI vs OCAPI detection with request.isSCAPI()

b2c-custom-caches

  • Cache definition in caches.json with package.json reference
  • CacheMgr and Cache Script API classes
  • get(key, loader) pattern for automatic population
  • Scoped cache keys for site/catalog/locale separation
  • Limitations: 20MB memory, 128KB entry size, no cross-server sync

b2c-webservices

  • Service Framework: LocalServiceRegistry, callbacks, Result object, error handling
  • HTTP Services: REST patterns, Basic/OAuth/API Key auth, multipart, caching, mTLS
  • FTP/SFTP Services: File operations, multi-operation patterns, workflows
  • SOAP Services: WSDL stubs, WS-Security, WSUtil, complex types
  • Services XML: Import/export format for credentials, profiles, and service configs

b2c-logging

  • Logger class: Static methods for quick logging
  • Log class: Instance methods with categories and custom file prefixes
  • LogNDC: Nested Diagnostic Context for request tracing
  • Log Files: Types, locations, retention, storage limits, formats

b2c-webdav (updated)

  • Log file naming patterns and types
  • Custom and system log file reference
  • Log retention and archive locations
  • Common log query examples

skill-authoring (contributor skill)

  • Skill structure and SKILL.md format
  • Progressive disclosure principles
  • Token budgets and context efficiency
  • Patterns learned from B2C skill development
  • References agentskills.io as canonical source

Test Plan

  • Verify skills are loaded by Claude Code when working in B2C Commerce projects
  • Test XML examples can be imported without schema validation errors
  • Test b2c docs search ProductMgr returns relevant results
  • Test b2c docs read ProductMgr renders documentation in terminal
  • Test b2c docs schema catalog displays XSD schema
  • Review skill content accuracy against official documentation

@clavery
Add B2C Commerce agent skills with XSD-validated XML examples
0e2c956 
Add 9 agent skills for B2C Commerce development guidance:

**Developer Skills (plugins/b2c/skills/):**
- b2c-custom-job-steps: Task and chunk-oriented job step creation
- b2c-controllers: SFRA and classic controller patterns
- b2c-isml: ISML template tags and expressions
- b2c-forms: Form XML definitions and SFRA handling
- b2c-localization: Resource bundles and locale support
- b2c-business-manager-extensions: BM menu items and extensions
- b2c-page-designer: Page and component development
- b2c-metadata: System object extensions and custom objects

**CLI Skills (plugins/b2c-cli/skills/):**
- b2c-site-import-export: Site archive import/export with CLI

**Validation against official sources:**
- Validated against official B2C Commerce documentation
- XML examples validated against XSD schemas from dwre-tools
- Key fixes applied:
  - steptypes.json location (cartridge root, not inside cartridge/)
  - preferences.xml structure (custom-preferences/preference)
  - Value definitions use <display> not <display-value>
  - Custom object data uses <object-attribute> not <custom-attribute>
  - ISML tag location constraints documented
  - Parameter validation attributes for job steps
@clavery clavery changed the title Add B2C Commerce agent skills with XSD-validated XML examples Add B2C Commerce agent skills Jan 10, 2026
@clavery
Add b2c-webservices skill for web service integrations
0bb9a29 
Comprehensive skill covering:
- Service Framework overview and components
- LocalServiceRegistry.createService() pattern
- Service callbacks (createRequest, parseResponse, execute, etc.)
- Result object handling and error states
- Log filtering for sensitive data

Reference documentation includes:
- HTTP-SERVICES.md: REST API patterns, authentication (Basic, OAuth, API keys),
  multipart uploads, file downloads, response caching, mTLS
- FTP-SERVICES.md: SFTP operations (list, get, put, delete), multi-operation
  patterns, file processing workflows
- SOAP-SERVICES.md: WSDL stubs, WS-Security, WSUtil, custom headers,
  complex types, MTOM attachments
- SERVICES-XML.md: XML import/export format for service configurations,
  credentials, profiles, and services
@clavery
Add b2c-logging skill for script logging
38eb827 
Comprehensive skill covering:
- Logger class (static methods for quick logging)
- Log class (instance methods with categories)
- Log levels: debug, info, warn, error, fatal
- Custom named log files with file prefix
- LogNDC for nested diagnostic context
- Message formatting with Java MessageFormat syntax
- Best practices for logging

Reference documentation includes:
- LOG-FILES.md: Log file types (custom and system), WebDAV locations,
  retention periods, storage limits, quota logs, security logs,
  import/export logs, and log entry formats
@clavery
Update b2c-webdav skill with comprehensive log file reference
f5dba0c 
Added detailed log file documentation:
- Log file naming patterns (<type>-<hostname>-appserver-<date>.log)
- Custom log file types (customdebug, custominfo, customwarn, customerror, customfatal)
- Custom named log files (custom-<prefix>-<hostname>-appserver-<date>.log)
- System log file types (error, warn, jobs, quota, deprecation, etc.)
- Log retention and archive locations (log_archive/ for compressed logs)
- Security logs and import/export logs
- Common log query examples using grep
@clavery
Add skill-authoring skill for creating user-facing skills
9c61f5f 
Meta-skill documenting how to create and maintain agent skills:
- Skill structure (SKILL.md + optional directories)
- Frontmatter metadata requirements
- Progressive disclosure principles (metadata → instructions → references)
- Token budgets and context efficiency
- Optional directories (scripts/, references/, assets/)
- File reference patterns
- Skill categories (developer vs user-facing)
- Writing effective skills checklist

Reference documentation includes:
- PATTERNS.md: Patterns learned from B2C skills including content
  organization, effective tables, code examples, XML validation,
  progressive complexity, common skill templates, and anti-patterns

Canonical reference: https://agentskills.io/home
@clavery
Update agent-skills documentation to be more maintainable
e34f596 
- Describe plugins generally instead of listing every individual skill
- Remove skill tables that would need constant updates as skills are added
- Link to GitHub directories for browsing available skills
- Add Cursor docs link for skills configuration
- Add VS Code Agent Skills documentation link
- Update usage examples to include logging and web services
@clavery
Add b2c-custom-caches skill for custom cache usage
6a4b18e 
Covers:
- When to use custom caches (expensive calculations, external responses, config)
- Defining caches in caches.json with package.json reference
- CacheMgr and Cache Script API classes
- get(key, loader) pattern for automatic population
- Scoped cache keys for site/catalog/locale separation
- Limitations (20MB memory, 128KB entry size, no cross-server sync)
- Common patterns for external APIs, calculations, and configuration
- Troubleshooting guide

Content validated against official documentation and Script API reference.
@clavery
Add b2c-hooks skill for hook registration and customization
29b970a 
Covers:
- Hook registration via package.json and hooks.json
- HookMgr API for calling and checking hooks
- Status object for controlling hook flow
- OCAPI/SCAPI hooks (before/after/modifyResponse patterns)
- System hooks (calculate, payment, order)
- Custom extension points
- Passing data between hooks via request.custom
- Remote includes in modifyResponse hooks
- Custom properties (c_ prefix) in API responses
- Error handling and circuit breaker
- SCAPI vs OCAPI detection with request.isSCAPI()

Reference files:
- OCAPI-SCAPI-HOOKS.md: API hook patterns by resource
- SYSTEM-HOOKS.md: Calculate, payment, order hooks

Content validated against official documentation and Script API reference.
@clavery
Add docs command topic for Script API documentation and XSD schemas
18a2425 
New CLI commands:
- `b2c docs search <query>` - Fuzzy search bundled Script API documentation
- `b2c docs read <query>` - Read documentation with terminal markdown rendering
- `b2c docs schema <query>` - Read XSD schema files with fuzzy matching
- `b2c docs download <output>` - Download docs from B2C instance

SDK changes:
- Add operations/docs module with search, read, and download functions
- Bundle 519 Script API markdown files and 54 XSD schemas in data/
- Use createRequire for robust path resolution to bundled data
- Export docs operations from main SDK entry point

Also adds b2c-docs skill for agent usage examples.
@clavery clavery marked this pull request as ready for review January 10, 2026 22:53
@clavery clavery changed the title Add B2C Commerce agent skills Add B2C Commerce agent skills and docs commands Jan 10, 2026
@clavery
Fix eslint import/namespace error for marked-terminal
fe8cfb3 
Use createRequire to load the marked-terminal CJS module, avoiding
eslint-plugin-import parser issues that caused inconsistent behavior
between local and CI environments.
@clavery
Fix eslint CI error for marked-terminal import
3f7cd4b 
- Use standard ESM named import for marked-terminal
- Disable import/namespace rule for that line (parser issue with CJS)
- Set reportUnusedDisableDirectives to warn to handle environment
  differences where import/namespace may or may not fire
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@yhsieh1 yhsieh1 Awaiting requested review from yhsieh1

@patricksullivansf patricksullivansf Awaiting requested review from patricksullivansf

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@clavery