TrueFoundry Skills Registry, Explained: Versioning Procedural Knowledge Across Agents

Skills package instructions, references, scripts, and assets into reusable procedures. A registry makes those bundles discoverable and versioned—but not automatically trustworthy.

TrueFoundrySeptember 19, 20269 min read

Source framing. This explainer is based on TrueFoundry’s AI Gateway Skills Registry and Create, Manage, and Use Skills documentation plus TrueForge’s Skills and Harness Capabilities documentation, reviewed September 19, 2026. Current docs describe repository-level RBAC and versioning, numbered FQNs, UI publishing for single-file skills, CLI or GitOps publishing for multi-file bundles, use across TrueFoundry Agents, Claude Code, and Cursor, and progressive disclosure in TrueForge. Security review, signing, evaluation, and release admission below are recommended controls, not claimed built-in certification.

A skill is a package of procedure, not a new permission

An agent skill describes how to perform a recurring task. Its root SKILL.md contains a name, an action-oriented description, and the procedure. A richer bundle can include reference material, scripts, and assets. This structure separates procedural knowledge from a monolithic system prompt and lets the runtime load detail only when the skill is relevant.

The distinction between knowledge and authority matters. A skill can tell an agent how to query a warehouse, triage an incident, or draft release notes. It does not, by itself, grant database access, authorize an incident response, or make a generated release note correct. Tools, credentials, gateway policy, and downstream systems remain the authority path.

TrueFoundry’s Skills Registry gives the package a shared identity. Skills live in Repositories, inherit repository access and version history, and are addressed by numbered fully qualified names. Teams can publish once and reuse the bundle in TrueFoundry Agents, Claude Code, or Cursor.

Progressive disclosure reduces initial context by exposing only selection metadata. It does not make the selected procedure safe, so the full bundle remains a governed artifact.

Progressive disclosure is the runtime design

TrueForge documents that an attached skill contributes only its name and description to the initial model context. The full SKILL.md body is read on demand from the sandbox when the agent decides the skill is relevant. This reduces initial context while keeping the procedure available.

The description is therefore a routing surface. If it is vague, the agent may fail to select the skill or select it for the wrong task. Keep it action-oriented, state when the skill should be used, and avoid overlapping descriptions that make selection ambiguous. Selection behavior should be evaluated with realistic user requests, including near misses.

Progressive loading controls context size; it does not isolate untrusted content. Once selected, the skill body and supporting files influence the agent. Scripts can execute inside the configured sandbox, and references can shape tool use. Treat a multi-file skill like a software artifact with a supply chain.

Three publishing paths, one versioned artifact

TrueFoundry documents three publishing paths. The UI creates a single-file skill whose body is the SKILL.md content authored in the editor. Multi-file bundles use the CLI upload command or a declarative manifest applied through GitOps. All paths create a versioned Skill under a Repository and yield an FQN such as a repository-qualified skill at version 1.

The UI currently supports only the single SKILL.md file. References, scripts, and assets require a CLI or GitOps path; multi-file UI support is documented as roadmap. The CLI validates the frontmatter and uploads the bundle. GitOps points a manifest at a local skill directory and publishes through the same apply workflow used for other TrueFoundry resources.

The publishing paths differ operationally but converge on the same repository and version identity. That identity lets agents and local coding surfaces consume a concrete bundle instead of an informal copy.

Repository access is inherited

Skills do not have separate per-skill permissions in the documented model. Discovery, edit, and use rights come from the parent Repository. That makes repository boundaries the practical unit of governance. Group skills by compatible ownership and sensitivity rather than placing every procedure in one catalog with broad access.

Repository access answers who may retrieve or use the bundle. It does not constrain every action the skill recommends. A user who can use a database skill still needs authorization at the database tool and business-resource layer. Conversely, revoking a skill does not necessarily revoke the underlying tool access.

LayerWhat it controlsWhat it does not proveRepositoryWho can discover, edit, or use stored skill versions.That the skill content is safe or effective.Skill bundleProcedure, references, scripts, and assets.Permission to call external systems.TrueForgeRuntime loading and sandbox-backed use for attached skills.Correctness of the procedure or business outcome.Gateway and toolIdentity, access, guardrails, approvals, and routed execution.That the task result met its purpose.

Version pinning is the foundation of reproducibility

The Skills CLI documentation requires a positive integer version when downloading and says a latest alias is not supported. That is a useful operational property: consumers name a concrete bundle. Pin the same concrete version in agent configuration and local developer environments when you need comparable behavior.

A version still needs provenance. Record the source repository commit, publisher, build or packaging process, file digests, dependencies, and review result. For scripts, pin external packages and record the execution environment. A numbered FQN identifies what the registry stored; provenance explains how that bundle was produced.

Scripts and references create different risks

Reference files can be stale, incomplete, or adversarially modified. Scripts can read and transform data, invoke local commands, or call services through available interfaces. Assets can contain active or malformed content. Review each class with an appropriate control rather than treating the directory as undifferentiated Markdown.

Static checks can validate frontmatter, path traversal, archive structure, file size, forbidden binaries, dependency declarations, and known dangerous patterns. Sandboxed tests can exercise scripts with synthetic inputs and denied network access. Task evaluations can measure whether the agent selects the skill and follows its constraints. Human review should focus on privileged procedures and irreversible actions.

The admission pipeline separates storage, inspection, task performance, and runtime authorization. No single check certifies every property of a skill.

Promotion should be consumer-aware

The same skill can be used by a TrueFoundry Agent, Claude Code, and Cursor, but those surfaces do not necessarily share identical models, tools, sandboxing, or user identity. Portability of format is not equivalence of runtime behavior. Test the skill in each supported surface and record the environment in the result.

A skill that is safe when paired with read-only MCP tools may be unsafe when a local coding environment exposes write access and shell commands. Release metadata should name expected tool dependencies, required permissions, compatible runtime versions, and prohibited environments.

A disciplined skill lifecycle

Start with a narrow task and a description that makes selection testable. Author the procedure with explicit preconditions, allowed tools, evidence requirements, error handling, and stopping rules. Publish a candidate version. Run static, sandbox, and behavioral tests. Admit it for named consumers. Observe selection, tool use, failures, and outcomes. Retire the version by removing consumers and access, then retain the evidence required by policy.

Do not mutate a widely used skill in place through informal file distribution. Publish a new version, diff the complete bundle, and roll consumers deliberately. When a vulnerability is found in a script or reference, identify every consuming agent and developer surface through version inventory.

Numbered versions are identities, not compatibility promises

A version number tells consumers which bundle they received. It does not, by itself, communicate whether an update is backward-compatible. A changed tool name, file path, output schema, or required permission can break an agent even when the procedure reads similarly.

Publish compatibility metadata alongside the bundle: expected runtime, required tools, supported input and output contracts, dependency versions, data classifications, and known migrations. For breaking changes, keep the prior version available long enough for consumers to move deliberately. Avoid teaching agents to download a moving “latest” bundle at runtime; resolve the approved number during release.

Inventory is essential for incident response

When a reference becomes false or a script dependency is compromised, responders need to answer two questions quickly: which versions contain the problem, and where are those versions used? Registry identity supplies the first anchor, but consumer inventory must include TrueFoundry Agents and any local Claude Code or Cursor installations synchronized from the registry.

Local copies can outlive repository access changes. Revoking use permission prevents future retrieval but does not erase a bundle already downloaded to a developer machine. Incident plans should distinguish registry containment, runtime detachment, local remediation, tool credential revocation, and downstream reconciliation. Retirement is complete only when risky authority and affected copies are addressed.

Outcome evaluation should follow the procedure

Skill evaluation needs more than selection tests. Verify that the agent follows preconditions, uses the intended tools, respects row or cost limits, handles missing data, cites the right references, and stops before unauthorized effects. Then check the authoritative task outcome. A syntactically correct tool trajectory can still produce a bad business result.

Store the skill FQN with each evaluation and runtime trace. That lets teams compare versions, detect regression, and decide whether a failure belongs to the skill, model, tool, data, or surrounding policy. Without the version link, a shared procedure becomes impossible to govern at scale.

Failure tests worth keeping

• Use prompts that should and should not select the skill; measure false selection and missed selection.
• Publish a multi-file bundle with unexpected paths, symlinks, oversized files, and undeclared dependencies.
• Change only a supporting script or reference; confirm the bundle diff and version change expose it.
• Run the same version across supported surfaces and compare tool reach and behavior.
• Revoke repository use access and confirm consumers cannot retrieve a new copy.
• Remove a skill from an agent while leaving tool access intact; confirm the distinction is understood.
• Retire a vulnerable version and inventory every pinned consumer before declaring remediation complete.

How Skills Registry and TrueForge fit together

Skills Registry is the distribution and governance surface for versioned procedural bundles. TrueForge is the runtime that exposes attached skill metadata, loads the full procedure on demand, and executes supporting work through its sandbox and tools. AI Gateway and MCP Gateway govern model and tool traffic around that runtime.

None of those layers certifies a procedure. The useful platform story is compositional: registry identity and repository access, runtime context management, tool authorization, and evidence can line up around the same pinned skill version.

The operational rule

Treat skills as code-adjacent release artifacts. Keep descriptions precise, pin numbered versions, review the complete bundle, test selection and execution, and scope repositories to real ownership boundaries.

TrueFoundry’s registry makes procedural knowledge reusable across agents and developer surfaces. TrueForge makes that knowledge economical to load at runtime. The system becomes trustworthy only when versioning is joined to admission, least privilege, sandboxing, and outcome evidence.

References

1. TrueFoundry — AI Gateway Skills Registry.
2. TrueFoundry — Create, Manage, and Use Skills.
3. TrueForge — Skills.
4. TrueForge — Harness Capabilities.

Editorial disclosure. This article reflects TrueFoundry’s engineering interpretation of the cited public materials as of September 19, 2026. Product capabilities are scoped to linked documentation. Examples and operating defaults are illustrative; they are not legal advice, an audit opinion, an independent benchmark, or a guarantee of security, safety, or compliance.

Slug: truefoundry-skills-registry-explainedSEO title: TrueFoundry Skills Registry, ExplainedMeta description: Learn how TrueFoundry Skills Registry versions SKILL.md bundles, applies repository RBAC, supports UI, CLI and GitOps publishing, and integrates with TrueForge.

‍