Claude Skills Pitfalls — Development skill for Claude Code

claude-skills-pitfalls

**A catalog of why Claude skills (`SKILL.md`) silently break across Claude Code, Claude.ai, and Claude Desktop — and how to fix each one.** Covers hidden tool limits, cross-platform tool differences, sandbox/filesystem constraints, and SKILL.md authoring traps, each labeled with how it was verified.

Skills break in ways that aren't documented anywhere accessible to skill authors. Some breakages are hidden constraints on a single tool. Some are differences between platforms. Some are silent fallbacks the author never notices. This repo catalogs them — with reproductions — so you find the answer when you search for the error, not when you read 4,000 lines of system prompt.

What this is / what this isn't

• Is: a catalog of runtime pitfalls when writing skills, with reproductions where possible
• Is: cross-platform (Claude.ai, Claude Code, Claude Desktop)
• Isn't: a tutorial on how to write skills (see Anthropic's `skill-creator`)
• Isn't: a bug tracker for Anthropic (file those upstream)
• Isn't: prompt engineering tips

Start here

If you read five entries, read these:

1. `Write` overwrites silently; `create_file` refuses to overwrite — most dangerous cross-platform divergence
2. Skills fail silently when their named tool doesn't exist — explains why your skill "works" on your platform and produces gibberish on others
3. `ask_user_input_v0` has hidden 3×4 limits — the pitfall that started this repo
4. `AskUserQuestion` and `ask_user_input_v0` are different tools — same purpose, different schemas, different limits
5. [references/ paths don't resolve from the skill's directory](pitfalls/skill-structure/references-dire