[skill-creator] Add Cowork/VM isolation writing pattern to skill authoring guide

Resolved 💬 3 comments Opened Mar 29, 2026 by ydmw74 Closed Apr 29, 2026

Summary

The skill-creator SKILL.md lacks guidance for a common failure mode: skills that rely on external credentials or configuration (remote MCP servers, APIs, Mac filesystem) silently fail in Cowork because Claude searches the isolated VM filesystem instead of querying the authoritative source.

Problem

Cowork sessions run in isolated VMs with no access to the user's local Mac filesystem. When a skill uses a remote MCP server (e.g. a banking API, a home-automation server, or any tool with server-side credentials), Claude's default behavior when credentials are needed is to:

  1. Search for credential files in the VM (~/.env, MEMORY.md, JSON config files, etc.)
  2. Find nothing
  3. Ask the user for credentials they shouldn't need to provide

This happens even when the skill correctly documents a fints_get_config-style "fetch config from the MCP tool" step — because the skill-creator's writing guide never tells skill authors to explicitly suppress the local-search behavior.

Concrete Example

We built a skill for German online banking (fints-banking) backed by an HBCI/FinTS MCP server running on a remote host. The MCP server exposes a fints_get_config() tool that returns bank_id, user_id, and customer_id — so no credentials ever need to come from the user or the local filesystem.

Despite this, Cowork sessions consistently:

  • Loaded the skill ✓
  • Searched MEMORY.md, ~/.env, and various config paths in the VM ✗
  • Timed out on fints_list_accounts({}) (no params) ✗
  • Asked the user for BLZ, Benutzer-ID, Kunden-ID ✗

Fix that worked: Adding an explicit section to the skill's SKILL.md body:

## Important: No local filesystem access

This skill may run in an isolated VM without access to the Mac filesystem.
Do NOT search locally for credentials or config files.
All required credentials come from the MCP server — call `fints_get_config()` first.

Once this was added, Cowork correctly called fints_get_config()fints_list_accounts()fints_get_balances() in sequence without any user prompting.

Proposed Fix

Add a Cowork/VM isolation pattern to the #### Writing Patterns section of skill-creator/SKILL.md, between the "Examples pattern" block and "### Writing Style":

**Cowork/VM isolation pattern** — Skills run in Cowork execute inside an isolated VM
with no access to the user's local Mac filesystem. If your skill relies on credentials,
configuration, or data that lives outside the VM (e.g. on a remote MCP server, an API,
or the Mac filesystem via `mcp__Control_your_Mac__osascript`), make this explicit at the
top of the SKILL.md body. Include a short section like:

\```markdown
## Important: No local filesystem access

This skill may run in an isolated VM without access to the Mac filesystem.
Do NOT search locally for credentials or config files.
All required credentials come from [source] — call [tool/step] first.
\```

The key ingredients: (1) tell Claude not to search locally, (2) name the authoritative
source, (3) name the first tool call or step to retrieve what's needed. Without this,
Claude will waste time searching the VM filesystem and then ask the user for credentials
it could have fetched itself.

Why This Matters

  • Affects any skill backed by a remote MCP server with server-side credentials
  • The failure is silent and confusing — Claude looks competent (it searches!) but produces the wrong behavior
  • The fix is a one-time documentation addition to skill-creator, preventing the issue for all future skills

Environment

  • macOS, Claude Desktop latest
  • Cowork session
  • Affected skill type: remote MCP server with server-side credential store

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗