managing-snippets

What this skill does

# Managing Snippets (v2.0)

Snippets auto-inject context when regex patterns match user messages. This skill provides a streamlined workflow for discovering snippet locations, creating snippets, searching configurations, and direct file editing.

## About Snippets

Snippets are pattern-triggered context injection files that enhance Claude's capabilities by automatically loading relevant information when specific keywords appear in user prompts. Think of them as "smart bookmarks" that activate based on what you're working on.

### What Snippets Provide

1. **Automatic context loading** - Inject relevant documentation when keywords match
2. **Workflow enhancement** - Load domain-specific guidance without manual selection
3. **Consistency** - Ensure same context is available across sessions
4. **Efficiency** - Skip manual skill invocation for frequently-used contexts

### When to Use Snippets

- Frequently-used skills that should activate on keywords (e.g., "DOCKER", "TERRAFORM")
- Domain-specific documentation that's needed for specific topics
- Quick-reference material that should load automatically
- Workflow guides tied to specific technologies or tasks

## Anatomy of a Snippet

Every snippet consists of two components:

### 1. config.local.json Entry (Required)

Located at:
```
/Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/scripts/config.local.json
```

**Structure:**
```json
{
  "name": "snippet-identifier",
  "pattern": "\\b(PATTERN)\\b[.,;:!?]?",
  "snippet": ["../snippets/local/category/name/SNIPPET.md"],
  "separator": "\n",
  "enabled": true
}
```

**Key fields:**
- `name`: Unique identifier for the snippet
- `pattern`: Regex pattern that triggers the snippet (MUST follow standard format)
- `snippet`: Array of file paths to inject (relative to config file)
- `separator`: How to join multiple files (usually `"\n"`)
- `enabled`: Whether snippet is active (`true`/`false`)

### 2. SNIPPET.md File (Required)

Located in subdirectory under:
```
/Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/claude-context-orchestrator/snippets/local/
```

**Structure:**
```markdown
---
name: "Descriptive Name"
description: "When to use this snippet and what it provides"
---

[Content to be injected into context]
```

**Organization:**
Snippets are organized by category:
- `snippets/local/communication/` - Email, reports, writing templates
- `snippets/local/documentation/` - Guides, references, how-tos
- `snippets/local/development/` - Code patterns, debugging workflows
- `snippets/local/productivity/` - Workflow automation, task management
- `snippets/local/output-formats/` - Formatting styles, templates

## CLI v2.0 Overview

The snippets CLI provides four focused commands:

1. **`paths`** - Discover available snippet categories and locations
2. **`create`** - Create snippets from source files with validation
3. **`list` / search** - Search snippets by name, pattern, or description
4. **`validate`** - Verify configuration integrity

**Installation:**
```bash
cd /Users/wz/.claude/plugins/.../scripts
make install  # Global: uv tool install
# OR
make dev      # Local dev: uv run snippets
```

**Auto-detect modes:**
- **TTY (terminal)**: Interactive selection interface
- **Non-TTY (piped)**: JSON output for scripting

## Snippet Management Process

Follow these steps in order to effectively manage snippets.

### Step 1: Discover Available Locations

Before creating a snippet, explore where snippets can be placed using the `paths` command.

**List all categories:**
```bash
snippets paths
# OR with JSON output
snippets paths --output json
```

**Filter by keyword:**
```bash
snippets paths dev        # Shows categories matching "dev"
snippets paths email      # Shows categories matching "email"
```

**Output:**
- Base directory path
- Category names (communication, documentation, development, productivity, output-formats)
- Category descriptions
- Full paths to each category

### Step 2: Planning the Pattern

Determine the regex pattern that will trigger your snippet. Patterns must follow the standard format (see Regex Protocol below).

**Pattern planning:**
1. Choose ONE distinctive keyword for the snippet (e.g., "DOCKER")
2. Convert to ALL CAPS (e.g., "docker" → "DOCKER")
3. Handle multi-word patterns (use `_`, `-`, or no separator)
4. Apply standard format: `\b(PATTERN)\b[.,;:!?]?`

**Examples:**
- Single keyword: `\b(DOCKER)\b[.,;:!?]?`
- Multi-word: `\b(BUILD_ARTIFACT)\b[.,;:!?]?`
- Compound: `\b(SNIPPETMGMT)\b[.,;:!?]?`

### Step 3: Creating a Snippet

Create snippets using the `create` command, which validates and registers the snippet automatically.

**Creation workflow:**

1. **Create source SKILL.md file with frontmatter:**
   ```markdown
   ---
   name: "Docker Best Practices"
   description: "Use when working with Docker containers, images, and containerization"
   pattern: "\\b(DOCKER)\\b[.,;:!?]?"
   ---

   # Docker Best Practices
   [Content here...]
   ```

2. **Run create command:**
   ```bash
   snippets create source.md snippets/local/development/docker/SKILL.md

   # With pattern override
   snippets create source.md snippets/local/development/docker/SKILL.md \
     --pattern "\\b(NEW_PATTERN)\\b[.,;:!?]?"

   # Force overwrite existing
   snippets create source.md snippets/local/development/docker/SKILL.md --force
   ```

**What create does:**
1. ✅ Validates source file exists
2. ✅ Parses YAML frontmatter (name, description, pattern)
3. ✅ Validates pattern format (ALL CAPS, proper structure)
4. ✅ Validates destination is within snippets/local/
5. ✅ Extracts snippet name from destination path
6. ✅ Checks destination doesn't already exist (unless --force)
7. ✅ Creates destination directory
8. ✅ Copies file to destination
9. ✅ Registers in config.local.json automatically

**Helpful error messages:**
- Missing frontmatter → Shows required YAML structure
- Invalid pattern → Explains pattern requirements with examples
- Invalid destination → Shows expected path format
- Missing pattern → Reminds to add --pattern flag or pattern field

**Common mistakes to avoid:**
- ❌ Using lowercase in pattern
- ❌ Missing `\\b` word boundaries (requires double backslash)
- ❌ Destination outside snippets/local/ directory
- ❌ Forgetting YAML frontmatter

### Step 4: Searching and Inspecting Snippets

Search snippets using enhanced multi-level matching (name → pattern → description).

**List all snippets:**
```bash
snippets                    # Default: list all (TTY: interactive, piped: JSON)
snippets list               # Explicit list command
snippets --output json      # Force JSON output
```

**Search by keyword:**
```bash
snippets docker             # Searches name, pattern, and description
snippets kubernetes         # Priority: exact name > name contains > pattern > description
```

**Interactive mode (TTY):**
- Shows formatted list with match indicators
- Navigate with arrow keys
- Select to open in $EDITOR
- ESC to cancel

**Non-interactive mode (piped/JSON):**
- JSON output with match_type and match_priority
- Can pipe to jq for filtering
- Suitable for scripting

**Match priority ranking:**
1. **Exact name match** (priority 1) - `snippets mail` finds snippet named "mail"
2. **Name contains** (priority 2) - `snippets dock` finds "docker"
3. **Pattern content** (priority 3) - `snippets KUBECTL` finds patterns with KUBECTL
4. **Description match** (priority 4) - `snippets "email templates"` finds description matches

**What to check:**
- Enabled status (✓ or ✗)
- Pattern alternatives (does it cover all intended keywords?)
- File paths (do they point to correct locations?)
- Content (read SKILL.md to verify)

**Regular audits:**
- Review snippets monthly
- Disable unused snippets (edit config.local.json)
- Update patterns based on usage
- Remove outdated content

### Step 5: Updating Snippets (Direct File Editing)

**Philosophy:** v2.0 CLI focuses on search and creation. Updat