[skill-creator] Add Cowork/VM isolation writing pattern to skill authoring guide
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:
- Search for credential files in the VM (
~/.env,MEMORY.md, JSON config files, etc.) - Find nothing
- 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
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗