sfcc-dev-mcp 1.0.15 → 1.0.19

package/.github/skills/skill-authoring/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: skill-authoring
+description: Guide for creating and maintaining user-facing agent skills
+---
+
+# Skill Authoring Guide
+
+This skill guides you through creating user-facing agent skills. For the canonical reference, see [agentskills.io](https://agentskills.io/home).
+
+## Skill Structure
+
+A skill is a folder containing a `SKILL.md` file with metadata and instructions:
+
+```
+my-skill/
+├── SKILL.md          # Required: instructions + metadata
+├── scripts/          # Optional: executable code
+├── references/       # Optional: additional documentation
+└── assets/           # Optional: templates, resources
+```
+
+## SKILL.md Format
+
+### Required Frontmatter
+
+```yaml
+---
+name: skill-name
+description: Brief description of what the skill does
+---
+```
+
+- **name**: Unique identifier (lowercase, hyphens)
+- **description**: One-line summary (loaded at startup for all skills - a maximum of 1000 characters)
+
+### Instructions Body
+
+The body contains markdown instructions that tell the agent how to perform the task.
+
+```markdown
+---
+name: my-skill
+description: Does something useful
+---
+
+# Skill Title
+
+Brief overview of what this skill helps accomplish.
+
+## When to Use
+
+Describe scenarios when this skill applies.
+
+## How to Use
+
+Step-by-step instructions or patterns.
+
+## Examples
+
+Concrete examples demonstrating usage.
+
+## Reference
+
+- [Detailed Reference](references/REFERENCE.md) - Link to additional docs
+```
+
+## Progressive Disclosure
+
+Structure skills for efficient context usage:
+
+| Layer | Token Budget | When Loaded |
+|-------|--------------|-------------|
+| Metadata | ~100 tokens | At startup (all skills) |
+| Instructions | < 5000 tokens | When skill activated |
+| References | As needed | On demand |
+
+### Guidelines
+
+1. **Keep SKILL.md under 500 lines** - Move detailed content to references
+2. **Front-load key information** - Put most important patterns first
+3. **Use tables for quick reference** - Easy to scan
+4. **Link to references** - Don't inline everything
+
+## Optional Directories
+
+### scripts/
+
+Executable code that agents can run:
+
+```
+scripts/
+├── validate.sh       # Validation script
+├── generate.py       # Code generator
+└── setup.js          # Setup helper
+```
+
+Scripts should:
+- Be self-contained or document dependencies
+- Include helpful error messages
+- Handle edge cases gracefully
+
+### references/
+
+Additional documentation loaded on demand:
+
+```
+references/
+├── PATTERNS.md       # Common patterns
+├── API.md            # API reference
+└── EXAMPLES.md       # Extended examples
+```
+
+Keep individual reference files focused. Smaller files = less context usage.
+
+### assets/
+
+Static resources:
+
+```
+assets/
+├── template.xml      # File templates
+├── schema.json       # Schemas
+└── diagram.png       # Visual aids
+```
+
+## File References
+
+Use relative paths from the skill root:
+
+```markdown
+See [the reference guide](references/REFERENCE.md) for details.
+
+Run the setup script:
+scripts/setup.sh
+```
+
+Keep references one level deep. Avoid deeply nested chains.
+
+## Skill Categories
+
+### Developer Skills (`.claude/skills/`)
+
+Skills for contributors working on this codebase:
+
+- Command development patterns
+- Testing approaches
+- API client patterns
+- Documentation standards
+
+### User-Facing Skills (`plugins/*/skills/`)
+
+Skills for users of the tool:
+
+- CLI command usage
+- Platform-specific patterns (B2C Commerce)
+- Integration guides
+
+## Writing Effective Skills
+
+### 1. Start with the User's Goal
+
+```markdown
+## Overview
+
+This skill helps you [accomplish X] by [doing Y].
+```
+
+### 2. Provide Quick Reference Tables
+
+```markdown
+| Command | Description |
+|---------|-------------|
+| `cmd1`  | Does X      |
+| `cmd2`  | Does Y      |
+```
+
+### 3. Show Concrete Examples
+
+```markdown
+## Examples
+
+### Basic Usage
+
+\`\`\`bash
+b2c command --flag value
+\`\`\`
+
+### Advanced Usage
+
+\`\`\`bash
+b2c command --complex-flag
+\`\`\`
+```
+
+### 4. Explain When NOT to Use
+
+```markdown
+## When NOT to Use
+
+- Scenario A (use skill-x instead)
+- Scenario B (manual approach better)
+```
+
+### 5. Link to Authoritative Sources
+
+Reference official documentation rather than duplicating it:
+
+```markdown
+## Reference
+
+For complete API documentation, see [Official Docs](https://example.com/docs).
+```
+
+## Validation Checklist
+
+Before publishing a skill:
+
+- [ ] Frontmatter has `name` and `description`
+- [ ] SKILL.md under 400 lines
+- [ ] Key information appears early
+- [ ] Examples are concrete and runnable
+- [ ] Reference links are valid
+- [ ] No deeply nested reference chains
+- [ ] Tested with target agent
+
+## Detailed Reference
+
+- [Patterns and Examples](references/PATTERNS.md) - Patterns from B2C skills

package/.github/skills/skill-authoring/references/PATTERNS.md

@@ -0,0 +1,384 @@
+# Skill Authoring Patterns
+
+Patterns and lessons learned from creating B2C Commerce skills.
+
+## Content Organization
+
+### Main SKILL.md Structure
+
+Effective skills follow this structure:
+
+```markdown
+---
+name: skill-name
+description: One-line description
+---
+
+# Skill Title
+
+Brief overview (2-3 sentences).
+
+## Overview / Quick Reference
+
+Tables or bullet points for quick scanning.
+
+## Core Concepts
+
+Key information the user needs to understand.
+
+## Patterns / How To
+
+Step-by-step instructions with examples.
+
+## Examples
+
+Complete, runnable examples.
+
+## Detailed References
+
+Links to reference files for deep dives.
+
+## Script API Classes (if applicable)
+
+Table of relevant classes/methods.
+```
+
+### Reference File Structure
+
+Reference files should be focused on one topic:
+
+```markdown
+# Topic Reference
+
+Brief intro.
+
+## Subtopic A
+
+Details with examples.
+
+## Subtopic B
+
+Details with examples.
+
+## Complete Example
+
+Full working example if applicable.
+```
+
+## Effective Tables
+
+Tables provide quick reference without consuming much context:
+
+### Command Reference Table
+
+```markdown
+| Command | Description |
+|---------|-------------|
+| `b2c cmd1` | Does X |
+| `b2c cmd2` | Does Y |
+```
+
+### Parameter Table
+
+```markdown
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | The item name |
+| `count` | int | No | Number of items |
+```
+
+### Feature Matrix Table
+
+```markdown
+| Feature | Supported | Notes |
+|---------|-----------|-------|
+| Feature A | Yes | Full support |
+| Feature B | Partial | Only in v2+ |
+| Feature C | No | Use workaround |
+```
+
+## Code Examples
+
+### Inline Code
+
+For short snippets, use inline code:
+
+```markdown
+Use `Logger.getLogger('category')` to get a logger instance.
+```
+
+### Code Blocks
+
+For complete examples, use fenced code blocks with language:
+
+````markdown
+```javascript
+var Logger = require('dw/system/Logger');
+var log = Logger.getLogger('checkout');
+log.info('Order {0} placed', orderNo);
+```
+````
+
+### Multi-file Examples
+
+When showing related files, use headers:
+
+````markdown
+**package.json:**
+```json
+{ "name": "my-package" }
+```
+
+**index.js:**
+```javascript
+module.exports = function() {};
+```
+````
+
+## XML Examples
+
+When documenting XML formats:
+
+1. **Always validate against XSD schemas** if available
+2. **Show namespace declarations** in first example
+3. **Use realistic but simple data**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<root xmlns="http://example.com/schema/2024">
+    <element attribute="value">content</element>
+</root>
+```
+
+## Referencing Official Documentation
+
+### When to Reference
+
+- API details that may change
+- Complete specification documents
+- Platform-specific configurations
+
+### How to Reference
+
+```markdown
+For complete API documentation, see the [Official Guide](https://docs.example.com).
+
+The `Logger` class is documented in the [Script API Reference](https://docs.example.com/api/Logger).
+```
+
+### When to Inline
+
+- Frequently used patterns
+- Information not easily found in docs
+- Synthesized knowledge from multiple sources
+
+## Progressive Complexity
+
+Structure content from simple to complex:
+
+### Basic Pattern First
+
+```markdown
+## Basic Usage
+
+```javascript
+Logger.info('Simple message');
+```
+```
+
+### Then Add Complexity
+
+```markdown
+## With Parameters
+
+```javascript
+Logger.info('Order {0} for customer {1}', orderNo, customerId);
+```
+```
+
+### Finally Show Advanced Cases
+
+```markdown
+## Custom Log Files
+
+```javascript
+var log = Logger.getLogger('prefix', 'category');
+log.info('Goes to custom-prefix-*.log');
+```
+```
+
+## Common Skill Patterns
+
+### CLI Command Skill
+
+```markdown
+---
+name: tool-command
+description: Guide for using the tool command
+---
+
+# Tool Command
+
+Brief description of what the command does.
+
+## Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `tool cmd1` | Does X |
+| `tool cmd2` | Does Y |
+
+## Examples
+
+### Basic Usage
+
+\`\`\`bash
+tool command --flag value
+\`\`\`
+
+### Common Workflows
+
+\`\`\`bash
+# Workflow description
+tool step1
+tool step2
+\`\`\`
+```
+
+### API/Framework Skill
+
+```markdown
+---
+name: framework-feature
+description: Guide for implementing feature with framework
+---
+
+# Feature Name
+
+Overview of the feature and when to use it.
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| Concept A | What it is |
+| Concept B | What it is |
+
+## Basic Pattern
+
+\`\`\`javascript
+// Basic implementation
+\`\`\`
+
+## Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| setting1 | value | What it does |
+
+## Detailed References
+
+- [Advanced Patterns](references/ADVANCED.md)
+- [Configuration Options](references/CONFIG.md)
+```
+
+### XML/Configuration Skill
+
+```markdown
+---
+name: config-format
+description: Guide for XML/config file format
+---
+
+# Configuration Format
+
+Overview of the configuration file.
+
+## File Structure
+
+\`\`\`
+project/
+├── config/
+│   └── settings.xml
+└── data/
+    └── values.xml
+\`\`\`
+
+## XML Schema
+
+\`\`\`xml
+<?xml version="1.0" encoding="UTF-8"?>
+<root xmlns="http://example.com/schema">
+    <!-- elements -->
+</root>
+\`\`\`
+
+## Element Reference
+
+| Element | Required | Description |
+|---------|----------|-------------|
+| `<elem1>` | Yes | Purpose |
+| `<elem2>` | No | Purpose |
+
+## Complete Example
+
+[Full example with realistic data]
+```
+
+## Skill Maintenance
+
+### Version Control
+
+- Keep skills in version control with the codebase
+- Update skills when features change
+- Review skills during code reviews
+
+### Testing Skills
+
+- Manually test instructions work as documented
+- Validate XML examples against schemas
+- Verify links to references work
+
+### Updating Skills
+
+When updating:
+1. Check if existing content is still accurate
+2. Add new content in appropriate section
+3. Update examples if APIs changed
+4. Verify reference links still work
+
+## Anti-Patterns to Avoid
+
+### Too Much Content in SKILL.md
+
+**Bad:** 2000+ line SKILL.md with everything inlined
+
+**Good:** < 500 line SKILL.md with references for details
+
+### Missing Context
+
+**Bad:**
+```markdown
+Use `cmd --flag` to do the thing.
+```
+
+**Good:**
+```markdown
+Use `cmd --flag` to enable feature X, which allows Y:
+
+\`\`\`bash
+cmd --flag value
+\`\`\`
+```
+
+### Outdated Examples
+
+**Bad:** Examples using deprecated APIs or old syntax
+
+**Good:** Examples validated against current documentation/schemas
+
+### Deeply Nested References
+
+**Bad:** SKILL.md → ref1.md → ref2.md → ref3.md
+
+**Good:** SKILL.md → ref1.md (one level deep)

package/.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: Setup Node.js
       uses: actions/setup-node@v5
@@ -36,7 +36,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: Setup Node.js
       uses: actions/setup-node@v5
@@ -61,7 +61,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     - name: Setup Node.js ${{ matrix.node-version }}
       uses: actions/setup-node@v5

package/.github/workflows/deploy-pages.yml

@@ -1,15 +1,15 @@
-name: Deploy GitHub Pages
+name: Deploy Docs (VitePress)
 
 on:
   push:
     branches: [ main ]
     paths:
-      - 'docs-site/**'
+      - 'docs-site-v2/**'
       - '.github/workflows/deploy-pages.yml'
   pull_request:
     branches: [ main ]
     paths:
-      - 'docs-site/**'
+      - 'docs-site-v2/**'
   workflow_dispatch:
 
 permissions:
@@ -26,28 +26,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Setup Node.js
         uses: actions/setup-node@v5
         with:
           node-version: '18'
-          cache: 'npm'
-          cache-dependency-path: './docs-site/package-lock.json'
 
-      - name: Install dependencies
-        working-directory: ./docs-site
-        run: npm ci
+      - name: Install docs dependencies
+        run: npm --prefix docs-site-v2 install
 
-      - name: Clean build directory
-        working-directory: ./docs-site
-        run: rm -rf dist
-
-      - name: Build site
-        working-directory: ./docs-site
-        run: npm run build
-        env:
-          NODE_ENV: production
+      - name: Build docs
+        run: npm --prefix docs-site-v2 run build
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
@@ -55,7 +45,7 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v4
         with:
-          path: ./docs-site/dist
+          path: ./docs-site-v2/.vitepress/dist
 
   deploy:
     environment:

package/.github/workflows/publish.yml

@@ -13,7 +13,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           fetch-depth: 0
@@ -90,7 +90,7 @@ jobs:
 
       - name: Install MCP Publisher
         run: |
-          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/latest/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
 
       - name: Update server.json version
         run: |
@@ -102,6 +102,9 @@ jobs:
           # Update server.json version to match the release
           jq --arg v "$VERSION" '.version = $v | .packages[0].version = $v' server.json > tmp && mv tmp server.json
 
+      - name: Validate server.json
+        run: npm run validate:server-json
+
       - name: Login to MCP Registry
         run: ./mcp-publisher login github-oidc