The contract: every rule on one page

Where should my skill write files, and which path forms work?9 rules

Treat a folder the user connected as a separate mount with its own rules, not as part of the workspace.

SILENTMeasured2026-08-05

Do not assume a connected project gives you a folder mount. It does not.

LOUDMeasured2026-08-05

Give the file tools the absolute outputs path; give the shell the absolute session outputs path. No single form works for both.

LOUDMeasured2026-09-23

Producing a file is not delivering it — and where your working directory lands differs by lane.

SILENTMeasured2026-09-23

Never pass an absolute session path to the file tools. It is denied, not translated.

LOUDMeasured2026-09-23

Treat your own skill's files as read-only at runtime.

LOUDMeasured2026-08-05

Treat the uploads location as read-only and write everything to the outputs location.

LOUDMeasured2026-08-05

Find an uploaded file from the message that announced it, never from a fixed uploads directory.

SILENTMeasured2026-09-05

Always give search tools an explicit folder.

SILENTMeasured2026-09-23

Why did my skill's output never reach the user?9 rules

Do not rely on writing a file to a directory as the act of delivering it.

SILENTMeasured2026-08-05

Write the deliverable to a stated path, then present it to the user. If you cannot present it, say where it is.

SILENTFrom binary2026-08-05

State the path of what you produced even when a delivery tool worked.

FRICTIONInference2026-09-05

Never call a tool that writes to the user's own disk from inside a skill.

SILENTFrom binary2026-08-05

Do not deliver by starting a local server and opening it. Write a self-contained file and present that.

LOUDMeasured2026-08-14

Do not hand-copy files into the outputs location before presenting them.

FRICTIONFrom binary2026-08-05

Assume the session filesystem does not outlive the session.

SILENTMeasured2026-08-05

Assume your skill may run in either sandbox, and never assume which one.

SILENTMeasured2026-08-05

Nothing will report progress for you — if a long run should say anything mid-way, your skill has to say it.

FRICTIONMeasured2026-09-05

Why does deleting a file fail, and what should my skill do?6 rules

Treat needing a delete as a design smell, because getting one interrupts the user.

FRICTIONMeasured2026-08-05

Do not assume that approval to delete in one location applies anywhere else.

FRICTIONMeasured2026-08-05

Do not move files between mounts with a rename. Copy, then verify.

LOUDMeasured2026-08-05

Expect removing a file or a directory to fail with a permission error on every Cowork mount.

LOUDMeasured2026-08-05

Expect the agent to ask for delete permission on its own the first time a removal fails.

FRICTIONFrom binary2026-08-05

Do not treat a file vanishing from its old path as evidence that it was deleted.

SILENTMeasured2026-08-05

What does my skill's shell see?8 rules

Do not treat the home directory as a private place that outlives the session.

SILENTMeasured2026-08-05

Do not use the inline shell-execution syntax in skill instructions and expect it to run.

SILENTFrom binary2026-08-05

Do not rely on arbitrary outbound network access from shell commands.

LOUDMeasured2026-08-05

Prefer what is preinstalled, and never install globally. A user-scoped or project-local install works, but treat it as a fallback.

LOUDMeasured2026-08-05

Do not assume the sandbox has no third-party libraries. It ships a large preinstalled stack.

FRICTIONMeasured2026-09-05

Do not expect to read or write anything outside your own session, and do not rely on the identity your shell runs as.

LOUDMeasured2026-09-05

Do not pass configuration to your skill's shell commands through the environment.

SILENTMeasured2026-08-05

Do not assume the shell tool has the same name it has in the CLI.

LOUDMeasured2026-08-05

How should my skill detect that it is running in Cowork?7 rules

For behaviour rather than reporting, branch on which tools exist instead of on the environment.

SILENTMeasured2026-08-05

Do not hard-fail when a runtime marker is missing. Fall through to the next check.

SILENTMeasured2026-08-05

Do not detect Cowork with a bare environment-variable check.

SILENTMeasured2026-09-05

Detect the runtime with an ordered sequence of checks, not a single environment test.

SILENTMeasured2026-09-23

Remember your skill spans two execution contexts, and test the one you are actually in.

SILENTMeasured2026-09-05

Expect the two-context split, and the missing shell markers, only in the local sandbox.

SILENTMeasured2026-09-23

Check that your own plugin's files are reachable before doing any work, and stop if they are not.

SILENTMeasured2026-09-05

Will my plugin's hooks and scripts run in Cowork?19 rules

Do not use a hook to export environment variables for your skill's shell commands.

SILENTMeasured2026-08-05

Expect plugin hooks to fire in Cowork.

FRICTIONMeasured2026-09-05

Install a plugin through the Cowork application if you want Cowork sessions to see it.

LOUDMeasured2026-08-05

Do not write into your plugin's own directory at runtime.

LOUDMeasured2026-08-05

Expect plugin files to be present as a mounted directory, and find it rather than hardcoding it.

LOUDMeasured2026-08-05

Use ${CLAUDE_PLUGIN_ROOT} for file-tool reads, and discover the mounted path at runtime for anything you execute.

SILENTFrom binary2026-08-14

Ship a launcher in your plugin's bin/ and call it as a bare command.

FRICTIONMeasured2026-08-14

${CLAUDE_SKILL_DIR} works in your SKILL.md body and nowhere else.

SILENTFrom binary2026-08-14

Your skill's description is the only thing that decides whether it gets used.

FRICTIONFrom binary2026-08-14

If your plugin ships an MCP server, make it a stdio command with no user-configuration placeholders, and expect it to run on the user's machine rather than in the sandbox.

SILENTFrom binary2026-09-05

Do not name a server memory in the desktop application's MCP configuration; a plugin's own memory server is safe.

SILENTFrom binary2026-09-23

Ship Cowork skills in a plugin, not in a project's .claude/skills folder.

SILENTFrom binary2026-09-23

Expect your plugin's local MCP server to work in Cowork, and a remote one to be replaced when the user already has that service connected.

SILENTMeasured2026-09-23

Do not write exact MCP tool names for connectors or a plugin's remote servers into your skill.

SILENTMeasured2026-09-23

When testing a plugin you also have installed, check which copy actually loaded.

SILENTFrom binary2026-09-23

Put your skill's trigger words in its name, and keep its description short.

SILENTFrom binary2026-09-23

Do not mark a hook to run for cloud sessions unless you accept that the session may have written what it runs.

LOUDFrom binary2026-09-23

Do not conclude your hook did not fire because a local Cowork session's records do not show it.

SILENTMeasured2026-09-23

Do not rely on a forked skill's exact output reaching the user.

SILENTMeasured2026-09-23

What changes when my skill dispatches sub-agents?7 rules

Always name the agent type when dispatching a sub-agent.

LOUDMeasured2026-08-05

Do not plan to resume a finished sub-agent. Dispatch a fresh one with the context restated.

LOUDFrom binary2026-08-05

Do not use a sub-agent to get around a path restriction or a permission prompt.

FRICTIONMeasured2026-08-05

Put everything a sub-agent needs in its prompt. It cannot ask you for more.

SILENTInference2026-08-05

Write sub-agent fan-out so that a dispatch being queued or refused is handled, not fatal.

LOUDFrom binary2026-08-05

Write sub-agent prompts with the absolute outputs path, as the sub-agent's own instructions now ask.

LOUDMeasured2026-09-23

Do not design a sub-agent that itself dispatches sub-agents.

SILENTFrom binary2026-09-05

How should my skill ask the user for missing arguments?1 rules

Do not build your skill's argument collection around AskUserQuestion in Cowork.

FRICTIONFrom binary2026-09-23

What can change without any version bump?9 rules

Detect capabilities at the moment you use them, and state a clear fallback when they are missing.

SILENTMeasured2026-08-05

Do not assume configuration is fixed for the lifetime of a session.

SILENTFrom binary2026-08-05

Never write a skill that depends on the exact wording of the system prompt.

SILENTFrom binary2026-08-05

Do not treat 'the version has not changed' as evidence that behaviour has not changed.

SILENTMeasured2026-08-05

Assume tool availability and defaults are served to the session, not shipped in the application.

SILENTMeasured2026-08-05

Write down which behaviours your skill depends on, in the skill itself.

FRICTIONInference2026-08-05

Do not hardcode a tool name your skill merely hopes is present.

LOUDMeasured2026-08-05

Your skill's own text can be shortened, or dropped entirely, part-way through a session — put what must survive near the top.

SILENTMeasured2026-08-14

When the capability that is missing is one that CHECKS your work, stop and say so rather than continuing without it.

SILENTInference2026-09-05