ask_user_input_v0 on Claude.ai enforces a schema-level ceiling of 3 questions and 4 options per question; exceeding either limit fails with a validation error.A catalog of 36 documented runtime pitfalls when writing Claude skills (SKILL.md) — hidden tool limits, cross-platform differences, sandbox constraints, and authoring traps. Each entry has a cause, a fix, and a verification label.
Hidden limits on a single tool — schema-enforced caps and undocumented ceilings.
ask_user_input_v0 on Claude.ai enforces a schema-level ceiling of 3 questions and 4 options per question; exceeding either limit fails with a validation error.image_search.max_results is bounded to the range [3, 5]; values outside that window are rejected by the tool's schema validation.recent_chats.n caps at 20verifiedrecent_chats.n is bounded at 20 — values above the cap are rejected; paginate with before/after cursors instead of asking for a larger page.Bash documents a 600000ms (10-minute) timeout max — but does not hard-reject above itverifiedBash tool description states timeout maxes at 600000ms (10 minutes). Empirically, passing a higher value is not rejected — the call is silently accepted (clamped or ignored), so the documented ceiling is not a hard gate.timeout_ms at 45000 — values above 45 seconds are silently clamped, and long-running commands die mid-execution.Undocumented runtime behaviors — prerequisite calls, path resolution, side effects.
conversation_search does keyword matching, not semantic search; meta-words like 'conversation' or 'chat' in your query poison the results and surface unrelated hits.Edit fails with "String to replace not found" when old_string includes Read's line-number prefixverifiedRead returns content in cat -n format (<line>\t<text>). If a skill copies a line from that output straight into Edit's old_string, the leading line number and tab are not part of the file, so the match fails with "String to replace not found in file."Edit errors unless Read was called on the same file earlier in the same conversation — even if your skill just wrote it.Write refuses to overwrite an existing file unless Read was called on that path earlier in the conversation — even when the overwrite is intentional.Bash call effectively starts in the project working directory with a fresh shell — a cd in one call, and exported variables, do not carry over to the next. The harness resets cwd back to the project directory after every call.Bash tool description embeds a git safety policy — refusing --amend, --no-verify, reset --hard, force-push, etc. without explicit user permission.Read resolves relative paths against the current working directory, not the skill's own directory — Read('references/foo.md') from a skill rarely finds the file.cd, and background jobs from a previous call do not carry over to the next.view tool rejects relative paths and bare filenames with a validation error; only absolute paths starting at / work.Divergences across Claude.ai, Claude Code, and Claude Desktop.
AskUserQuestion/ask_user_input_v0 picker does.AskUserQuestion (Code/Desktop) and ask_user_input_v0 (Claude.ai) serve the same purpose but have different schemas, different limits, and different question/option caps.Edit accepts a replace_all flag; Claude.ai's str_replace_based_edit_tool has no equivalent and requires unique matches.view tool can list a directory's contents; on Claude Code and Desktop the Read tool errors on directory paths.Write overwrites existing files silently; Claude.ai's create_file refuses to overwrite and errors. The most dangerous cross-platform divergence in the catalog.search_mcp_registry and suggest_connectors exist on Claude.ai but not on Claude Code; skills that rely on runtime MCP discovery silently misbehave there.server__tool on some surfaces and mcp__server__tool on others — hardcoding either form breaks the skill on the other.conversation_search on Claude.ai, a different shape on Desktop, and isn't available on Claude Code — same intent, three implementations.Sandbox, filesystem, and network constraints.
/mnt/user-data/uploads/ on Claude.ai is read-only — skills that try to write there for round-tripping uploaded files fail with a permission error. Use /mnt/user-data/outputs/.~, host paths, and host-installed binaries are not present.curl to arbitrary domains fails with a network error, not a DNS error./mnt/user-data/outputs/.pip install <pkg> on Claude.ai's bash sandbox fails with 'externally-managed-environment' (PEP 668); add --break-system-packages or use a venv.SKILL.md authoring traps — file paths, references, hot-reload.
references/foo.md pattern recommended by skill-creator does not resolve relative to the skill's own directory at runtime — you must construct the absolute path yourself.No pitfalls match your search.