Claude Skills: What They Are and How to Govern Them at Scale

What Are Claude Skills?

Claude Skills, sometimes called agent skills, are reusable capability bundles that teach an agent how to perform a specialized task, such as querying a database, triaging an alert, following an escalation playbook, or drafting release notes. A skill is authored once and reused everywhere, so the same procedure powers a production agent, a local Claude Code session, or Cursor without being rewritten for each one.

The key idea is that a skill is not a prompt you paste in. It is a small, self-contained package the agent reads on demand when the task calls for it.

How a skill is structured

Every skill is a directory rooted at a SKILL.md file. That file has two parts:

• YAML frontmatter with a name and a description. This is the only text the agent sees about the skill upfront, so the description should be action-oriented ("Use when the user asks for sales, usage, or cost numbers") so the model picks the right skill at the right moment.
• A Markdown body with the actual procedure the agent follows once it selects the skill.

A skill can also bundle supporting files next to SKILL.md, such as reference documents and scripts, which the model reads on demand once the skill is in scope. A typical multi-asset skill looks like this:

---

name: analytics-helper

description: How to query the analytics warehouse. Use when the user asks for sales, usage, or cost numbers.

---

‍

# Analytics Helper Skill

‍

## Querying Tables

1. Use the `query.py` script in this skill's `scripts/` directory.

2. Look up schemas in `references/sales-tables.md`.

3. Cap results at 1000 rows unless the user asks for a full export.

‍

## Common Aggregations

For revenue, group by `month_start` and sum `gross_revenue`.

‍

When a user asks "how much revenue did we make in October," the agent reads the skill, follows the steps, and uses the bundled scripts and references to answer, rather than guessing the schema.

Claude Skills work best when

• A task is repetitive and has a known, correct procedure.
• The steps are too long or too specific to live in a system prompt.
• The same workflow needs to run across several agents or tools.
• You want the procedure to improve in one place and propagate everywhere.

Why Managing Claude Skills Gets Hard

Writing your first skill takes minutes. Running a library of them across a company is where teams hit friction, and it usually shows up as the same set of problems.

‍

Skill files end up scattered across repositories, so nobody knows which skills exist or which is the canonical version. There is no version pinning independent of code, so a change to a skill can silently alter an agent's behavior in production. There is no access control per skill, so any team can read or change any procedure. And the same skill gets copied into three repos and slowly drifts out of sync.

‍

These are governance problems, not authoring problems, and they are exactly what a central registry is for.

How TrueFoundry's Skills Registry Governs Claude Skills

In TrueFoundry, skills live in the Skills Registry, a centralized, versioned, RBAC-governed catalog. That is a deliberate contrast with the default experience, where skill files are committed to agent repos or uploaded ad hoc with no shared registry, no version pinning, and no per-skill access control.

‍

Product screenshot, TrueFoundry docs: the Skills Registry.

‍

The registry adds the controls a growing skill library needs:

‍

• Discovery. One catalog across all teams, so people search, browse, and reuse existing skills instead of rewriting them.
• Versioning. Every skill is versioned, and you can pin a specific version per agent for production stability.
• Access control. Skills inherit RBAC from their parent repository, so you control who can read, use, or publish each one.
• Rollback. Revert to a known-good version instantly if a new version misbehaves.
• Audit trail. Every version change and use is logged.
• Cross-agent reuse. The same skill powers multiple agents with no duplication or drift.

‍

Product screenshot, TrueFoundry docs: publishing a skill version.

‍

Because the registry sits alongside the AI Gateway and MCP Gateway, a skill is not an isolated file. Platform teams govern which skills are available to which agents and teams, and agent builders pick from an approved catalog rather than managing files by hand. The skill a developer uses in Claude Code is the same governed artifact a production agent uses, which is what keeps behavior consistent as you scale.

‍