How to maintain one skill across multiple repositories

Suppose you write a skill for reviewing API changes. It asks your coding assistant to check permissions, preserve compatibility and test rejected requests. It works well enough that you copy it from your billing repository into your accounts service and your public API.

Then a reviewer finds a missing check. The assistant checked whether a user was logged in, but missed whether that user owned the record. You improve the skill in billing. The other two copies still contain the old instructions.

You could copy the fix again. But someone has already changed the public API version to handle an older client. Replacing that file would erase their change. Leaving it alone would leave the missing check.

This is where sharing a skill becomes maintaining one. You need to know which instructions are shared, which differences are deliberate, and how an improvement reaches the people using them.

Decide when an update should reach a repository

A shared location answers where the skill lives. It does not answer when someone should start using a change.

For a writing skill, you might want everyone to get clearer instructions on their next task. For a release skill, you might want each repository to review a new procedure before using it. Neither policy is right for every skill.

There are several ways to make that choice.

One person’s skills across projects

If you are the only user, a personal skills directory may be enough. Claude Code, for example, supports personal skills across projects on one machine. It also supports skill directories linked to another location on disk. These are documented features, so copying a skill into every repository is unnecessary for that case. See Claude Code’s skill locations.

A link can point several projects at one local copy. It cannot keep a teammate’s machine up to date. Once another person needs the skill, decide how they get that copy and its updates.

A shared Git repository with reviewed updates

Keep skills in a separate repository when you want their history and review process in Git. Each consuming project can include a chosen revision through a submodule. Git records a specific commit for that submodule; it does not silently follow every change to the shared repository. See Git’s submodule documentation.

That gives a repository owner a clear decision: keep the current instructions or adopt a newer revision. It also adds an update task to each consuming project. Your setup must put the skill where the coding tool can discover it, and new checkouts must fetch the submodule’s contents.

Choose this approach when being able to identify and restore the exact instructions matters more than getting every improvement immediately. Pinning the instructions does not make model output identical, but it removes one source of change.

Fetch shared instructions when they are needed

Another approach is to let the coding tool request the skill from a shared service. MCP provides a connection through which a tool can retrieve those instructions. With a service that returns the current version, an update can reach the next request without changing each repository.

This trades local update work for dependence on the service. Decide what happens if a request fails. If you keep a fallback copy, record where it came from and when it was last updated. Otherwise, you have recreated the forgotten-copy problem under another name.

My recommendation is to choose the update policy before the distribution tool. Use reviewed revisions for procedures that need controlled adoption. Fetch current instructions when the team wants a common, current version. A team can use both for different skills.

Separate the rule from the repository detail

Even perfect distribution cannot make a billing-specific instruction useful everywhere.

Consider this instruction:

Run the billing API tests, then check that users cannot read another customer’s invoices.

It contains a reusable check and local details. Split those ideas:

For each changed endpoint that accesses a user-owned record, check both ownership and authentication. Find the repository’s documented test command and test the rejected request through the endpoint.

The shared skill now describes what to check. The repository supplies its test command and domain examples.

This does not mean making every instruction vague. “Follow best practices” gives an assistant little to do. “Check whether an authenticated user can access another user’s record” names a specific failure while remaining useful across services.

A useful editing test is to ask whether a sentence would still make sense in the second repository. If it names a local script, directory or deployment target, put that detail beside the project that owns it. Tell the shared skill where to look for it, and what to do if it is missing.

Also check what you are sharing. The Agent Skills specification defines a skill as a directory, which may include scripts, references and assets beside SKILL.md. A document that refers to scripts/check-api.py is incomplete without that script. Moving the Markdown alone does not move its dependencies.

Treat an override as a separate version to maintain

Sometimes the public API really does need different instructions. Perhaps its old clients depend on a response field that internal services no longer use.

Keep that exception narrow. Record why it exists, who owns it, and what would let you remove it. When possible, keep the shared procedure and supply the local constraint separately.

If your tool replaces the entire skill when it finds a repository override, the override becomes another version to maintain. A fix to the shared skill will not necessarily reach it.

For the ownership check in our example, the maintainer should review both versions. The public API’s compatibility rule does not explain why it should miss an ownership check. Those are independent concerns.

This is also a reason to avoid overriding a whole skill just to change a test command. A small local difference should not force you to maintain a second copy of every shared rule.

Test an improvement before sharing it

A clearer-looking instruction can still produce a worse review. Keep a few real tasks from repositories that use the skill, together with the result you expect.

The Agent Skills evaluation guide recommends comparing runs with a skill against a baseline, which can be the previous version. Use fresh sessions so earlier discussion does not supply instructions the skill itself lacks. Judge observable results, rather than whether the answer sounds thorough.

For the API review skill, select actual past changes that cover these cases:

Past change to select	What to look for in the review
A known ownership bug	Identifies the access failure and points to the relevant code
A fix that already enforces ownership	Recognizes the protection instead of repeating the old finding
A change involving the legacy response field	Respects the public API’s documented compatibility constraint
A change outside API behavior	Avoids inventing API findings to satisfy the checklist

Run the old and revised skill against the same changes. Keep the inputs, instructions and outputs together. If a result surprises you, repeat the comparison before deciding the edit helped.

The second case matters as much as the first. An instruction that makes an assistant accuse every endpoint of missing access checks has increased noise, even if it catches the original bug.

Give one person or team responsibility for accepting shared changes. Teammates should be able to contribute improvements, but someone needs to decide whether the evidence supports making them the default.

Where SourceAnt fits

SourceAnt supports the shared-service approach. A workspace skill is available across its repositories. Connected coding tools can search for a skill, read it, or request it through an MCP prompt. Updating the workspace skill changes what a subsequent request retrieves, unless that repository has an override. The skills guide covers setup and use.

That removes the need to keep a separate instruction file current in every checkout. It does not remove the need to test changes or maintain exceptions. SourceAnt’s repository overrides replace the workspace version; they do not merge later edits into it. Instructions already read into a conversation also need to be requested again after an update.

SourceAnt over MCP

Use a shared skill from your coding tool

1. Find the skillType the prefix. Every workspace skill is listed with what it is for.

   > /sourceant:skill

   • /sourceant:skill:test-cultureDescribe the test framework, layout, and visible limits without assuming coverage or quality.
   • /sourceant:skill:contract-consistencyCheck whether changed inputs, outputs, errors, or access rules break existing consumers.
   • /sourceant:skill:duplicate-implementationCheck whether newly added code duplicates existing behavior and introduces a concrete problem.
2. Give it a taskAdd what to work on. Name a repository to use its own version of the skill, if it has one.

   > /sourceant:skill:contract-consistency

   task

   Review the change to the invoice endpoint

   repository

   billing

3. Work from the current versionSourceAnt sends the latest instructions into the conversation with your task attached.

   Sent to the assistant

   Apply the Contract consistency review skill to the requested task.

   Trace each changed contract from the code that produces a value to the code that uses it.

   1. Read both sides. Compare accepted inputs, returned fields, error handling, and access checks.

   Repository: billing

   Requested task:
   Review the change to the invoice endpoint

Start with one skill you already use in two repositories. Compare the copies. Move the genuinely shared instructions into one maintained version, and write down why any remaining differences exist. Before distributing the next edit, try it on a real task from each repository. That gives you a useful answer to the question that copying alone cannot settle: did both projects benefit from the change?