Distribution and reuse

Read these first

• Testing and iterating on skills
• Config hygiene

What you will know

• Package a skill or server for a team to install

  A fresh teammate environment should install pinned dependencies and expose the expected entry points without local paths or undocumented secrets.

• Version it and communicate a breaking change

  Consumers must distinguish compatible from incompatible releases and have a migration path instead of silently receiving changed behavior.

• Put team-shared agent configuration under review

  Review is the control for prompt injection, tool permissions, secret exposure, and accidental organization-wide behavior changes.

• Add a regression test and changelog entry for a shared skill or server change

  The test should catch a behavior regression, while the changelog lets operators correlate the change with a released artifact.

• Onboard a colleague onto the shared setup without hand-holding

  A colleague should complete setup from the repository and verify a known task, revealing missing credentials, permissions, or platform assumptions.

Chapters

1. 1

   Six copies in Slack are not a shared artefact

   A popular local skill gets zipped into a channel, six people copy it in, and three weeks later two report broken output. There is no version, no source of truth and no way to tell which copy anyone runs, so a bug report cannot be tied to a revision and a fix cannot reach the people affected. Establishes what has to leave your machine to make one: pinned dependencies, declared entry points, no local paths, no undocumented secrets.

   Read chapter
2. 2

   The new joiner is the only honest packaging test

   Everyone on the team following your README proves little, because they share your base image, your global installs and credentials already sitting in their shells from other work. Success on prepared machines is exactly the population that cannot reveal an undeclared assumption. Covers running the install from a clean environment against a known task, what a CI job catches, and the platform and credential gaps it will still miss.

   Read chapter
3. 3

   A change consumers cannot see is still breaking

   Tightening a skill's description so it stops firing on requests it handled badly feels like a bug fix, but the quality judgement is yours and the dependence is theirs — no error, no diff, just guidance that stops arriving. Learn to classify changes from the consumer's side, find who relies on the behaviour before removing it, and ship a response-shape change to a shared MCP server the survivable way: new alongside old, a dated deprecation, migration before removal.

   Read chapter
4. 4

   Nothing declares a dependency on a skill that simply fires

   This is the one way a shared skill is not like a library: no consumer ever imported it, so there is no graph to read and no way to answer who depends on this from the repository alone. The evidence has to be manufactured — activation telemetry recording when the skill fired and on what kind of request, a sample of the requests that matched the description you are about to narrow, and, where telemetry does not exist yet, going to the five teams with a concrete list of example requests rather than a description of the change, because they cannot recognise a dependency stated abstractly either. The same record is what lets a regression test be scoped to the behaviours consumers actually use rather than the ones you remember writing.

   Read chapter
5. 5

   Behaviour changes need a release to correlate against

   Someone edits a shared skill's body to change how migrations are formatted; two weeks later a consuming team's migrations start failing review and they have nothing but the calendar to line their failures up with. A released version plus a changelog entry gives operators the correlation, and a regression test on the shared repository catches the behaviour change before it ships. Covers what the test should assert and what the entry should say.

   Read chapter
6. 6

   Reviewers of shared config look for permissions and instructions

   A reviewer asked what they are checking needs a concrete answer: whether the change grants new tool permissions, exposes a secret, or introduces text that every agent loading the file will treat as instructions. That last one explains why ranking scrutiny by file size gets it backwards — a one-line description edit imposes or withdraws a capability across all consumers, and an unreviewed bundled reference is authoritative content an outside contributor may have written.

   Read chapter
7. 7

   An unowned server outranks slow onboarding

   Eighteen months in you have 60 skills, 9 servers, two-day onboarding, three servers with no identifiable owner and two teams running forked config. Onboarding time is the visible number and the least serious fact: it improves with a setup script and returns as the catalogue grows. Learn to rank by which fact produces an incident nobody can respond to, and what your chosen fix will look like it has failed at three months in.

   Read chapter