Agent Skills Governance Is Broken — and a GitHub Repo Is Not the Fix

The way engineering organizations manage Agent Skills today is archaic, imprecise, and an anti-pattern. It is time to say so out loud.

The agentic AI market is accelerating fast. Gartner predicts that 40% of enterprise applications will embed AI agents by the end of 2026, up from less than 5% in 2025. Agent Skills — the packages of instructions, scripts, and reference materials that give AI agents domain-specific expertise — are rapidly becoming first-class engineering assets, fundamental to an organization’s agentic capability as its APIs or its internal libraries.

Yet despite this strategic importance, the prevailing approach to managing Agent Skills is to drop them into a GitHub repository and bolt on enough process to make it feel governed. This approach is not just suboptimal — it is an active governance anti-pattern that will compound in cost and risk as agentic systems scale.

Why Organizations Need a Skills Management System in the First Place

To understand why the current approach fails, it helps to be precise about what a skills management system actually needs to do. Engineering organizations need five things from any shared asset store — whether that asset is an API, a library, or an Agent Skill:

Curation — distinguishing high-quality, broadly useful skills from narrowly scoped or experimental ones, and maintaining that distinction over time.

Versioning — tracking changes to skills so that consumers know what they are running, and so that updates can be deployed or rolled back in a controlled way.

Discoverability — making it possible for engineers (and increasingly, agents) to find the right skill for a given task without exhaustive manual search.

Lifecycle management — handling the full arc from creation through active use to deprecation and retirement, with enforcement at each stage.

Governance and access control — ensuring that only the right people and systems can read, publish, update, or invoke a given skill, with appropriate audit trails.

A GitHub repository can address some of these needs, imperfectly, for a small catalog. It fails systematically as the catalog grows — and understanding how it fails is the first step toward the right solution.

GitHub: The Wrong Tool Wearing a Governance Costume

GitHub is a version control platform. It was designed to track changes to code, facilitate human collaboration through pull requests, and manage branching and merging. It does those things exceptionally well — for code. Agent Skills are not code in the traditional sense. They are behavioral packages that instruct AI agents how to act, and they require governance mechanisms that source control was never designed to provide.

What happens when organizations try to govern skills through GitHub? They reach for the tools available: directory structures, CODEOWNERS files, pull request reviews, README catalogs, and human working groups. Each of these is a compensating mechanism — a workaround for a gap that GitHub leaves open.

The compensating mechanisms fail in predictable ways.

Curation via directory structure does not scale. Flat repositories with tens of skills are browsable. Repositories with hundreds of skills are archives. Engineers stop discovering skills organically and start either reinventing existing ones or asking around — neither of which is discovery in any meaningful sense.

Versioning via Git history gives you a record of changes, but it does not give you a pinned, deployable version that a specific agent or team can reliably target. Anthropic’s own enterprise documentation acknowledges this directly: custom Skills do not sync across surfaces, and organizations deploying Skills across the Claude API, claude.ai, and Claude Code must implement their own synchronization process. “Maintain skill source files in Git as the single source of truth” is official guidance — but it makes the organization responsible for all the distribution and consistency work that a proper versioning service would handle.

Discoverability via README is documentation, not infrastructure. A README catalog is accurate when someone last edited it. Skills move, get renamed, go stale, lose their owners, and the catalog silently drifts. There is no mechanism to detect or correct this drift — only human attention, which cannot be allocated to a file indefinitely.

Lifecycle management via pull request process produces what might be the most precise description of the problem with GitHub-based governance: governance theater. Pull request reviews, CODEOWNERS assignments, working groups, and migration playbooks give the appearance of control. But when a skill is marked deprecated in a README and the directory still exists, nothing stops an agent from loading it. The deprecation is advisory. The governance is cosmetic. As one analysis of GitHub CODEOWNERS at scale found, without active enforcement, rules become suggestions — and a 2025 study of 803,000 pull requests found that CODEOWNERS rules and branch protection are either not enforced or routinely bypassed in a significant portion of real repositories.

Access control via repository permissions is coarse-grained and organizational in nature. It controls who can push to a repository, not who can use which skill. There is no primitive for “this skill is available to the networking team but not to the data team,” or “this skill requires elevated approval before an agent can invoke it.” Scoping by permission is blunt; skills require precision.

The result is an organization that has substituted process for policy, documentation for enforcement, and social convention for access control. That is the governance anti-pattern.

The Case for a Purpose-Built Skills API Service

A skills API service is not simply a better place to store SKILL.md files. It is a different architectural model — one in which governance is a runtime property rather than a documentation exercise. The following seven capabilities illustrate what that difference means in practice.

1. Scope as a Governed Dimension: Every Skill Knows Its Audience

In a GitHub-based model, skill scope is expressed through directory conventions and social agreement. A skill in the networking/ subdirectory is, by convention, for the networking team — but nothing prevents a developer from installing it, an agent from loading it, or a central reviewer from being asked to approve it even when they lack the domain context to evaluate it meaningfully. Scope is a label, not a control.

A skills API service makes scope a runtime primitive. When a skill is registered, it carries an explicit scope: global, domain, team, service or private. Queries from agents or engineers outside that scope return nothing — not by directory convention, but by policy enforcement at the access layer. The networking team’s operational runbook is invisible to the data team. A global cross-cutting skill is discoverable by anyone. The distinction is enforced without any human needing to remember it.

This also dissolves a false dilemma that organizations currently face. The choice between “everything in one central repo” (centralized governance, autonomous bottleneck) and “each team maintains their own repo” (team autonomy, discovery fragmentation) is a product of the GitHub model’s limitations. A scoped API provides both: teams publish autonomously within their defined scope, and a single registry surface makes the right skills visible to the right consumers.

2. Self-Service Within Guardrails: Replace the PR Queue With a Policy Engine

GitHub code review has already become the bottleneck of AI-assisted development more broadly. With AI coding agents generating code, some engineering teams are now producing 50–60 pull requests per day — and the bottleneck is no longer writing code, it is reviewing and approving it. The 2025 DORA report frames this as “localized pockets of productivity” lost to “downstream chaos,” with gains in coding speed absorbed by bottlenecks in review and deployment.

The same dynamic afflicts skills. When every new skill — including narrow, team-specific ones that central reviewers have no expertise to evaluate — must pass through a central PR queue, the review process adds friction without adding value. Reviewers lacking domain context approve what they cannot meaningfully assess. Teams with urgent operational needs wait on an unrelated merge queue.

A skills API service replaces the PR gate with a policy engine. Publishing a skill is gated by automated checks: schema validation, a linting pass, a named owner on record, a scope declaration that matches the publishing team’s entitlement. If those checks pass, the skill is published — no human bottleneck required for well-scoped, properly formed contributions.

Skills that require human oversight because they touch sensitive systems or cross scope boundaries are routed for explicit approval. But that approval is targeted and domain-appropriate, not a generalized central review queue that cannot distinguish between a platform-wide infrastructure skill and a single team’s operational runbook.

Critically, the review process itself can be augmented by code review agents with specific expertise in Agent Skills — validating that SKILL.md metadata is complete, that descriptions are semantically precise enough for accurate agent triggering, and that bundled scripts do not introduce unsafe patterns. AI-assisted skills review closes the quality gap without restoring the human bottleneck.

3. A Living Registry, Not a Decaying Document: The Catalog That Governs Itself

The core distribution problem with GitHub-based skills is not philosophical — it is mechanical. When an engineer clones a project, the agent they work with has no way of knowing which skills the project depends on. There is no package.json equivalent for Agent Skills. The file that teaches the agent how to perform a workflow lives on someone else's machine, in their .claude/skills/ directory, and the mechanism for sharing it is ad hoc: export, zip, send over Slack, manually import. If the skill is updated the next week, the other engineer does not get the update.

The team-level workarounds for this — private GitHub repos used as plugin sources, manual plugin marketplace commands, custom synchronization scripts — are engineering effort spent compensating for the absence of a registry, not delivering value.

A skills API service is the registry. Every skill is registered, versioned, and queryable through the same interface. There is no separate catalog to maintain because the registry is the catalog. Updates propagate to consumers because the service serves the current version, not because engineers remembered to push and everyone remembered to pull. The “single source of truth” that Anthropic’s own enterprise guidance recommends maintaining in Git becomes an actual service property rather than an aspiration enforced by human discipline.

4. Controlled Access for Sensitive Recipes: Not Every Skill Can Be Open-Sourced Inside Your Own Organization

Agent Skills are not just technical workflows. As organizations mature their use of agentic systems, skills will increasingly encode deeply sensitive organizational knowledge — knowledge that cannot be shared freely even within the organization, let alone in a public or semi-public repository.

Consider what this category includes in practice: a skill that guides an agent through a company’s product roadmap and pipeline, used only by the product leadership team. A skill encoding specific human resources policies and compensation structures, accessible only to People Operations. A skill that encodes M&A due diligence workflows, visible only to a small deal team. A skill that embeds proprietary financial modelling approaches that constitute competitive trade secrets. These are skills that need to exist for agents to function effectively in sensitive contexts — and they are skills that, under the GitHub model, must either be stored in a repo (creating exposure risk) or excluded from the shared catalog entirely (creating isolation and reinvention).

This risk is not hypothetical. Research on AI agent vulnerabilities has documented how agents can autonomously access emails, knowledge bases, and internal databases, with system-level permissions that may quietly shift the protective boundary around a company’s sensitive information. Skills that embed proprietary workflows or strategic context represent a specific materialization of this risk.

A skills API service addresses this through attribute-based access control on skill records. A skill can be registered as visible only to a specific team or role scope. Access is enforced at query time — an agent or engineer without the appropriate entitlement does not receive the skill, does not know the skill exists, and cannot install it. The sensitive recipe stays in the registry where it can be versioned, maintained, and governed — rather than existing informally outside any management system because the shared repo cannot contain it safely.

And when a skill containing sensitive information is found to have been miscategorized or exposed incorrectly, a skills API service can revoke access immediately. Under the GitHub model, once a skill is in a repo and has been read or forked, there is no mechanism to un-expose it.

5. Discovery That Works at Machine Speed: Find Skills Like You Search the Web, Not Like You Browse a Filing Cabinet

Skills work when they describe processes clearly enough for an agent to recognize when to invoke them. The SKILL.md metadata specification — name, description, compatibility, version, author — is already designed for semantic retrieval. The limitation is that in a GitHub-based model, this rich metadata sits inert in a file, retrievable only by a human who knows to look in the right directory.

At the scale agentic systems are reaching — Gartner’s 1,445% surge in multi-agent system inquiries from Q1 2024 to Q2 2025 reflects the pace — engineering teams will manage skill catalogs of hundreds or thousands of entries. Browsing is not discovery at that scale. Browsing is archaeology.

A skills API service indexes the metadata and exposes semantic search over it. An engineer or agent looking for “incident response workflows for multi-VPC DNS failures” finds the relevant skill directly, ranked by relevance, scoped to their entitlement, with compatibility signals surfaced alongside the result. This is discoverability as infrastructure, not documentation.

6. Deprecation That Has Teeth: If a Skill Is Retired, It Should Be Unreachable

The GitHub deprecation model is a comment in a file. A deprecated skill continues to exist as a directory, continues to be installable, continues to be loadable by an agent. The CoSAI Workstream on Secure Design Patterns for Agentic Systems specifically identifies “zombie servers that remain active after deprecation” as a documented security risk — tools and capabilities that remain operational indefinitely without lifecycle management, creating ongoing exposure.

For Agent Skills, the risk of inadequate deprecation takes several distinct forms. A skill encoding a workflow that relied on a deprecated internal API continues to instruct agents to invoke that API — the skill is wrong, but nothing prevents it from being loaded. A skill discovered to cause unintended behavior when combined with certain agent tool configurations continues to be available — there is no hard revocation, only an advisory note. Most critically: a skill containing sensitive organisational knowledge that has been inadvertently released into a broader scope cannot be reliably recalled. Once a file has been read and cached, the information is out. There is no revocation mechanism in a file system.

A skills API service makes deprecation a policy state enforced at the access layer. When a skill is deprecated, the service stops serving it. Not by convention, not by advisory, but by control: the skill is unreachable. Agents cannot load it. Engineers cannot install it. And the enforcement is immediate — not contingent on a team getting around to deleting a directory or a working group processing a migration ticket.

7. From Human Wiring to Agent Autonomy: Skills Must Evolve From Design-Time Choices to Runtime Decisions

Every model of skills management discussed so far — GitHub repos, org-level repos, manual catalogs, API uploads — shares a common assumption: a human decides which skills to install, configures the agent accordingly, and the agent operates within those pre-set boundaries. The agent is a passive consumer of decisions made upstream by a human at design time.

This assumption is already being overtaken by the direction of the industry. Analysts project the multi-agent AI market to grow at a 48.5% compound annual rate through 2030. Gartner anticipates that 15% of day-to-day work decisions will be made autonomously through agentic AI by 2028. The architecture of these systems is moving from individual assistants toward orchestrated fleets of specialized agents — one for security, one for testing, one for domain-specific refactoring — that coordinate workflows autonomously.

In a multi-agent world at scale, requiring a human to wire each skill to each agent is a fundamental bottleneck. The human-in-the-middle who decides which skills get installed is doing work that agents, properly equipped, could do themselves.

A skills API service, surfaced as an MCP server, transforms the registry into a queryable capability layer accessible at runtime. An agent can ask: “What skills are available to me for incident response in the networking domain, scoped to my team’s entitlements?” The registry returns the relevant options. The agent selects and loads what it needs for the current task. The decision moves from design time — a human configuring a skill list — to runtime, governed by the registry’s policy engine.

This is not an incremental improvement to the GitHub model. It is a different model of how agents relate to their own capabilities. As agentic systems evolve from tools that assist human developers to autonomous participants in engineering workflows, the infrastructure that governs their knowledge must evolve accordingly. A static file in a repository cannot participate in a runtime conversation. A skills API service can.

The Deferred Problems Are the Product Requirements

Every organization managing a growing skills catalog through GitHub eventually reaches the same set of problems that resist solution within the GitHub model: how to discover skills across multiple repositories, how to detect and handle skills whose owners have left, how to enforce deprecation in a way agents respect, how to give teams autonomy without fragmenting discoverability, and how to eventually enable agents to discover their own applicable skills at runtime.

These are not edge cases. They are the natural consequences of scale, and they are consistently deferred because the GitHub model offers no clean answer to any of them. The deferred problem list is, in effect, a product requirements document for a skills management API.

Organizations that solve this with more process — bigger working groups, more detailed migration playbooks, stricter CODEOWNERS hierarchies — are investing engineering effort in governance theater. The working group will not scale to two hundred skills. The manually-maintained README will not stay current. The advisory deprecation notice will not stop an agent from loading a retired skill.

Skills are not configuration files. They execute code in agent environments with bash access and filesystem permissions. They encode organizational knowledge that may be sensitive, strategic, and competitive. They are increasingly the mechanism through which agents understand how to do their work. They deserve infrastructure built for exactly that purpose — not a version control system wearing a governance costume.

What a Skills API Service Looks Like in Practice

A purpose-built skills management API would expose, at minimum:

• A registration endpoint that accepts a skill package, validates it against the agentskills.io open specification, assigns a scope and access policy, and makes it immediately queryable
• A versioned retrieval endpoint that serves a specific skill version to an authorized consumer — agent or human — enforcing scope and deprecation state at query time
• A semantic search endpoint indexed on skill metadata, filterable by scope, domain, compatibility, and status
• A lifecycle management interface for managing skill status (active, deprecated, revoked), with hard enforcement at the retrieval layer
• An MCP server surface that exposes skill discovery to agents at runtime, enabling autonomous capability lookup within policy bounds
• An audit log of who registered, updated, deprecated, or accessed each skill — the audit trail that compliance and security teams will increasingly require

The agentskills.io open specification already defines the skill format and metadata schema. Anthropic’s Skills API provides workspace-scoped distribution for the Claude platform. The gap this post describes — scoped, policy-enforced, autonomously discoverable, lifecycle-managed skills governance — remains largely unaddressed by the existing ecosystem.

That gap is the next infrastructure problem in agentic AI. The organizations that solve it first will be the ones that scale agentic systems without the governance debt that the GitHub model accumulates.

References:

1. Anthropic Agent Skills documentation (platform.claude.com);
2. agentskills.io open specification;
3. JFrog “Agent Skills Are the New Packages of AI” (March 2026);
4. GitHub Well-Architected “Governing Agents in GitHub Enterprise”;
5. CoSAI Workstream 4 “Secure Design Patterns for Agentic Systems” (January 2026);
6. Gartner Emerging Tech Impact Radar 2025; DORA Report 2025;
7. Gravitee “State of AI Agent Security 2026”;
8. KPMG Q4 AI Pulse Survey (March 2026);
9. MachineLearningMastery “7 Agentic AI Trends to Watch in 2026”;
10. CodePulse Code Review Study 2025.