Verified 2026-09-23
view as .md

Writing skills that survive Cowork

Claude Cowork runs your skill in a sandbox with rules that differ from the Claude Code CLI in ways that will silently break an otherwise-correct skill. This site covers the nine failure modes that actually show up: wrong path forms, deliverables that vanish on delivery, delete calls that fail with a permission error, a shell that cannot see your environment, runtime detection that reports the wrong answer, plugin paths that resolve differently per consumer, an input prompt the host steers away from, sub-agent assumptions that do not hold, and behaviour that changes with no version bump at all.

Derived from shipped binaries and live sessions. This site does not detect product changes.

Start from the symptom

What you saw → why → what to do instead
Tool refused the path your shell just printed
The file tools reject the shell’s absolute form outright — a literal prefix test, not a translation.
Pass the outputs location's absolute path.
Your file exists, the user never saw it
The working directory is a scratch space that is never presented or listed.
Present it, and state the path.
rm / rmdir fails with a permission error
Every Cowork mount denies exactly those two operations by default.
Design so no delete is needed.
Moving a file between mounts fails
A rename cannot cross a mount boundary.
Copy, then verify.
Your env var is empty inside the shell
The shell is sealed: host exports and hook exports do not reach it.
Pass config as arguments.
Detection reports “not Cowork” inside Cowork
The part of your skill running shell commands has none of those markers set.
Use ordered checks; branch on tools.
A global install fails or disappears
Global installs do not take effect, and nothing persists past the session.
Prefer the preinstalled stack.
A tool name from the CLI does not exist
Tool surfaces are served to the session, not shipped in the app.
Check it exists before naming it.
A long run goes silent and the user asks what is happening
Nothing in the runtime narrates, and the one nudge meant to break a silent stretch was never observed firing.
Write the progress messages into the skill, at the steps that matter.
Your skill says nothing was attached, but the user attached a file
It looked in a fixed uploads directory; the file is somewhere else in this sandbox.
Resolve the path from the message that announced the attachment.
Your plugin's MCP tools are missing in a cloud session
The sandbox does not start them; the Desktop app on the user's machine does, and only for stdio servers while it is open.
Ship a stdio command (shim an HTTP endpoint), drop user-configuration placeholders, and tell users to keep Desktop open.
Your skill ran, but none of its scripts or sub-agents did
A surface can serve your skill's text without your plugin around it, and nothing announces that.
Test for a file you ship and cannot work without, and stop when it is missing.

The five that break the most skills

If you read nothing else.

  1. 01
    Write to the absolute outputs path.
    Absolute session paths are denied by the file tools every time, and from Desktop 2.7032.0 so are bare filenames.
  2. 02
    Producing a file is not delivering it.
    Write to a stated path, present it, and name the path anyway.
  3. 03
    Never pass configuration through the environment.
    The shell your skill runs in is sealed — including from your own hooks.
  4. 04
    Detect the runtime with ordered checks.
    A bare environment-variable check false-negatives where it matters most.
  5. 05
    Detect capabilities at the moment you use them.
    The surface is served, not shipped. It can change mid-session.

How to read the labels

Confidence — how we know
MEASUREDFROM BINARYINFERENCE
Neutral on purpose. Provenance is not severity.
Severity — what it costs you
Breaks silently Fails loudly Costs friction
Editorial, not measured — a judgement about consequence.

9 failure modes, one page each

Where should my skill write files, and which path forms work?
9 rules
The shell and the file tools need DIFFERENT path forms. There is no form correct for both.
Why did my skill's output never reach the user?
9 rules
Two sandboxes that disagree about what delivering a file means.
Why does deleting a file fail, and what should my skill do?
6 rules
Every mount denies removing a file and removing a directory.
What does my skill's shell see?
8 rules
Sealed environment, no arbitrary network, a large preinstalled stack.
How should my skill detect that it is running in Cowork?
7 rules
Why the naive check false-negatives, and the ordered recipe that works.
Will my plugin's hooks and scripts run in Cowork?
19 rules
Hooks do fire. Plugin root resolves differently per consumer.
What changes when my skill dispatches sub-agents?
7 rules
Same containment as the main thread. Self-contained prompts only.
How should my skill ask the user for missing arguments?
1 rules
Cowork steers skills toward the elicitation form, not AskUserQuestion.
What can change without any version bump?
9 rules
Served, not shipped: what moves with no version bump and no signal.

Where this fits in your workflow

Same author as this site, and not part of the verified material.
Starting a skill
skill-creator-plus

A skill for building skills: draft, run evals against a baseline, review the results, iterate. Based on Anthropic's skill-creator and substantially reworked since. Its runtime reference encodes several of the rules documented here — including the two-sandbox delivery split and the fact that a rendered page has no way to send anything back — so a skill scaffolded with it starts on the right side of them.

Checking a skill you already have
cowork-harness

Runs a skill against Cowork's runtime contract from scenario files — including whether it triggers at all, how it behaves in each sandbox, and whether its output actually gets delivered. Has a replay mode that runs in CI. Every rule here raises the same question — does mine do this? — and clicking through a real session to find out is slow, and easy to get wrong in exactly the ways this site documents.

75 rules in total · see them all on one page