Sharing & Troubleshooting Skills

Three ways to share

Plugin skills are namespaced, so /acme-tools:deploy won't collide with another plugin's /deploy.

Troubleshooting: "my skill never triggers"

Work through these in order:

1. Is it found? Type / and look for it in the menu. If it's missing, check the path (.claude/skills/<name>/SKILL.md) and that the first line of the file is ---.
2. Is the frontmatter valid? Bad YAML is silently ignored. Run claude --debug to see loading errors.
3. Is auto-invocation off? disable-model-invocation: true means only /name works, by design.
4. Is the description specific? Vague or overlapping descriptions lose to better matches. Add real trigger phrases.
5. **Is it limited by paths?** If set, the skill only auto-activates when matching files are involved.

Name conflicts and priority

When two skills share a name, the higher-priority location wins: enterprise > personal > project. A skill also takes priority over an old .claude/commands/ file with the same name. If the wrong version runs, check for duplicates in ~/.claude/skills/.

Runtime errors

• A script fails? Run it yourself in the terminal with the same arguments first.
• A ` !command injection that exits non-zero aborts the skill. Add || true` where failure is acceptable.
• Prompted every time a script runs? Add it to allowed-tools.

Measure, don't guess

The real test of a skill is whether results improve. Compare fresh sessions with and without the skill on the same task. For plugin skills, claude plugin eval runs evaluation suites, and /skill-doctor reports each skill's context cost and usage.

Check your understanding