Troubleshooting Guide

When things go wrong with Claude Code plugins, this guide helps you diagnose and fix the most common issues quickly. Each section covers a specific problem with symptoms, root causes, and step-by-step fixes.

Issue 1: Skill Doesn't Activate

Symptoms

• You mention a topic the skill should handle, but Claude doesn't use it
• The skill doesn't appear in /skills output
• Slash command for the skill doesn't work

Root Causes & Fixes

1. Missing trigger phrases in description

Claude uses the description field to decide when to activate a skill. If it lacks clear trigger language, Claude won't know when to use it.

# Bad: vague description
description: "Helps with Docker stuff"

# Good: clear trigger phrases
description: |
  Use when the user wants to harden a Dockerfile, audit container
  security, or optimize Docker image size. Activate for any Docker
  or container-related security questions.

2. user-invocable is set to false

If a skill has user-invocable: false in its frontmatter, it won't appear in the / menu and can't be triggered directly:

# This hides the skill from the / menu
user-invocable: false

# Remove this line or set to true to make the skill available
user-invocable: true

3. Plugin not installed or loaded

# Check if the plugin is installed
/plugins

# Reinstall if missing
/plugin marketplace add jeremylongshore/claude-code-plugins

4. Frontmatter parsing error

Invalid YAML in the frontmatter silently prevents skill loading. Validate the SKILL.md:

# Validate a specific skill file
python3 scripts/validate-skills-schema.py --skills-only --verbose plugins/category/plugin-name/skills/skill-name/SKILL.md

Issue 2: Validation Errors

Symptoms

• Enterprise validation returns a low score
• CI fails on the validation step
• Specific field errors in validation output

Diagnosis

# Run enterprise validation with verbose output
python3 scripts/validate-skills-schema.py --enterprise --verbose path/to/SKILL.md

# Check for specific field issues
python3 scripts/validate-skills-schema.py --enterprise path/to/SKILL.md 2>&1 | grep "FAIL\|ERROR\|WARN"

Common Validation Failures

Quick Fix Template

If your skill is missing multiple required fields, use this template as a starting point:

---
name: my-skill-name
description: |
  Use when the user needs help with [specific task].
  Activate for questions about [topic area].
allowed-tools: Read, Write, Edit, Glob, Grep
version: 1.0.0
author: Your Name <email@example.com>
license: MIT
tags: [relevant, tags, here]
---

Issue 3: Plugin Not Found

Symptoms

• /plugins doesn't list your plugin
• Install command fails with "plugin not found"
• Skills from the plugin don't appear

Fixes

1. Verify plugin.json exists

# Check for the required plugin manifest
ls -la plugins/category/plugin-name/.claude-plugin/plugin.json

# If missing, create it with required fields
cat > plugins/category/plugin-name/.claude-plugin/plugin.json << 'EOF'
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "What this plugin does",
  "author": "Your Name "
}
EOF

2. Check marketplace catalog entry

The plugin must be registered in the marketplace catalog:

# Search for your plugin in the catalog
grep "plugin-name" .claude-plugin/marketplace.extended.json

# If not found, add an entry to marketplace.extended.json
# Then regenerate the CLI catalog:
pnpm run sync-marketplace

3. Verify plugin.json only has allowed fields

CI rejects plugin.json files with extra fields. Only these fields are allowed:

{
  "name": "...",
  "version": "...",
  "description": "...",
  "author": "...",
  "repository": "...",
  "homepage": "...",
  "license": "...",
  "keywords": []
}

Issue 4: Build Fails

Symptoms

• pnpm install or pnpm build fails
• Marketplace build errors
• CI build job fails

Fixes

1. Check package manager

The repository enforces strict package manager policy. Using the wrong one will fail:

# Root and all packages: use pnpm
pnpm install
pnpm build

# Marketplace directory ONLY: use npm
cd marketplace/
npm install
npm run build

# NEVER use npm at root or pnpm in marketplace/

2. Clean install

# Remove all node_modules and reinstall
rm -rf node_modules packages/*/node_modules plugins/mcp/*/node_modules
pnpm install

# For marketplace
cd marketplace/
rm -rf node_modules
npm install

3. Check Node.js version

# Requires Node.js 18+
node --version

# If outdated, update via nvm
nvm install 20
nvm use 20

4. MCP plugin build issues

# MCP plugins need individual builds
cd plugins/mcp/plugin-name/
pnpm build

# Ensure dist/index.js is executable
chmod +x dist/index.js

# Verify shebang line exists
head -1 dist/index.js
# Should show: #!/usr/bin/env node

Issue 5: Performance Issues

Symptoms

• Build takes longer than expected
• Performance budget check fails in CI
• Pages load slowly

Diagnosis

# Run performance budget checks
node scripts/check-performance.mjs

# Benchmark CLI operations
bash scripts/benchmark-cli.sh

# Check bundle sizes
cd marketplace/
npm run build
du -sh dist/

Common Performance Fixes

Performance Budget Reference

# Current limits (enforced by CI)
Total bundle (gzipped):    19.5 MB
Largest file (gzipped):    550 KB
Build time:                < 10 seconds
Route count:               1,600 - 2,000

Issue 6: SaaS Pack Missing Skills

Symptoms

• A SaaS pack has fewer skills than expected
• Skills listed in TRACKER.csv aren't present as files
• Pack validation reports missing skills

Diagnosis

# Check the tracker for expected skills
cat plugins/saas-packs/pack-name/TRACKER.csv

# Count actual skill directories
ls -d plugins/saas-packs/pack-name/skills/*/

# Compare expected vs actual
diff <(grep -o '"[^"]*"' plugins/saas-packs/pack-name/TRACKER.csv | sort) \
     <(ls -d plugins/saas-packs/pack-name/skills/*/ | xargs -I{} basename {} | sort)

Regenerating Missing Skills

If skills are listed in the tracker but missing from the filesystem, regenerate them:

# Regenerate the pack using the generator script
python3 scripts/generate-pack.py --pack pack-name --regenerate-missing

# Validate the regenerated skills
python3 scripts/validate-skills-schema.py --enterprise plugins/saas-packs/pack-name/

Manual Skill Creation

If the generator isn't available, create skills manually following the pack's existing structure:

# Use an existing skill as a template
cp -r plugins/saas-packs/pack-name/skills/existing-skill/ \
      plugins/saas-packs/pack-name/skills/new-skill/

# Edit the SKILL.md with the correct content
# Then validate
python3 scripts/validate-skills-schema.py --enterprise \
  plugins/saas-packs/pack-name/skills/new-skill/SKILL.md

Getting Help

Self-Service Resources

• Marketplace: tonsofskills.com - Browse plugins, skills, and documentation
• Playbooks: tonsofskills.com/playbooks - In-depth guides for specific topics
• Plugin validation: Run python3 scripts/validate-skills-schema.py --enterprise --verbose for detailed diagnostics

Community Support

• GitHub Issues: Report bugs and request features
• Discussions: Ask questions and share tips

Pro Support

For production deployments and enterprise needs:

• Intent Solutions: Professional support for Claude Code plugin deployments
• Custom plugin development: Bespoke skills and SaaS packs for your tech stack
• Training: Team onboarding and best practices workshops

Diagnostic Checklist

When reporting issues, include this information for faster resolution:

# Gather diagnostic info
echo "=== Environment ==="
node --version
pnpm --version
claude --version

echo "=== Plugin Status ==="
ls .claude-plugin/

echo "=== Validation ==="
python3 scripts/validate-skills-schema.py --enterprise --verbose 2>&1 | tail -20

echo "=== Recent Errors ==="
# Include any error messages from your terminal

Last Updated: 2026-03-21

Author: Jeremy Longshore

Related Playbooks: Beginner Onboarding, Incident Debugging