skill fixes

Author: clavery

.claude/skills/skill-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-authoring
-description: Guide for creating and maintaining user-facing agent skills
+description: Guide for creating and maintaining user-facing agent skills. Use when creating a new skill, adding a SKILL.md file, writing skill frontmatter/descriptions, organizing skill directories, or improving an existing skill's discoverability. Covers SKILL.md format, progressive disclosure, reference files, and writing effective descriptions.
 metadata:
   internal: true
 ---
@@ -9,6 +9,23 @@ metadata:
 
 This skill guides you through creating user-facing agent skills. For the canonical reference, see [agentskills.io](https://agentskills.io/home).
 
+## Before You Start
+
+Identify **2-3 concrete use cases** your skill should enable before writing anything.
+
+Good use case definition:
+```
+Use Case: [Name]
+Trigger: User says "[phrase 1]" or "[phrase 2]"
+Steps: 1. [action] 2. [action] 3. [action]
+Result: [What the user gets]
+```
+
+Ask yourself:
+- What does a user want to accomplish?
+- What domain knowledge or best practices should be embedded?
+- What multi-step workflows does this require?
+
 ## Skill Structure
 
 A skill is a folder containing a `SKILL.md` file with metadata and instructions:
@@ -21,32 +38,38 @@ my-skill/
 └── assets/           # Optional: templates, resources
 ```
 
+**Critical rules:**
+- File must be exactly `SKILL.md` (case-sensitive). No variations (`SKILL.MD`, `skill.md`).
+- Folder names must be **kebab-case**: `my-skill-name` (no spaces, no underscores, no capitals)
+- **No README.md** inside the skill folder. All documentation goes in SKILL.md or references/.
+
 ## SKILL.md Format
 
 ### Required Frontmatter
 
 ```yaml
 ---
 name: skill-name
-description: Brief description of what the skill does
+description: What it does. Use when user asks to [specific phrases].
 ---
 ```
 
-- **name**: Unique identifier (lowercase, hyphens)
-- **description**: Rich description for skill discovery (1-1024 characters)
+- **name**: kebab-case, must match folder name. No spaces or capitals.
+- **description**: 1-1024 characters. Must include BOTH what it does AND when to use it.
+
+**Security restrictions** — forbidden in frontmatter:
+- XML angle brackets (`<` or `>`) — frontmatter appears in Claude's system prompt
+- Skill names containing "claude" or "anthropic" (reserved)
 
 ### Writing Effective Descriptions
 
-The description field is **critical for skill discovery** by coding agents. It should include:
+The description is the **only discovery mechanism** — it determines whether Claude loads your skill. It should include:
 
-1. **What the skill does** - Core functionality
-2. **When to use it** - Trigger scenarios
-3. **Keywords** - Task-oriented phrases that help agents connect questions to skills
+1. **What the skill does** — Core functionality
+2. **When to use it** — Trigger conditions and phrases
+3. **Key capabilities** — Task-oriented phrases users might say
 
-**Format:**
-```yaml
-description: "[What it does]. Use when [scenarios]. Keywords/phrases."
-```
+**Structure:** `[What it does] + [When to use it] + [Key capabilities]`
 
 **Good examples:**
 ```yaml
@@ -56,204 +79,158 @@ description: Search and read B2C Commerce Script API documentation and XSD schem
 # Include common error scenarios
 description: View and debug B2C CLI configuration. Use when authentication fails, connection errors occur, wrong instance is used, or you need to verify dw.json settings, environment variables, or OAuth credentials.
 
-# Disambiguation helps agents choose the right skill
+# Disambiguation with negative triggers
 description: Run and monitor existing jobs, import/export site archives. Use when executing batch jobs, importing site data, or checking job status. For creating new job code, use b2c-custom-job-steps instead.
+
+# Negative triggers prevent over-triggering
+description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead).
 ```
 
 **Bad examples:**
 ```yaml
-# Too brief - no discovery keywords
-description: Using the b2c CLI for documentation
+# Too vague - no trigger phrases
+description: Helps with projects.
+
+# Missing triggers - only says what, not when
+description: Creates sophisticated multi-page documentation systems.
 
-# Action-oriented instead of problem-oriented
-description: Using the b2c CLI to search and read Script API documentation
+# Too technical, no user-oriented phrases
+description: Implements the Project entity model with hierarchical relationships.
 ```
 
 **Key insight:** Include **task-oriented phrases** ("generating URLs", "querying products") not just class names, since users ask about tasks they want to accomplish.
 
-### Instructions Body
+### Writing the Main Instructions
 
-The body contains markdown instructions that tell the agent how to perform the task.
+After the frontmatter, write instructions in Markdown. Recommended structure:
 
 ```markdown
----
-name: my-skill
-description: Does something useful. Use when [scenarios]. Keywords: [task phrases].
----
-
 # Skill Title
 
-Brief overview of what this skill helps accomplish.
-
-## Examples
-
-Concrete examples demonstrating usage.
-
-## Reference
-
-- [Detailed Reference](references/REFERENCE.md) - Link to additional docs
-```
-
-Note: The description frontmatter is the **only** discovery mechanism. "When to Use" sections in the body are not used for discovery. Put all discovery-relevant information in the description.
-
-## Progressive Disclosure
-
-Structure skills for efficient context usage:
+Brief overview (2-3 sentences).
 
-| Layer | Token Budget | When Loaded |
-|-------|--------------|-------------|
-| Metadata | ~100 tokens | At startup (all skills) |
-| Instructions | < 5000 tokens | When skill activated |
-| References | As needed | On demand |
+## Instructions
 
-### Guidelines
+### Step 1: [First Major Step]
+Clear explanation of what happens.
 
-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
+### Step 2: [Next Step]
+Continue with specifics.
 
-## Optional Directories
+## Examples
 
-### scripts/
+### Example 1: [Common scenario]
+User says: "[trigger phrase]"
+Actions: 1. [step] 2. [step]
+Result: [What the user gets]
 
-Executable code that agents can run:
+## Troubleshooting
 
-```
-scripts/
-├── validate.sh       # Validation script
-├── generate.py       # Code generator
-└── setup.js          # Setup helper
+### Error: [Common error message]
+**Cause:** [Why it happens]
+**Solution:** [How to fix]
 ```
 
-Scripts should:
-- Be self-contained or document dependencies
-- Include helpful error messages
-- Handle edge cases gracefully
-
-### references/
-
-Additional documentation loaded on demand:
+**Be specific and actionable:**
 
+Good:
 ```
-references/
-├── PATTERNS.md       # Common patterns
-├── API.md            # API reference
-└── EXAMPLES.md       # Extended examples
+Run `python scripts/validate.py --input {filename}` to check data format.
+If validation fails, common issues include:
+- Missing required fields (add them to the CSV)
+- Invalid date formats (use YYYY-MM-DD)
 ```
 
-Keep individual reference files focused. Smaller files = less context usage.
-
-### assets/
-
-Static resources:
-
+Bad:
 ```
-assets/
-├── template.xml      # File templates
-├── schema.json       # Schemas
-└── diagram.png       # Visual aids
+Validate the data before proceeding.
 ```
 
-## File References
+Note: "When to Use" sections in the body are **not** used for discovery. Put all discovery-relevant information in the description frontmatter.
 
-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      |
-```
+## Progressive Disclosure
 
-### 3. Show Concrete Examples
+Skills use a three-level system to minimize token usage:
 
-```markdown
-## Examples
+| Layer | Budget | When Loaded |
+|-------|--------|-------------|
+| YAML frontmatter | ~100 tokens | At startup (all skills) |
+| SKILL.md body | < 5000 tokens | When skill activated |
+| Linked files (references/) | As needed | On demand |
 
-### Basic Usage
+### Guidelines
 
-\`\`\`bash
-b2c command --flag value
-\`\`\`
+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
 
-### Advanced Usage
+## Optional Directories
 
-\`\`\`bash
-b2c command --complex-flag
-\`\`\`
-```
+### scripts/
+Executable code that agents can run. Scripts should be self-contained, include helpful error messages, and handle edge cases.
 
-### 4. Explain When NOT to Use
+### references/
+Additional documentation loaded on demand. Keep individual reference files focused on one topic. Smaller files = less context usage.
 
-```markdown
-## When NOT to Use
+### assets/
+Static resources: templates, fonts, icons used in output.
 
-- Scenario A (use skill-x instead)
-- Scenario B (manual approach better)
-```
+## File References
 
-### 5. Link to Authoritative Sources
+Use relative paths from the skill root. Keep references one level deep — avoid deeply nested chains (SKILL.md → ref1.md → ref2.md is too deep).
 
-Reference official documentation rather than duplicating it:
+## Skill Categories
 
-```markdown
-## Reference
+### Developer Skills (`.claude/skills/`)
+Skills for contributors working on this codebase (command development patterns, testing approaches, API client patterns, documentation standards).
 
-For complete API documentation, see [Official Docs](https://example.com/docs).
-```
+### User-Facing Skills (`skills/*/skills/`)
+Skills for users of the tool (CLI command usage, platform-specific patterns, integration guides).
 
 ## Validation Checklist
 
-Before publishing a skill:
-
-- [ ] Frontmatter has `name` and `description`
-- [ ] SKILL.md under 500 lines
-- [ ] Key information appears early
-- [ ] Examples are concrete and runnable
-- [ ] Reference links are valid
-- [ ] No deeply nested reference chains
-- [ ] Tested with target agent
+### Before you start
+- [ ] Identified 2-3 concrete use cases
+- [ ] Planned folder structure
+
+### During development
+- [ ] Folder named in kebab-case
+- [ ] `SKILL.md` file exists (exact spelling)
+- [ ] No `README.md` inside the skill folder
+- [ ] YAML frontmatter has `---` delimiters
+- [ ] `name` field: kebab-case, matches folder name
+- [ ] `description` includes WHAT and WHEN (trigger phrases)
+- [ ] No XML tags (`<` or `>`) in frontmatter
+- [ ] Instructions are clear and actionable
+- [ ] Examples provided
+- [ ] Error handling / troubleshooting included
+- [ ] References clearly linked
+
+### Testing
+- [ ] Triggers on obvious task requests
+- [ ] Triggers on paraphrased requests
+- [ ] Does NOT trigger on unrelated topics
+- [ ] Functional output is correct
+
+### After deployment
+- [ ] Test in real conversations
+- [ ] Monitor for under/over-triggering
+- [ ] Iterate on description and instructions
+
+## Iteration Signals
+
+**Undertriggering** (skill doesn't load when it should):
+- Users manually enabling it or asking "when should I use this?"
+- Solution: Add more trigger phrases and task-oriented keywords to description
+
+**Overtriggering** (skill loads for unrelated queries):
+- Users disabling it or confusion about purpose
+- Solution: Add negative triggers ("Do NOT use for..."), be more specific, clarify scope
+
+**Execution issues** (skill loads but results are inconsistent):
+- Users correcting Claude or re-prompting
+- Solution: Make instructions more specific, add error handling, use scripts for critical validations (code is deterministic; language interpretation isn't)
 
 ## Detailed Reference
 

skills/b2c-cli/skills/b2c-scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: b2c-scaffold
-description: Generate B2C Commerce cartridges, controllers, hooks, custom APIs, job steps, and Page Designer components from scaffold templates.
+description: Generate B2C Commerce cartridges, controllers, hooks, custom APIs, job steps, and Page Designer components from scaffold templates. Use when starting a new cartridge, adding a controller to an existing cartridge, creating hook implementations, bootstrapping custom API endpoints, or generating job steps and Page Designer components.
 ---
 
 # B2C Scaffold Skill