Reusable Patterns for Claude Cowork Plugin Design

The first Claude Cowork plugin you ship will work. The fifth one your team ships — built by someone else, copied from the second, patched by a third person — is where the cracks appear. Skills load when they shouldn't, two plugins fight over the same connector, and a prompt that was crisp in isolation becomes mush when three skills are live at once. The fix isn't more cleverness; it's a small set of reusable patterns applied consistently. This post is a field guide to those patterns at the code and structure level.

I'll frame each as a named pattern with the problem it solves, because that's how they'll actually show up in a code review: "this skill needs the narrow-trigger pattern," not a paragraph of advice.

Pattern 1: One skill, one job, one trigger

The single most valuable pattern is keeping each skill scoped to one job with one unambiguous trigger line. Cowork's router reads only the short description to decide whether to load a skill, so overlapping or broad descriptions are how you get the wrong skill firing. If you find yourself writing "and also" in a skill description, that's two skills.

Concretely: a skill named "invoice-reconciliation" with the trigger "Match incoming payments to open invoices" will route reliably. A skill named "finance-helper" that reconciles invoices, drafts emails, and explains policy will route unpredictably, because half the requests in a finance conversation look plausibly relevant to it. Split it. Small skills compose; big skills collide.

Pattern 2: Progressive disclosure of context

A skill body should be layered so the cheap, always-useful part loads first and the heavy reference material loads only when needed. Put the core procedure in the entry file and push examples, lookup tables, and edge-case handling into separate reference files the model pulls in on demand. This keeps the context lean for the common case and deep for the rare one.

flowchart TD
  A["Request enters Cowork"] --> B["Load skill entry file"]
  B --> C{"Edge case or detail needed?"}
  C -->|No| D["Run core procedure"]
  C -->|Yes| E["Pull reference file into context"]
  E --> D
  D --> F{"External action?"}
  F -->|Yes| G["Call typed tool"]
  F -->|No| H["Return result"]
  G --> H

The pattern matters most across an enterprise, where the same skill serves people with very different requests. Progressive disclosure means the analyst running the routine case and the one chasing a weird exception both get a tuned context without you maintaining two skills.

Pattern 3: Typed tools with narrow surfaces

When you define connector tools, prefer many narrow tools over one wide tool with a mode flag. get_invoice, list_open_invoices, and mark_paid each have a clear schema and an obvious permission. A single invoice_op tool with an "action" parameter forces the model to get two things right at once and makes role-scoping clumsy. Narrow tools are easier for the model to call correctly and easier for security to reason about.

Pair each tool with a schema that's strict where it matters: required fields marked required, enums for closed sets, sensible bounds. The schema is the only thing standing between the model's intent and a malformed write, so treat it as production code, not documentation. And design tools to return structured, readable errors — a tool that returns "error: 422" gives the model nothing to recover with; one that returns "amount must be positive" lets it fix the call.

Pattern 4: Context hygiene at the orchestrator

The orchestrating agent's context is a shared resource, and the fastest way to degrade a long Cowork session is to dump raw tool output into it. The pattern is to summarize at the boundary: when a tool returns a large payload, have the relevant skill instruct the model to extract what it needs and discard the rest, rather than carrying the full blob forward. The same applies to sub-agent results — they should hand back conclusions, not transcripts.

This is why delegation and context hygiene go together. A sub-agent isn't just for parallelism; it's a context firewall. The forty-invoice reconciliation can churn through megabytes of detail inside sub-agents and return a clean summary, leaving the orchestrator's context pristine for the next request in the conversation.

Pattern 5: Idempotent writes by construction

Any tool that changes a system of record should be safe to call twice. The pattern is to make writes carry a client-supplied key the underlying system can dedupe on, so a retried create_task doesn't produce two tasks. Agents retry — after a timeout, after a model reconsiders — and an enterprise plugin that double-books on retry will lose trust fast. Bake idempotency into the connector so the model doesn't have to reason about it.

Where true idempotency isn't possible, fall back to read-before-write: have the model check whether the task already exists before creating it. It's slower and less reliable than a real idempotency key, but it beats silent duplication.

Pattern 6: Versioned, scoped, and observable

The last pattern is operational. Every plugin carries a version; every connector carries a scope tied to role; every tool call is logged with who, what, and against which record. None of this is glamorous, but it's what lets you ship a plugin to three departments and still answer "what did it do in HR last Tuesday?" Without versioning you can't roll back a bad skill change; without scoped connectors one team's plugin can reach another's data; without logs you're debugging blind.

Frequently asked questions

Why prefer many narrow tools over one flexible tool?

Narrow tools give the model a clear schema and an obvious permission per action, so it calls them correctly and security can scope them individually. A single multi-mode tool forces the model to pick the action and the arguments at once and makes role-based access clumsy.

What is progressive disclosure in a skill?

It's layering the skill so the core procedure loads first and heavier reference material loads only when a request needs it. This keeps the common case lean on context while still giving the model depth for edge cases.

How do I keep a long Cowork session from degrading?

Practice context hygiene: summarize large tool outputs at the boundary instead of carrying raw payloads forward, and use sub-agents as context firewalls that return conclusions rather than full transcripts.

How do I make agent writes safe to retry?

Make them idempotent by having write tools carry a client-supplied key the system dedupes on, so a retried call doesn't create a duplicate. Where that's impossible, have the model read before writing.

Bringing agentic AI to your phone lines

These patterns — narrow tools, clean context, idempotent writes — are exactly what keep CallSphere's voice and chat agents dependable when they take real calls, use tools mid-conversation, and write bookings into your systems. See the patterns in action at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.