Troubleshooting Guide

Common issues and solutions when working with Agent Skills across different platforms.

• Check Paths: Ensure the skill folder is in the platform's expected directory.
• YAML Validation: Verify the Frontmatter triple-dashes --- are correct and YAML is valid.
• Folder Name: The directory name must match the name field in SKILL.md.

• Description Clarity: If the description is too vague, the agent won't know when to use it.
• Explicit Call: Try manually invoking with /skill-name or @skill-name.
• Model Conflict: The agent might be preferring its own internal knowledge over the skill.

• Executable Bit: Run chmod +x scripts/*.sh on Unix systems.
• Path Issues: Ensure scripts use relative paths within the skill directory.
• Admin Access: Some platforms require administrator privileges to read certain directories.

• Sync Issues: Restart the CLI with claude restart if new skills aren't detected.

• Indexing: Cursor may take a few moments to index a newly added skill folder.

• Tokens: Large skills can consume many tokens; try using Progressive Disclosure.

Check the Best Practices or visit our community forum.