# Skills Gotchas

## Non-ASCII characters in YAML frontmatter silently prevent skill loading

Claude Code skills with em dashes (`---` U+2014), smart quotes, or other non-ASCII in the YAML frontmatter `description` field will fail to load with "Unknown skill" — no error message, no warning. The body below frontmatter can contain any characters. Claude commonly generates em dashes, so this is a recurring risk. Always run `validate-skill` before committing a skill.

## Each Claude profile has independent skills directories

Skills symlinked into `~/.claude/skills/` are NOT available in other profiles (e.g., `~/.claude-octopus/skills/`). Each profile maintains a completely independent skills directory. The `CLAUDE_CONFIG_DIR` env var identifies the active profile at runtime — use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills` in install scripts.