Skip to content

28-skill-optimization-patterns.md

Latest commit

 

History

History
336 lines (262 loc) · 8.79 KB

28-skill-optimization-patterns.md

File metadata and controls

336 lines (262 loc) · 8.79 KB

28. Skill Optimization Patterns

Created: January 2026 Source: Claude Code changelog (January 2026) + Production implementation Evidence: 171 skills optimized with new frontmatter features

Overview

Claude Code introduced new skill frontmatter features in January 2026 that enable:

  • Isolated execution via context: fork
  • Agent routing via agent: field
  • Menu visibility control via user-invocable: false
  • Wildcard bash permissions for cleaner configuration

This guide shows how to optimize your skills library with these features.

1. Context Fork (context: fork)

What It Does

  • Runs skill in an isolated sub-agent context
  • Prevents context pollution from long-running operations
  • Ideal for heavy skills that spawn many tool calls

When to Use

  • Deployment skills - Multiple gcloud/docker commands
  • Sync operations - Database migrations, gap detection
  • Validation skills - Cross-environment parity checks
  • Large-scale operations - Anything with 10+ tool calls

Implementation

---
name: deployment-master-skill
description: "Deploy to GCP Cloud Run with Sacred compliance..."
context: fork
---

Batch Update Script

# Add context: fork to heavy skills
for skill in deployment-master-skill gap-auto-healing-skill sync-workflow-skill; do
  if [ -f ~/.claude/skills/$skill/SKILL.md ]; then
    if ! grep -q "context:" ~/.claude/skills/$skill/SKILL.md; then
      sed -i '/^description:/a context: fork' ~/.claude/skills/$skill/SKILL.md
      echo "✅ Added context: fork to $skill"
    fi
  fi
done

Recommended Skills for context: fork

Category Skills
Deployment deployment-master, cloud-run-safe-deployment, post-deployment-validation
Sync gap-auto-healing, gap-detection-and-sync, historical-reductions-sync
Validation comprehensive-parity-validation, production-parity-workflow
Database database-master, schema-recreation-sync, large-table-sync-safety
Testing testing-master, staging-data-sync-validation

2. Agent Routing (agent:)

What It Does

  • Specifies which agent type executes the skill
  • Routes skill to specialized agent for better results
  • Enables domain expertise matching

Agent Mapping

Domain Agent Use Cases
Database database-agent Schema, sync, gaps, parity
API api-coordinator OAuth, endpoints, integrations
Testing test-engineer Jest, E2E, baseline tests
Deployment deploy-agent Cloud Run, GCP, CI/CD
AI/LLM vertex-ai-agent Prompts, embeddings, quality
Troubleshooting debug-specialist Errors, investigation, fixes
Hebrew hebrew-agent RTL, cultural, i18n

Implementation

---
name: database-master-skill
description: "Database patterns and schema operations..."
agent: database-agent
context: fork
---

Batch Update Script

# Add agent routing by domain
cd ~/.claude/skills

# Database skills
for skill in database-master-skill gap-auto-healing-skill schema-recreation-sync-skill; do
  if [ -f "$skill/SKILL.md" ] && ! grep -q "agent:" "$skill/SKILL.md"; then
    sed -i '/^description:/a agent: database-agent' "$skill/SKILL.md"
    echo "✅ database-agent → $skill"
  fi
done

# AI skills
for skill in ai-quality-validation-skill prompt-optimization-skill semantic-query-router-skill; do
  if [ -f "$skill/SKILL.md" ] && ! grep -q "agent:" "$skill/SKILL.md"; then
    sed -i '/^description:/a agent: vertex-ai-agent' "$skill/SKILL.md"
    echo "✅ vertex-ai-agent → $skill"
  fi
done

3. User Invocable (user-invocable: false)

What It Does

  • Hides skill from slash command menu
  • Skill still works when called programmatically
  • Reduces menu clutter for consolidated/internal skills

When to Use

  • Consolidated skills that redirect to master skills
  • Internal/utility skills not meant for direct invocation
  • Template skills used as references only

Implementation

---
name: api-authentication-patterns-skill
description: "Configure API authentication..."
user-invocable: false
---

# ⚠️ CONSOLIDATED

This skill has been consolidated into **api-master-skill**.

Batch Update Script

# Find and mark consolidated skills
cd ~/.claude/skills

for skill in $(grep -l "consolidated into" */SKILL.md 2>/dev/null | xargs -I{} dirname {}); do
  if ! grep -q "user-invocable:" "$skill/SKILL.md"; then
    sed -i '/^description:/a user-invocable: false' "$skill/SKILL.md"
    echo "✅ Marked $skill as internal"
  fi
done

4. Wildcard Bash Permissions

What It Does

  • Uses * wildcard at any position in Bash rules
  • Simplifies permission configuration
  • Reduces maintenance overhead

Before (Explicit Rules)

{
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(npm run format)",
      "Bash(npm install)",
      "Bash(git status)",
      "Bash(git log)",
      "Bash(git diff)",
      "Bash(git add)",
      "Bash(gcloud run deploy)",
      "Bash(gcloud run services)",
      "Bash(docker build)",
      "Bash(docker push)"
    ]
  }
}

After (Wildcard Patterns)

{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(git *)",
      "Bash(gcloud *)",
      "Bash(docker *)",
      "Bash(node *)",
      "Bash(curl *)",
      "Bash(jq *)",
      "Bash(grep *)",
      "Bash(find *)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(PGPASSWORD=* psql *)"
    ]
  }
}

Wildcard Patterns

Pattern Matches
Bash(npm *) All npm commands
Bash(* install) Any command ending with install
Bash(git * main) Git commands with "main" at end
Bash(PGPASSWORD=* psql *) Any psql with any password

5. Complete Optimization Workflow

Step 1: Identify Skills to Optimize

# Count current state
echo "Skills with context: fork → $(grep -rl 'context: fork' ~/.claude/skills/*/SKILL.md | wc -l)"
echo "Skills with agent: → $(grep -rl '^agent:' ~/.claude/skills/*/SKILL.md | wc -l)"
echo "Skills with user-invocable: false → $(grep -rl 'user-invocable: false' ~/.claude/skills/*/SKILL.md | wc -l)"

Step 2: Categorize Skills

# Find consolidated skills
grep -l "consolidated into" ~/.claude/skills/*/SKILL.md

# Find heavy/master skills
ls ~/.claude/skills/ | grep -E "(master|deployment|sync|gap|parity)"

Step 3: Apply Optimizations

  1. Mark consolidated skills with user-invocable: false
  2. Add context: fork to heavy skills
  3. Add agent: routing to domain-specific skills
  4. Update settings.json with wildcard permissions

Step 4: Validate

# Validate settings.json
jq . ~/.claude/settings.json > /dev/null && echo "✅ Valid JSON"

# Validate skill frontmatter
for skill in ~/.claude/skills/*/SKILL.md; do
  if grep -q "^---" "$skill" && grep -q "name:" "$skill"; then
    echo "✅ $(basename $(dirname $skill))"
  else
    echo "❌ $(basename $(dirname $skill))"
  fi
done

6. Results from Production Implementation

Optimization Summary

Feature Skills Updated
context: fork 25 heavy skills
agent: routing 39 domain skills
user-invocable: false 26 consolidated skills
Wildcard permissions 19 rules (from 30+)

Agent Distribution

Agent Skills
database-agent 14
vertex-ai-agent 10
deploy-agent 6
test-engineer 4
debug-specialist 4
api-coordinator 2

Benefits

  • Cleaner slash menu - 26 fewer internal skills visible
  • Better isolation - Heavy operations don't pollute context
  • Smarter routing - Skills execute with domain expertise
  • Simpler config - 19 wildcard rules vs 30+ explicit

7. Migration Checklist

  • Audit skills directory (ls ~/.claude/skills/)
  • Identify consolidated skills (grep for "consolidated into")
  • Identify heavy skills (deployment, sync, gap, parity)
  • Map skills to agent domains
  • Add user-invocable: false to consolidated skills
  • Add context: fork to heavy skills
  • Add agent: to domain-specific skills
  • Update settings.json with wildcard permissions
  • Validate JSON/YAML syntax
  • Restart Claude Code session
  • Test skill activation

References

Status: ✅ PRODUCTION VALIDATED Implementation Time: ~2-3 hours for full optimization ROI: Cleaner menu, better isolation, smarter routing