A Shared Skills Repository for Every Agent

Make the repository authoritative

If Claude Code reviews database changes using last month's checklist while Cursor uses an edited copy, sharing a filename has achieved little. Give the procedure one maintained home and make every installation traceable to it. Treat local skill directories as deployment targets; changes go back through the repository before becoming the team's next release.

Start with a narrow catalog: database change review, incident evidence collection, and release verification, for example. Give each skill an owner, an intended trigger and an observable result. Keep project facts in project instructions and task procedures in skills. The distinction matters when a procedure changes independently of an application's source tree; keeping agent instruction files in sync addresses the other half.

Choose either a common approved release for routine work or a pinned release for reproducible jobs. Document which policy applies before distributing anything.

Package complete procedures, not isolated Markdown

The Agent Skills specification defines a directory containing SKILL.md, with YAML frontmatter and Markdown instructions. Its required name must match the directory, and its description explains both purpose and trigger. Optional scripts, references and assets belong with the skill. Keep relative references inside that package so a clean machine can resolve them.

skills/
  database-change-review/
    SKILL.md
    references/
      review-checklist.md

For that directory, a small starting procedure could be:

---
name: database-change-review
description: Review a proposed database migration for locking, rollback, and application compatibility before approval.
metadata:
  owner: platform
---
Read references/review-checklist.md.
Inspect the proposed migration and its rollback plan.
Report locking risks, compatibility assumptions, and missing evidence.
Do not apply the migration.
If the target database version is unknown, ask for it.

Keep the common procedure independent of a particular client's shell wrapper or approval syntax. Put client-specific behavior in its adapter and test it there. A portable file format cannot establish identical execution behavior. For authoring details, see writing skills that work across agents.

Promote a release and record its commit

Use ordinary Git review to promote a candidate catalog. In this example, replace the repository URL and tag with your team's repository and approved release:

git clone --branch skills-2026-10-27 https://git.example.org/platform/agent-skills.git agent-skills
git -C agent-skills checkout --detach skills-2026-10-27

Git's clone documentation permits a tag as the branch argument; checkout documents detached operation at a commit. A tag is a convenient release name, but do not assume the name can never move. Have the deployment process resolve and record the full commit identifier, then use that identifier for subsequent installations and incident reconstruction.

Publish the catalog and its supporting files from the same revision. Avoid a server returning yesterday's description with today's instructions, or an installer updating SKILL.md while retaining an old helper. Stage the complete release before switching consumers to it.

For CI, record the skill commit alongside the application commit. For interactive agents, expose the installed revision in diagnostics. Rollback then means selecting a known catalog revision rather than asking everyone to undo local edits.

Adapt discovery to each client

Claude Code documents project skills at .claude/skills/<name>/SKILL.md and personal skills at ~/.claude/skills/<name>/SKILL.md. It supports symlinked skill folders in these locations. A local installer can therefore link each approved skill directory into the chosen scope, provided the target remains readable to that session.

Cursor documents project discovery from .agents/skills/ and .cursor/skills/, as well as several compatibility directories. Pick one discovery location per installation and check for older copies elsewhere. Cursor also distinguishes local personal skills from cloud availability: a home-directory installation is insufficient evidence that a remote worker received the package.

Maintain a small compatibility record for every supported client: discovery location, invocation method, supported frontmatter and handling of bundled files. Add Codex or a new harness only after checking its actual discovery behavior. Verify the selected skill and revision in a fresh session, including sessions started inside a subdirectory. An agent finding a similarly named procedure is a deployment failure even if its answer looks plausible.

Serve a small catalog when files cannot travel

For agents without the required filesystem access, design an MCP service that lists approved skill names and descriptions, then reads one selected package entry. These are application tools you define. MCP's tools specification supplies discovery through tools/list, invocation through tools/call, and schemas describing arguments; it does not define a universal skill-installation method.

For example, your service could advertise a read_skill tool requiring a name and release. After discovery and connection setup, its invocation could be:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "read_skill",
    "arguments": {
      "name": "database-change-review",
      "release": "skills-2026-10-27"
    }
  }
}

Return the resolved revision with the instructions. Define how references are fetched and reject paths outside the approved package. Load descriptions before bodies, following the specification's progressive disclosure approach.

Claude Code's documented HTTP setup would connect to your service like this:

claude mcp add --transport http team-skills https://skills.example.org/mcp

Configure its required authentication separately. Receiving procedure text through a tool is not proof that a client registered a native slash command, downloaded scripts or granted execution permission. Test those capabilities individually.

Review changes before widening distribution

Assign owners to the skill directories and release configuration. GitHub's CODEOWNERS documentation describes automatic review requests and an option to require owner approval through branch protection. Merely adding CODEOWNERS does not make approval mandatory; enable the corresponding rule and protect the ownership file too.

Review the complete package diff. A harmless-looking wording update can point at a changed script or replace a reference with instructions to send internal data elsewhere. Require reviewers to identify newly requested tools, commands, network destinations and credentials. Keep production credentials out of examples and package assets.

Give consumers read access to approved releases and reserve publication for a separate identity. An agent using the checklist should not silently rewrite the checklist for everyone else. Skill instructions also cannot substitute for permissions enforced by the tool or target system.

When withdrawing a procedure, stop distributing it and identify installed revisions that still contain it. Deleting the repository entry cannot recall text already loaded into a running conversation. Use the review questions in reviewing untrusted skills before sharing them before promoting externally sourced packages.

Where SPYN3 fits

With Memory & skills enabled by an admin, SPYN3 stores shared skills under spyn3://workspace/skills/<name>/SKILL.md. Any MCP client can use context_list, context_read and context_search; reads need call:tools, while writes need the separate write:memory permission. The Claude Code and Codex plugin loads a skill catalog at SessionStart within its 9,500-byte startup budget. This setting is off by default. Keep repository review and release promotion as your team's process.

Prove that every consumer received the intended procedure

Before announcing a release, run the same database-review task through each supported client. Use a fixture with a missing rollback plan and an unspecified database version. Check that the agent finds the intended skill, reads its checklist, asks for the missing version and reports the rollback gap without applying anything.

1. Start from an empty installation and verify discovery without relying on a developer's personal files.
2. Record the selected name, resolved commit and supporting-file revisions.
3. Try an unrelated task and confirm the catalog does not inject the full database checklist into it.
4. Remove a referenced file and confirm the agent reports missing evidence instead of inventing its contents.
5. Restore the previous approved release and repeat the fixture.

For remote delivery, add an unavailable-service case and check that the client reports the procedure could not be loaded. Retain these results with each release. They demonstrate that the shared catalog reaches working agents, including fresh sandboxes, with an identifiable version and a usable recovery path.