Troubleshooting

Troubleshooting

Common issues and how to fix them.

---

Plugin Not Found After Install

Symptom: You installed a plugin but Claude does not recognize its skills or commands.

Fixes:

1. Restart Claude Code. Some changes require a fresh session to be discovered.
2. Verify the plugin directory structure is correct:

   ls ~/.claude/plugins/my-plugin/.claude-plugin/plugin.json

3. Check that plugin.json is valid JSON:

   cat ~/.claude/plugins/my-plugin/.claude-plugin/plugin.json | python3 -m json.tool

4. Run ccpi doctor to check for configuration issues.

---

Skill Not Activating

Symptom: You say something that should trigger a skill, but Claude uses general capabilities instead.

Fixes:

1. Check the description: The description field in frontmatter must include "Use when..." and trigger phrases. If the trigger phrases do not match what you are saying, Claude will not activate the skill.
2. Check frontmatter syntax: Ensure the YAML between --- delimiters is valid. A missing colon or broken indentation will prevent parsing.
3. Check the name: The name field must be kebab-case and match the folder name.
4. Check discovery location: Verify the skill is in one of the four discovery paths:
   • ~/.claude/skills/
   • .claude/skills/
   • Inside a plugin's skills/ directory
   • Built-in
5. Try manual invocation: Type /skill-name to invoke it directly. If that works, the issue is with trigger phrase matching.
6. Check allowed-tools: If allowed-tools is malformed (e.g., missing quotes, unscoped Bash), the skill may fail silently.

---

ccpi Command Not Found

Symptom: Running ccpi returns "command not found".

Fixes:

1. Verify global installation:

   pnpm list -g @intentsolutionsio/ccpi

2. If not installed, install it:

   pnpm add -g @intentsolutionsio/ccpi

3. Check that pnpm's global bin directory is in your PATH:

   pnpm bin -g

   Add that directory to your shell's PATH if it is missing.
4. If you use nvm or another Node version manager, make sure you are on the same Node version where you installed ccpi.

---

Marketplace Sync Issues

Symptom: ccpi search returns stale or no results.

Fixes:

1. Re-add the marketplace:

   /plugin marketplace remove claude-code-plugins
   /plugin marketplace add jeremylongshore/claude-code-plugins
   

2. Run ccpi update to pull the latest catalog.
3. Check your internet connection -- the CLI fetches from GitHub Pages.

---

Permission Errors

Symptom: A plugin's scripts or MCP server fail with "Permission denied".

Fixes:

1. Make shell scripts executable:

   chmod +x path/to/script.sh

2. For MCP server plugins, the compiled dist/index.js must be executable:

   chmod +x plugins/mcp/my-plugin/dist/index.js

3. Verify the file has a proper shebang line (#!/usr/bin/env node for Node.js scripts).

---

MCP Server Not Connecting

Symptom: An MCP plugin's tools are not available, or Claude reports a connection error.

Fixes:

1. Check the build: MCP plugins must be compiled before use:

   cd plugins/mcp/my-plugin && pnpm build

2. Check .mcp.json: The MCP configuration file must point to the correct dist/index.js path.
3. Check dependencies: Run pnpm install inside the plugin directory.
4. Check Node version: MCP plugins require Node.js >= 18.
5. Test manually: Run the server directly to see error output:

   node plugins/mcp/my-plugin/dist/index.js

---

Build Failures

Symptom: pnpm build or marketplace build fails.

Fixes:

1. Clean install: Remove node_modules and reinstall:

   rm -rf node_modules && pnpm install

2. Check package manager: The root uses pnpm, but the marketplace/ directory uses npm. Do not mix them.

   # Root
   pnpm install && pnpm build
   
   # Marketplace
   cd marketplace && npm install && npm run build

3. Run validation first:

   pnpm run sync-marketplace
   ./scripts/validate-all-plugins.sh

4. Check TypeScript errors:

   pnpm typecheck

---

Skill Validation Failures

Symptom: The validator reports errors for your SKILL.md file.

Common issues:

Error	Fix
"Name must be kebab-case"	Rename to lowercase-with-hyphens
"Missing required field"	Add all 6 required frontmatter fields
"Bash must be scoped"	Change Bash to Bash(git:*) or similar
"Version must be SemVer"	Use x.y.z format (e.g., 1.0.0)
"Body exceeds 500 lines"	Move content to references/ directory
"Missing required section"	Add all 7 body sections (Overview through Resources)
"Use CLAUDE_SKILL_DIR"	Replace ${CLAUDE_PLUGIN_ROOT} with ${CLAUDE_SKILL_DIR}

Run the full validator with details:

python3 scripts/validate-skills-schema.py --verbose --skills-only

---

Getting Help

If these steps do not resolve your issue:

• GitHub Discussions: Ask a question -- community Q&A and troubleshooting
• Issue Tracker: Report a bug -- for confirmed bugs and feature requests
• Discord: Claude Developers Discord -- 40,000+ members, real-time help
• Email: jeremy@intentsolutions.io -- for security issues or private inquiries

When reporting an issue, include:

1. Your Node.js version (node --version)
2. Your ccpi version (ccpi --version)
3. The exact error message or unexpected behavior
4. Steps to reproduce the problem

---

Related Pages

• Installation -- setup walkthrough
• CLI Quick Reference -- all commands
• Your First Plugin -- plugin structure guide
• Your First Skill -- skill creation guide