It Worked on My Machine, but Nobody Could Trigger It — Four Assumptions I Stripped Out of a Cowork Plugin

Assumption 1: the description was tuned to my own vocabulary

This accounted for most of the misses.

Cowork and Claude Code pick skills using the description in the SKILL.md frontmatter. Which means the description is not documentation — it is routing input. Write it as a human-facing blurb and it will not route.

Mine started out like this.

---
name: weekly-report
description: Generates the weekly report
---

It never failed me. I always say "generate the weekly report," so the literal string was right there in my prompt.

My friend says "can I get a summary for this week" and "pull last week's numbers." Neither contains "weekly" or "report."

The rewrite:

---
name: weekly-report
description: >-
  Aggregates the last seven days of sales and usage data into a Markdown
  report and posts it to Slack. Use when the user asks for any retrospective
  rollup over a recent period — "weekly report", "summary for this week",
  "last week's numbers", "how did last week go", "week in review".
  Do not use for a single one-off metric lookup (query it directly instead).
  Do not use for monthly or quarterly rollups (use monthly-report).
---

Three rules came out of the rewrite.

1. Describe the intent, not the feature. Not "generates the weekly report" but "when the user asks for a retrospective rollup over a recent period." Write the situation, not your wording of it.
2. Include the cluster of phrasings. Synonyms, casual forms, whatever people actually type. The phrasings you would never use are the valuable ones.
3. State when not to use it. One "do not use for..." line draws the border with the skill next door.

The third one surprised me. Pile up only positive conditions and neighboring skills start fighting over the same utterance. Negative conditions are what make the boundary legible.

That rewrite alone took his trigger rate from 25% to 65%. Not good enough yet, but one cause was provably gone.

I touched on description design in Writing Skill Files in Markdown as well; rereading it through a routing lens surfaces different things.

Assumption 2: paths were welded to my folder layout

The next cluster: fires, then dies quietly.

The skill said, in plain text:

1. Read `/Users/masaki/Dropbox/Workspace/data/sales.csv`
2. Filter to the last seven days and aggregate

Correct path on my Mac. Nonexistent on anyone else's.

It reads like a joke, but I could not see it while writing. The tests passed. As long as you test in your own environment, environment coupling is invisible by construction.

I settled on pushing the input location out to an environment variable and listing it as required in the README.

## Inputs
 
- Sales data: `${SALES_DATA_PATH}` (if unset, ask the user where it lives)
- Destination channel: `${SLACK_REPORT_CHANNEL}` (default: #reports)
 
If `SALES_DATA_PATH` is unset and the user cannot say where the file is,
stop there. Do not guess at a similar-looking file.

That last line is earned. When a path is missing, Claude helpfully goes looking for something nearby. It reads an unrelated CSV, produces a plausible report, and finishes clean. That was by far the worst failure mode — no error, so nobody notices.

If it isn't there, stop. If it's ambiguous, ask. Never guess. Those three lines change how safe the plugin is in someone else's hands.

Assumption 3: I assumed everything was already connected

The third one made me wince at my own code.

On my machine, GitHub and Slack and Google Drive have been connected for ages. I wired them up six months ago and have not thought about it since. The plugin naturally calls all of them.

My friend had no Slack connector. The plugin died on the post step, and the aggregation it had already finished was thrown away.

The lesson: you cannot ship your environment's state, only its files. Six months of connections, authorizations, and settings do not fit in the ZIP.

So I put a dependency check at the top of each skill.

## Before running
 
This skill depends on the following. Check availability first and tell the
user about anything missing **before starting work**.
 
| Requirement | Used for | If missing |
|---|---|---|
| GitHub connector | Fetching and updating issues | Stop, explain setup |
| Slack connector | Posting the report | Skip the post, save the file, continue |
| SALES_DATA_PATH | Location of the sales data | Ask the user |
 
A missing Slack connector is not a reason to abort. Finish the aggregation
and leave the artifact behind.

The "if missing" column is the important one. Make every dependency mandatory and one gap kills the whole plugin. Make them all optional and you get silently degraded results.

Decide, per dependency, whether to abort or degrade. Only the author can make that call — the person installing it has no idea what the assumptions were.

For connector setup and health, The Cowork Connectors Guide and Building Connector Observability for Solo Ops are both relevant here.

Assumption 4: I assumed nothing else would compete

The last one never crossed my mind until I read the logs.

For "sort through the issues that piled up," the winner was not my issue-triage. It was a skill from a different plugin my friend already had installed.

I don't have that plugin. Collisions were impossible in my world. I had been arranging furniture in an empty room; his room already had furniture in it.

A distributed plugin always lands inside someone else's collection of skills. Being optimal in isolation guarantees nothing.

I don't have a complete answer here — you cannot know what else people have installed. But a few things reduce the damage.

• Make names specific. acme-weekly-sales-report, not report. Generic names collide.
• Lean on the "do not use for" lines. Rule three from Assumption 1 pays off again here.
• List known conflicts in the README. Partial knowledge, shared early, still helps.

With all three in, the re-measurement came back 17 of 20. 85%. Short of my own 90%, but usable.

The full progression:

A 30-minute preflight before you ship

Whatever a machine can catch, let the machine catch. This script hunts for absolute paths, raw credentials, undocumented env vars, and names that are too generic to survive contact with other plugins.

#!/usr/bin/env bash
# plugin-preflight.sh — find environment coupling before distribution
# usage: ./plugin-preflight.sh ./my-plugin
set -uo pipefail
 
DIR="${1:?usage: plugin-preflight.sh <plugin-dir>}"
FILES=(--include='*.md' --include='*.json' --include='*.sh' --include='*.yaml')
fail=0
 
section() { printf '\n== %s ==\n' "$1"; }
ng()      { printf '  NG   %s\n' "$1"; fail=1; }
ok()      { printf '  ok   %s\n' "$1"; }
 
section "User-specific absolute paths"
if hits=$(grep -rnE '(/Users/[^/[:space:]"]+|/home/[^/[:space:]"]+|C:\\\\Users\\\\)' "$DIR" "${FILES[@]}"); then
  printf '%s\n' "$hits" | sed 's/^/       /'
  ng "A personal home directory is baked in"
else
  ok "none found"
fi
 
section "Raw credentials"
if hits=$(grep -rnE '(sk-ant-[A-Za-z0-9_-]{8,}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,})' "$DIR" "${FILES[@]}"); then
  printf '%s\n' "$hits" | sed 's/^/       /'
  ng "Something looks like a credential (use YOUR_API_KEY instead)"
else
  ok "none found"
fi
 
section "Referenced env vars documented in README"
# Process substitution, not a pipe: a pipe puts the loop in a subshell
# and fail=1 never reaches the caller.
while read -r var; do
  [ -z "$var" ] && continue
  if grep -q -- "$var" "$DIR/README.md" 2>/dev/null; then
    ok "$var (documented)"
  else
    ng "$var (not in README — nobody can configure it)"
  fi
done < <(grep -rhoE '\$\{[A-Z][A-Z0-9_]{2,}\}' "$DIR" "${FILES[@]}" | tr -d '${}' | sort -u)
 
section "Collision-prone skill names"
while read -r skill; do
  base=$(basename "$(dirname "$skill")")
  case "$base" in
    report|triage|sync|analyze|publish|notify|check|update)
      ng "$base (too generic — add an org or domain prefix)" ;;
    *) ok "$base" ;;
  esac
done < <(find "$DIR" -name 'SKILL.md' 2>/dev/null)
 
section "Result"
if [ "$fail" -eq 0 ]; then
  echo "  preflight passed"
else
  echo "  resolve the NG items above before shipping"
fi
exit "$fail"

The env var check uses while ... done < <(...) rather than a pipe because a pipe runs the loop in a subshell and fail=1 never escapes it. I learned that the hard way: every check was failing and the script still exited 0, so CI stayed green.

A machine only finds traces. Description quality and dependency design still come down to judgment. But a hardcoded home directory has not slipped through since.

What machines miss, other people's machines find

Preflight cannot measure trigger rate. What's left is running it somewhere that isn't yours.

You can't become another person, but you can get closer. My order of operations now:

1. Start from a fresh profile. No existing settings, no existing connections.
2. Write cases in phrasings you don't use. The hardest step and the highest-value one. Getting someone else to write the sample utterances turned out to be the only reliable way out of my own vocabulary.
3. Run skill-trigger-check.sh; don't ship below 80%. With a number, you can tell whether the fix worked.
4. Hand it to exactly one person and read their logs for a week. The misses that show up there are the best test cases you will ever get.

Step four felt rude. You are handing someone something broken and asking for their time. But my head will never produce phrasings from outside my own head. Leaning on that first person was the fastest route.

Where to start

If you have a skill running happily on your machine and someone waiting for it, write ten lines of cases.jsonl before you ship — in phrasings you would never use yourself.

If the trigger rate lands under 90%, one of these four assumptions is in there. The MISS rows will tell you which.

I am still working this out, particularly the collision problem, which I have no principled answer for yet. If you are wrestling with the same thing, I would like to compare notes. Thank you for reading.