Agent skills marketplace options for teams: author, version, review and roll back

An agent skills marketplace is the catalog a team’s coding agents install skills from, and choosing one is the last of five decisions a team makes about Agent Skills. The first four are how to write a description that makes the agent load the skill, how to keep SKILL.md small, how to version it so a one-line edit does not silently change every engineer’s agent, and how to review the scripts it bundles. This guide covers all five for Claude Code, Codex CLI and Cursor, from the open Agent Skills specification and vendor documentation as published in October 2026, and walks through agent-skills-for-teams, an MIT-licensed skill that teaches an agent this process, with real output from its linter.

TL;DR

• Only a skill’s name and description load at session start, so the description decides whether the agent reads the rest. Write it as trigger conditions and test it.
• Keep SKILL.md under 500 lines and about 5,000 tokens; move detail into references/ with an explicit “read this when” line.
• Version skills like an API whose consumer is the agent: SemVer in metadata.version, a changelog, tagged releases and a rehearsed rollback.
• Distribution runs from in-repo folders, to a shared git repo installed with npx skills add, to plugin marketplaces, to a central registry such as the Bifrost Skills Repository.
• Skills run with the agent’s full permissions. Review every bundled script before install and on every upgrade.

How Agent Skills load

A skill is a folder with a SKILL.md file (YAML frontmatter plus Markdown instructions) and optional scripts/, references/ and assets/ folders. Agents load it in three tiers, and that mechanism explains almost every rule for writing and shipping skills.

The progressive disclosure section of the spec sets the budgets:

The spec’s frontmatter rules are strict: name is 1 to 64 lowercase letters, digits and single hyphens and must match the folder name; description is required and capped at 1,024 characters; metadata is a string-to-string map, which is where a version belongs.

Each harness adds its own listing budget. Claude Code caps each skill’s listing text at 1,536 characters and, when many skills are installed, drops descriptions to fit 1% of the context window, starting with the least-used skills. Codex’s initial list uses at most 2% of the context window and shortens descriptions first. For teams, that means every installed skill taxes every session, and installing every skill for everyone pushes the useful descriptions out.

How to create Claude skills that trigger

To create a Claude skill, make a folder under .claude/skills/<name>/ in a repository or ~/.claude/skills/<name>/ for personal use, add SKILL.md with a name and a description, and write the instructions below the frontmatter. The work is in the description: it is the only text the agent sees before deciding to load the skill.

Claude Code’s skill locations table adds enterprise skills in the managed settings directory and plugin skills namespaced as /plugin-name:skill-name; on a name clash, enterprise beats personal and personal beats project.

The agent-skills-for-teams skill gives a description formula that matches the spec: what the skill does in concrete verbs and nouns, “Use when” situations (including ones where the user never names the domain), phrases users actually type, and an optional “Not for” boundary when a sibling skill overlaps. Its example:

# Weak: says nothing about when
description: Helps with database migrations.

# Strong
description: Write, review and safely apply Postgres schema migrations with this repo's
  migrate tool, including backfills, lock-safe index creation and rollback scripts. Use
  when the user adds or changes a column, table, index or constraint, asks why a deploy
  is blocked on a migration, or mentions "migration", "ALTER TABLE", "backfill" or
  "schema change", even if they only describe the data change they want.

Descriptions should be tested, not guessed. The Agent Skills guide to optimizing descriptions recommends about 20 realistic queries, half should-trigger and half near-misses that share keywords but need something else. Run each several times, treat 0.5 as the trigger-rate threshold, split the set roughly 60/40 into train and validation, and tune only on train. Claude Code’s troubleshooting section adds that malformed YAML leaves the description empty; --debug shows the parse error.

Keeping SKILL.md small

A small SKILL.md holds only what the agent would get wrong without it: project conventions, the default tool, exact commands for fragile steps and a list of gotchas. Everything else moves to references/ or scripts/ and loads only when the body says to read or run it. The spec’s ceiling is 500 lines; the team skill targets 150 to 400.

The spec’s file reference rules ask for relative paths and references one level deep, and Claude Code’s supporting files guidance asks that each file be referenced from SKILL.md with what it contains and when to load it. That load condition is what most skills miss. “Read references/api-errors.md if the API returns a non-200 status” works; “see references/” does not, because agents then open every file or none. The team skill assigns content by frequency:

For a skill that has already grown, its bloat triage is mechanical: estimate tokens (characters divided by four), mark each section every-run, some-runs or already-known, delete what the model knows, move some-runs content into references, script deterministic procedures, re-run the evals and ship a minor version.

Versioning skills with SemVer and changelogs

Versioning a skill means putting metadata.version: "MAJOR.MINOR.PATCH" in its frontmatter, keeping a CHANGELOG.md beside it, and releasing from tags so consumers pin to a known revision. Without it, an edit to one line changes what every agent on the team does at its next session, with no record of when or why.

Semantic Versioning needs one adjustment for skills: the consumer is the agent, so behavior change, not text change, decides the bump. The versioning-and-review reference in the team skill spells it out:

Two rules are easy to miss: a description change alters triggering, so it is at least minor; and versions only move forward, so rollback means serving or pinning an older release.

The release flow is a pull request that bumps metadata.version and adds a changelog entry written for the upgrade’s reviewer (what the agent will do differently), CI lint and trigger evals, CODEOWNERS approval, then a merge and a per-skill tag such as db-migrations/v2.3.1. The reference ships a GitHub Actions workflow that lints every pull request touching skill folders and fails when a changed skill’s diff adds no version: line.

Security review for skill scripts

A skill is code-adjacent: its instructions steer an agent that can run shell commands, and its scripts execute on the developer’s machine with the developer’s access. Review it like code, with CODEOWNERS on the skills directory and a separate owner for scripts/.

Anthropic’s engineering post on Agent Skills warns that “malicious skills may introduce vulnerabilities in the environment where they’re used or direct Claude to exfiltrate data,” and recommends installing them only from trusted sources. In The Frontier Wire’s test install, the skills CLI printed “Review skills before use; they run with full agent permissions.”

The team skill’s checklist fits in a pull request template:

• Scripts contain no curl | sh, no sudo, no rm -rf on broad paths, no eval of input, no reads of ~/.ssh, ~/.aws, .netrc or .npmrc, and no git push --force.
• Every network call a script makes is documented in SKILL.md and goes to an expected host.
• No secrets, tokens, internal hostnames or customer data in any file.
• Remote resources are pinned to exact versions, commit SHAs or checksums, never “latest”.
• Instructions never tell the agent to skip confirmations or widen its permissions, and contain nothing that would override the user’s instructions; prompt injection through third-party skills is a real path.
• allowed-tools, if set, is minimal; the spec marks it experimental.
• Third-party skills are read in full, every file, pinned, and re-reviewed on upgrade.

Plugins need the same scrutiny. Claude Code’s plugin review steps point reviewers at hooks/hooks.json, .mcp.json and bin/, since the install pane does not show what a hook runs. The guide to Claude Code security covers the managed settings that limit what a skill-loaded agent can do, and the piece on AI agent security covers the wider threat model.

Agent skills marketplace options for teams

A team has five practical ways to distribute skills, each with its own versioning and rollback story. The choice depends on whether a skill belongs to one codebase, who edits it, and how many harnesses the team runs.

Public directories sit beside these. skills.sh calls itself “The Agent Skills Directory” and lists skills that install with npx skills add <owner/repo>; Anthropic’s official and community marketplaces play the same role for Claude Code. Teams find skills there but should serve them from a source they control.

Claude Code plugin marketplaces

A Claude Code plugin marketplace is a repository or directory with a .claude-plugin/marketplace.json listing plugins, which can carry skills. Teammates run claude plugin marketplace add your-org/your-marketplace, then claude plugin install <plugin>@<marketplace>.

Versioning has a trap: users get a new copy only when the plugin’s computed version changes, so commits pushed without a version bump ship nothing. To hold users on a version, point the entry at a ref or sha. Background auto-update is off by default. Administrators can require a marketplace with extraKnownMarketplaces and enabledPlugins in managed settings and restrict sources with strictKnownMarketplaces. Private marketplaces use each machine’s existing git credentials.

Codex packages reusable skills as plugins too, and Cursor imports skills from a repository only through a plugin and marketplace. The comparison of Codex and Claude Code covers the wider differences between the two agents.

Shared git repo with npx skills

The skills CLI from Vercel Labs installs from any git source into the right folder for each harness, which its agent table shows differ:

The default install method symlinks every agent directory to one canonical copy. Private repositories work with existing git, GitHub CLI or SSH credentials. The sibling guide to npx skills and skills.sh covers the CLI in depth.

Pinning with skills-lock.json

skills-lock.json is the file the skills CLI writes into a project to record what it installed. In The Frontier Wire’s test install with CLI 1.7.4, each entry held the source (build-with-ai-hq/agent-skills-for-teams), sourceType (github), skillPath (SKILL.md) and a computedHash of the skill’s content. Commit it, because it is what makes an install checkable.

The CLI reference documents npx skills experimental_install, which restores the skills recorded in the lock file into .agents/skills/. With --frozen-lockfile, the default when a CI or GITHUB_ACTIONS variable is set, every restored skill must match its recorded hash; a source whose content differs is skipped, the lock is left untouched, and the command exits with code 1. experimental_sync, which installs skills declared in package.json, also tracks them in the lock, and the reference advises pinning a Git ref “when you need reproducible remote content.”

Two limits matter. Both commands are experimental and may change in any release. And the lock records a content hash, not a commit: it detects that upstream changed but cannot fetch the old content back. To hold a version, install from a tag’s tree URL (npx skills add https://github.com/your-org/team-skills/tree/<tag>/skills/db-migrations) or vendor the skill into the team’s repository.

Rolling back a skill

Rollback is the operation teams rehearse least and need most. The team skill gives one procedure per distribution model and one rule for all: verify in a fresh agent session, because running sessions keep the skill they already loaded.

Knowing who runs what is the other half: collect npx skills list output, and give each skill a line the agent can echo (“This is db-migrations 2.3.1”) so bug reports name the revision.

Central registry with Bifrost Skills Repository

A central registry fits when skills are owned by a platform team, edited by people who do not work in git, published as immutable versions and rolled back for everyone in one action. Bifrost, Maxim AI’s open-source (Apache 2.0) AI gateway, includes a Skills Repository in its open-source build that does this and serves skills to Claude Code and Codex as a plugin marketplace.

Every save creates an immutable SemVer version, and versions never go backwards: once 3.0.0 exists, 2.5.0 is rejected. Save stages a version without changing what users receive; Save & Serve publishes it. Shifting the served version is the rollback, and it deletes nothing.

Registering it as a marketplace needs git on the server and an External Client URL every client can reach. Then:

claude plugin marketplace add <your-bifrost-url>/api/skills/serve/claude-code/.claude-plugin/marketplace.json
codex plugin marketplace add <your-bifrost-url>/api/skills/serve/codex

Each skill is published as plugin bifrost-<skill-name>, and bifrost-all-skills bundles every served skill under a version that moves automatically (minor when a skill is added, major when one is deleted, patch when a served version shifts). A Skills API lets CI publish from git, so review stays in pull requests.

Two cautions from the docs: marketplace and download URLs are public by design while management is authenticated, so no skill should hold secrets; and files added From URL are fetched at serve time, so version immutability does not freeze them. Enterprise tier. Role-based access control and SSO decide who can create and publish skills.

The agent-skills-for-teams skill

agent-skills-for-teams is an MIT-licensed Agent Skill from the build-with-ai-hq GitHub organization that teaches a coding agent to author, version, review, distribute and roll back skills across a team. It is published on GitHub and listed on skills.sh. Everything described in this guide that is attributed to “the team skill” comes from its files.

Its description triggers when someone says a skill never triggers or loads at the wrong time, asks where skills go (.claude/skills versus .agents/skills), has SKILL.md files drifting across repos, wants SemVer and changelogs, needs to roll a skill out or back, wants a security review of a skill’s scripts, or asks to “set up a skills registry.” The body holds a quick diagnosis (five find and shasum commands for inventory, drift, size, bundled code and shadowing personal installs) and seven practices ordered by impact. Three references load on demand:

• writing-skills-that-trigger.md: when a task deserves a skill, the description template, body structure, a 20-query trigger eval with a bash runner built on claude -p --output-format json, output evals and bloat triage.
• versioning-and-review.md: the SemVer table, a changelog template, the release flow, the CI workflow, the security checklist and rollback per model.
• bifrost-skills-repository.md: marketplace prerequisites, the publish and shift runbook, a Python CI sync script against the Skills API, and troubleshooting.

What lint_skills.py catches

scripts/lint_skills.py is a standard-library Python linter (it uses PyYAML if present) that scans any directory for SKILL.md files. Errors, which exit with code 1, cover spec violations (name format, name and folder mismatch, missing or over-long description, broken relative links) and copy-paste drift: the same skill name with different content in two places. Warnings cover short descriptions, descriptions with no “use when” language, missing metadata.version, bodies over 500 lines or about 5,000 tokens, and scripts matching risky patterns such as piping a download into a shell, sudo or reads of credential files.

In a test install on October 28, 2026, The Frontier Wire installed all six build-with-ai-hq skills with skills CLI 1.7.4 into an empty git repository for Claude Code, Codex and Cursor, then ran the linter over them:

6 skill(s) scanned: 0 error(s), 0 warning(s)

No spec errors, drift, oversized bodies or risky scripts were reported, and all six carried a version. Because the token check measures the body rather than the line count, it also catches dense skills that a 500-line rule alone would pass. That is the extent of the testing: the skills were installed and inspected, not run against a team’s repositories.

Install and use

npx skills add build-with-ai-hq/agent-skills-for-teams --list      # preview
npx skills add build-with-ai-hq/agent-skills-for-teams -a claude-code -a codex -a cursor -y
npx skills add build-with-ai-hq/agent-skills-for-teams -g -y       # user-wide
npx skills list                                                    # what is installed
npx skills update agent-skills-for-teams                           # upgrade deliberately

Then ask the agent in plain language, for example:

• “Our deploy-review skill never triggers. Rewrite its description and build a trigger eval.”
• “Audit this repo’s skills for drift, bloat and unreviewed scripts.”
• “Set up SemVer, changelogs and a CI lint for our skills repo.”
• “We need one place to roll skills out to the whole team and roll them back. Set up a skills registry.”

Sibling skills from the same organization cover adjacent jobs: ai-coding-agent-governance for rolling the agents themselves out, discussed in the guide to Claude Code for teams, and secure-llm-apps for application security. The Frontier Wire’s roundup of Claude Code skills and its guides to Codex skills and Cursor skills cover the harness-specific side.

Limits of this guide

This guide rests on documentation and files read in October 2026 and a single test install. It did not measure trigger rates, compare agent output with and without a skill, or run a marketplace or registry under load. Listing budgets and the skills CLI’s experimental commands are recent and may change. The build-with-ai-hq organization was created in October 2026, so its skills have no track record; review them as the checklist above asks for any third-party skill.

Skills change agent behavior without a deploy, so they need the release discipline teams already apply to code: a tested description, a small body, a version on every change, a reviewer for every script and a rehearsed rollback. The marketplace, whether a git repository, a plugin catalog or a registry, is only the delivery layer. For a team starting from copy-pasted SKILL.md files, npx skills add build-with-ai-hq/agent-skills-for-teams and one linter run show how much drift is already there.