# Maintaining a team skill library

Read this at step 8 for the registry and versioning, at step 9, or for a library clean-up. Client facts were checked on 2026-11-06; re-check them at run time.

## The registry

One row per skill in [../assets/skill-registry-template.csv](../assets/skill-registry-template.csv), kept in the repository next to the skills and changed through review like code.

- `name`, `purpose`: the skill and its job in a few words.
- `owner_role`, `reviewer_role`: who approves the procedure and who reviews changes (never the same person for one change).
- `version`, `status`: semantic version and draft, approved, deprecated or retired.
- `clients`: the clients it is tested on.
- `canonical_location`: where the canonical folder lives and how each client reaches it (for example a symlink).
- `invocation`: automatic, automatic plus a command, or manual-only with its command.
- `write_risk`: none, draft or live (live never ships in version 1).
- `context_files`: the `martech-context/` files and versioned IDs it cites.
- `mcp_servers_and_mode`: each server and the read-only layer that holds, or "exports only".
- `scripts`: bundled scripts, or none.
- `last_eval_date`, `last_eval_result`: the latest eval record and its gate result.
- `last_reviewed`, `review_by`: dates; `review_by` is 90 days out, 30 for skills that prepare spend, send or publish drafts.
- `source_and_commit`: for adopted third-party skills, the source URL, pinned commit and sha256.

Versioning:

- Patch (1.0.1): wording that changes no behaviour, a typo, a refreshed checked date.
- Minor (1.1.0): new behaviour with the same inputs and outputs, such as a new exception rule.
- Major (2.0.0): changed inputs, outputs or command. Tell every user; old run records may not compare.
- Every version gets a changelog line and, for minor and major, a `decisions.md` entry naming the approver.

## Review cadence and triggers

Review on the `review_by` date, and early when any of these happen:

- A client upgrade, or a changelog entry touching skills, commands, permissions or listing budgets.
- A model change for the team.
- A connected tool gains or loses tools, or its read-only layer changes.
- A `martech-context/` definition the skill cites changes version.
- An incident or a correction a reviewer had to make.
- Trigger accuracy drops (people report it not loading, or loading for the wrong job).
- A new skill arrives whose description overlaps.

A review reruns the trigger set and output cases, re-checks every dated fact against the live page, and updates `last_reviewed`, `review_by` and the registry.

Failure mode: stale vendor facts. The skill presents retired settings or old limits as current. Detect: the live-docs check at each review; vet rule V22 flags common retired products. Prevent: a checked date next to every volatile fact and its URL in `sources.yaml`.

## Regression first

Every production failure becomes a test case before the fix.

Example: in week 6, the pacing review called Meta 31% under budget on a Monday because the export included that morning's partial day. Before touching SKILL.md, the owner adds a boundary output case with a partial final day and confirms the current version fails it. Then the fix (use only days with `data_complete` true) goes in, the case passes 3 of 3, the rest of the suite still passes, and the version moves from 1.0.0 to 1.1.0.

## Listing budget hygiene

Clients load every installed skill's name and description up front within a budget, and drop or shorten descriptions when it overflows. An installed but unused skill costs triggering accuracy for the rest.

- Claude Code (checked 2026-11-06): the listing gets 1% of the context window and caps each entry at 1,536 characters; over budget, descriptions of the least-invoked skills go first. Check monthly with `/doctor` and `/skill-doctor`. Propose `name-only`, or `off`, in `skillOverrides` for rarely used skills, as a settings diff the owner applies. The budget can be raised with `skillListingBudgetFraction`, but trimming is usually better.
- Codex (checked 2026-11-06): the initial list gets at most 2% of the context window (8,000 characters when unknown); descriptions are shortened first and skills can be omitted with a warning. `skills.max_context_tokens` sets a different budget, up to 10,000 tokens. Propose a `[[skills.config]]` entry with `enabled = false` for unused skills.
- Cursor: check Customize > Skills for what is installed; list stray copies picked up from compatibility folders and propose their removal to the owner.
- Keep the job and the request wording in the first sentence of every description, so a shortened one still triggers and a dropped one is the least-used skill, not the one that matters.

## Deprecation, ownership and retirement

- Deprecate before removing: the description starts with "Deprecated: use" and the replacement's name, the registry status becomes deprecated, and the skill is removed after one review cycle.
- Ownership change: when an owner leaves or changes role, reassign within 30 days or deprecate. An unowned skill is not reviewed and slowly goes wrong.
- Retire or merge:
  - unused for 90 days, unless seasonal (a Black Friday readiness check);
  - the baseline now matches it (rerun the output cases without the skill);
  - two skills that load for the same requests.

Failure mode: the skill adds tokens but no value. With-skill and baseline outputs score the same, because the model already knows the job. Detect: a quality delta under 20 points and no blocker difference. Prevent: narrow the skill to the knowledge gap (the team's thresholds, exceptions and hand-offs) or retire it.

## Quarterly library review

A one-hour agenda for the owner group:

1. Inventory: every skill each client lists, against the registry. Anything listed and not registered is removed or registered.
2. Usage: invocation counts where the client shows them; candidates for name-only, off or retirement.
3. Overlaps: pairs of skills whose descriptions compete; rerun both trigger sets.
4. Failing evals: any skill whose last gate failed or is older than its review date.
5. Stale `review_by` dates and unowned skills.
6. Open vetting findings and third-party skills whose source has moved past the pinned commit.
7. Next candidates from the scorecard: the top two by priority.