managing-snippets

name	managing-snippets
description	Comprehensive guide for managing Claude Code snippets v2.0 - discovering locations, creating snippets from files, searching by name/pattern/description, and validating configurations. Use this skill when users want to create, search, or manage snippet configurations in their Claude Code environment. Updated for LLM-friendly interface with TTY auto-detection.

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:

{
  "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:

---
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:

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:

snippets paths
# OR with JSON output
snippets paths --output json

Filter by keyword:

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:

   ---
   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:

   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:

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

Search by keyword:

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. Updates are done by editing files directly.

Modify existing snippets when:

• Pattern doesn't match expected keywords
• Content is outdated
• Need to enable/disable temporarily
• Want to rename for clarity

Update workflow:

1. Find the snippet:

   snippets docker          # Search to locate snippet
   # OR in interactive mode: select snippet → opens in $EDITOR
   

2. Determine what needs updating:

   • Pattern expansion → Edit config.local.json
   • Content modification → Edit SKILL.md directly
   • Status change → Edit config.local.json (enabled field)
   • Rename → Edit config.local.json (name field)

3. For pattern updates:

   # Edit config.local.json directly
   vim ~/.claude/plugins/.../scripts/config.local.json
   
   # Modify the pattern field
   {
     "name": "docker",
     "pattern": "\\b(DOCKER|CONTAINER|DOCKERFILE|KUBECTL)\\b[.,;:!?]?",  # Added KUBECTL
     ...
   }
   

4. For content updates:

   # Edit SKILL.md directly
   vim ~/.claude/plugins/.../snippets/local/development/docker/SKILL.md
   
   # Update content while maintaining YAML frontmatter
   

5. Validate changes:

   snippets validate        # Check for errors
   snippets validate --output json  # JSON output for scripting
   

6. Test:

   • Type trigger keyword in new prompt
   • Confirm content loads correctly

Context-aware updating: If a snippet failed to load during a session, analyze why:

• Did the pattern not match? → Edit config.local.json to expand pattern
• Was it disabled? → Change "enabled": false to true
• Missing keywords? → Add alternatives to pattern

Step 6: Deleting Snippets (Direct File Editing)

Remove snippets that are:

• No longer needed
• Superseded by other snippets or skills
• Creating conflicts with other patterns

Deletion workflow:

1. Backup first:

   # Create backup of config
   cp ~/.claude/plugins/.../scripts/config.local.json \
      ~/.claude/plugins/.../scripts/config.local.json.backup.$(date +%Y%m%d_%H%M%S)
   
   # Backup snippet file
   cp -r ~/.claude/plugins/.../snippets/local/category/snippet-name \
         ~/.claude/plugins/.../backups/snippet-name_$(date +%Y%m%d_%H%M%S)
   

2. Remove from config.local.json:

   vim ~/.claude/plugins/.../scripts/config.local.json
   
   # Delete the entire mapping object
   # Ensure JSON remains valid (check commas)
   

3. Optionally delete SKILL.md:

   rm -rf ~/.claude/plugins/.../snippets/local/category/snippet-name
   

4. Validate and verify:

   snippets validate              # Check JSON is valid
   snippets                       # Confirm snippet is gone
   # Type trigger keyword → should not load
   

Restoration: If you need to restore:

1. cp backup/config.local.json.backup.TIMESTAMP config.local.json
2. cp -r backup/snippet-name_TIMESTAMP snippets/local/category/snippet-name
3. snippets validate and test trigger keyword

Regex Protocol (Standard Format)

CRITICAL: All snippet patterns MUST follow this format.

Standard Format

\b(PATTERN)\b[.,;:!?]?

Rules:

1. Single keyword per snippet: Each snippet should have exactly ONE trigger keyword (e.g., DOCKER, not DOCKER|CONTAINER|DOCKERFILE). This ensures predictable activation and avoids confusion about which keyword triggered what.
2. Word boundaries: \b at start and end
3. Parentheses: Pattern wrapped in ()
4. ALL CAPS: Uppercase only (A-Z, 0-9)
5. Multi-word: Use _, -, or no separator (never spaces)
6. No mixed separators: Can't mix _ and - in same pattern
7. Optional punctuation: [.,;:!?]? at end
8. Alternation discouraged: Avoid | for multiple keywords—create separate snippets if needed

Why Full Punctuation Matters

Users naturally add punctuation when typing. Excluding punctuation causes mismatches:

• ❌ Pattern [.,;:]? does NOT match "ARTIFACT!"
• ✅ Pattern [.,;:!?]? matches "ARTIFACT!", "ARTIFACT?", "ARTIFACT."

Always use the full set: [.,;:!?]?

Valid Examples

\b(DOCKER)\b[.,;:!?]?                      # Single keyword (preferred)
\b(BUILD_ARTIFACT)\b[.,;:!?]?              # Underscore separator
\b(BUILD-ARTIFACT)\b[.,;:!?]?              # Hyphen separator
\b(BUILDARTIFACT)\b[.,;:!?]?               # No separator

Invalid/Discouraged Examples

\b(docker)\b[.,;:!?]?              # ❌ Lowercase
\b(BUILD ARTIFACT)\b[.,;:!?]?      # ❌ Space separator
\b(BUILD_ART-IFACT)\b[.,;:!?]?     # ❌ Mixed separators
\bDOCKER\b                         # ❌ Missing parens and punctuation
\b(DOCKER)\b[.,;:]?                # ❌ Incomplete punctuation
\b(DOCKER|CONTAINER|DOCKERFILE)\b[.,;:!?]? # ⚠️ Multiple keywords—avoid

Pattern Transformation

User input → Standard format:

1. Choose ONE keyword:

   • Pick the most distinctive/memorable keyword
   • "docker, container, dockerfile" → Choose DOCKER (most distinctive)

2. Convert to ALL CAPS:

   • "docker" → "DOCKER"
   • "build artifact" → "BUILD_ARTIFACT"

3. Handle multi-word:

   • Choose one separator: _ (preferred), -, or none
   • Apply consistently throughout pattern

4. Apply standard format:

   • Wrap in \b boundaries
   • Add parentheses
   • Add [.,;:!?]? for punctuation

JSON Escaping

IMPORTANT: In config.local.json, backslashes must be doubled:

{
  "pattern": "\\b(DOCKER)\\b[.,;:!?]?"
}

Single \b becomes \\b in JSON.

Complete Examples

Example 1: Create Docker Snippet

Step 1: Understand needs

• Trigger: "DOCKER" (single distinctive keyword)
• Provides: Docker best practices and commands
• Frequent use: Yes

Step 2: Plan pattern

• Keyword: DOCKER
• Pattern: \b(DOCKER)\b[.,;:!?]?

Step 3: Create snippet

1. Create directory:

   mkdir -p ~/.claude/plugins/.../snippets/local/development/docker
   

2. Create SNIPPET.md:

   ---
   name: "Docker Best Practices"
   description: "Use when working with Docker containers, images, and containerization"
   ---
   
   # Docker Best Practices
   [Content here...]
   

3. Add to config.local.json:

   {
     "name": "docker",
     "pattern": "\\b(DOCKER)\\b[.,;:!?]?",
     "snippet": ["../snippets/local/development/docker/SNIPPET.md"],
     "separator": "\n",
     "enabled": true
   }
   

Step 4: Test

• Type "DOCKER" → snippet loads

Example 2: Create a Related Snippet for Different Keyword

Scenario: User wants "kubectl" to also load kubernetes-related content

Solution: Create a separate snippet (single-keyword rule)

1. Original snippet: kubernetes with pattern \b(K8S)\b[.,;:!?]?
2. Create new snippet: kubectl-guide with pattern \b(KUBECTL)\b[.,;:!?]?
3. Both can reference the same content files if needed

Alternative: If content is truly identical, consider renaming the keyword to something more general (e.g., K8S)

Example 3: Delete Unused Snippet

Backup → Remove from config.local.json → Delete SNIPPET.md → Verify

File Locations

• Config: ~/.claude/plugins/.../scripts/config.local.json
• Snippets: ~/.claude/plugins/.../snippets/local/{category}/{name}/SNIPPET.md
• Categories: communication/, documentation/, development/, productivity/, output-formats/

Best Practices

• Check architecture first (read config.local.json before creating)
• Pattern in config.local.json, NOT YAML frontmatter
• Use ALL CAPS in patterns with full punctuation: [.,;:!?]?
• Double-escape in JSON: \\b not \b
• Test after changes
• Backup before deletion

Quick Reference (v2.0)

Task	Command / Action
Discover categories	snippets paths or snippets paths <filter>
Create snippet	snippets create source.md snippets/local/category/name/SKILL.md
List all snippets	snippets or snippets list
Search snippets	snippets <keyword> (searches name/pattern/description)
Update pattern	Edit pattern field in config.local.json directly
Update content	Edit SKILL.md file directly (or use snippets <name> in TTY → opens $EDITOR)
Enable/disable	Change enabled field in config.local.json
Delete snippet	1. Backup files 2. Remove from config.local.json 3. Delete SKILL.md directory
Validate config	snippets validate or snippets validate --output json
Test pattern	Type trigger keyword in new prompt

Troubleshooting

Issue	Fix
Not loading	Check enabled: true, pattern matches (ALL CAPS), file path correct
Pattern not matching	Verify standard format, use [.,;:!?]?, test with ALL CAPS
Too many loading	Check overlapping patterns, disable conflicts
JSON errors	Validate syntax, use \\b not \b

Critical Reminders

Architecture:

• Pattern goes in config.local.json (NOT YAML frontmatter)
• Always read config.local.json before creating snippets
• Double-escape in JSON: \\b

When User Corrects You: Stop → Read actual files → Understand architecture → Fix all related mistakes → Verify