Create, Manage, and Use Skills

Author your skill once, publish a versioned bundle to the Skills Registry, and re-use it across surfaces. Pick the publish path that matches your workflow:

Path	Use when
From UI	Single-file `SKILL.md`. Quickest, no CLI setup needed.
`tfy upload skill` (CLI)	Multi-file skills (supporting `references/`, `scripts/`, `assets/`) — one-shot imperative upload. Works on a dev machine or in CI.
`tfy apply` (CLI, GitOps)	Multi-file skills defined declaratively as a YAML manifest — best fit for GitOps where the skill lives alongside its source.

UI uploads currently support a single SKILL.md file only. Multi-file support from the UI is on the roadmap — for now, if your skill ships supporting files (references/, scripts/, assets/), use one of the two CLI paths below.

All three paths produce the same artifact: a versioned Skill stored under a Repository and addressable by its FQN (e.g. agent-skill:my-tenant/my-skills/analytics-helper:1). Repository access controls who can discover, edit, and use the Skill.

Skills do not have separate per-skill permissions. Manage access on the parent Repository instead. See Repositories for the shared repository concept, storage backing, and access control.

Prerequisites

A Repository with at least one storage integration configured. The skill bundle is stored in this repository’s blob storage. See Repositories for the concept and Create a repository for setup.
For the CLI / GitOps paths — the TrueFoundry CLI installed and authenticated. See CLI Setup.

Publish

From UI
`tfy upload skill`
`tfy apply` (GitOps)

The UI flow is the fastest way to publish a single-file skill. The Gateway uses the SKILL.md content you author here as the entire skill bundle.

The UI flow currently supports a single SKILL.md only — supporting files are not uploaded. Multi-file support from the UI is on the roadmap. If your skill needs references/, scripts/, or assets/, use the tfy upload skill or tfy apply tab instead.

Open the Skills Registry

Navigate to Agents → Skills in the left sidebar and click Create New Skill → Create from UI.

Create New Skill menu showing Create from UI and Upload using CLI options — Create New Skill menu with the Create from UI option highlighted

Fill in the basic fields

Field	Description
Name	Lowercase letters, digits, hyphens. 1–64 chars. Cannot contain `anthropic` or `claude`.
Repository	The Repository where this skill version is stored.
Description	Short, action-oriented description. The agent uses this to decide whether the skill is relevant. 1–1024 chars.

Author the SKILL.md body, save the version

The editor is a Markdown editor. The Gateway automatically prepends the YAML frontmatter from the fields above, so you only write the body — the procedure the agent should follow. Click Save to create v1.

# Analytics Helper Skill

## Querying Tables

To run a query against the warehouse, call …

To create a new version later, open the skill and click New Version in the version list.

Use the CLI when your skill ships supporting files. The CLI reads your local folder, validates SKILL.md, and registers a new version. Works equally well from a developer machine or a CI job.

Lay out the skill folder

analytics-helper/
├── SKILL.md
├── references/
│   └── sales-tables.md
└── scripts/
    └── query.py

SKILL.md must start with YAML frontmatter — see How to Write a Skill for the rules.

Run tfy upload skill

From the parent directory of your skill folder:

tfy upload skill \
  --repository my-skills \
  --dir ./analytics-helper

The CLI validates the frontmatter, uploads the bundle, and registers the new version. On success:

Uploaded skill version successfully.

The version appears in the Skills Registry, e.g. agent-skill:my-tenant/my-skills/analytics-helper:1. See CLI Reference for the full flag list.

Define the skill as a YAML manifest and apply it with tfy apply — the same mechanism used for deployments, prompts, and other TrueFoundry resources. See Using tfy apply for the general overview.

Author the manifest

Point source.skill_dir at the skill folder; tfy apply packages and uploads it.

manifests/analytics-helper.yaml

type: agent-skill
name: analytics-helper
ml_repo: my-skills
metadata: {}
source:
  type: local
  skill_dir: ./skills/analytics-helper

See the manifest reference below for every field.

Apply

tfy apply -f manifests/analytics-helper.yaml

# Or apply an entire directory of manifests at once:
tfy apply --dir ./manifests

Typical GitOps repository layout & CI workflow

my-repo/
├── .github/workflows/tfy-apply.yaml    # CI: tfy apply on merge to main
├── skills/
│   ├── analytics-helper/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   └── scripts/
│   └── customer-triage/
│       └── SKILL.md
├── manifests/
│   ├── analytics-helper.yaml           # points to ./skills/analytics-helper
│   └── customer-triage.yaml            # points to ./skills/customer-triage
└── .tfyignore                          # optional: skip files when packaging

.github/workflows/tfy-apply.yaml

name: Apply TrueFoundry manifests
on:
  push:
    branches: [main]

jobs:
  apply:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install -U truefoundry
      - run: tfy login --host ${{ secrets.TFY_HOST }} --api-key ${{ secrets.TFY_API_KEY }}
      - run: tfy apply --dir ./manifests

Use the Skill

Once a skill version exists, you can use it from any of three surfaces. Open the Usage tab on the Skill Detail page in the UI to copy the exact command pre-filled with your skill’s FQN.

Skill Detail drawer showing the Usage tab with Download, Add to Cursor, and Add to Claude options and a copyable tfy download skill command — Skill Detail showing the Usage tab with Download, Add to Cursor, and Add to Claude options

TrueFoundry Agent
Claude Code
Cursor

Mount the skill into a TrueFoundry Agent from the Agent Playground. The Gateway loads the skill alongside the agent’s tools and runs it inside a sandbox.See Mounting Skills in TrueFoundry Agents for the full flow — selector, version pinning, and the Preload SKILL.md toggle.

Sync the skill into Claude Code’s local skills directory. Claude Code picks up new skills from this directory automatically.

tfy download skill \
  --fqn agent-skill:my-tenant/my-skills/analytics-helper:1 \
  --dir "$HOME/.claude/skills"

Use the Usage → Add to Claude tab on the Skill Detail page to grab this command pre-filled with the right FQN.

Sync the skill into Cursor’s local skills directory.

tfy download skill \
  --fqn agent-skill:my-tenant/my-skills/analytics-helper:1 \
  --dir "$HOME/.cursor/skills"

Use the Usage → Add to Cursor tab on the Skill Detail page to grab the command pre-filled with the exact path for your install.

To pull the bundle to disk for editing, mirroring, or auditing, point --dir at any local path (e.g. ./skills). Edit the files and re-publish a new version with tfy upload skill.

CLI Reference

tfy upload skill — full flag reference

Publish a new version of an agent skill from a local directory.

tfy upload skill \
  --repository <repository-name> \
  --dir <path-to-skill-root>

Flag	Required	Default	Description
`--repository`	yes	—	Name of the Repository where the skill version will be published. Must already exist.
`--dir` / `-d`	no	`.`	Path to the local skill root directory. Must contain `SKILL.md` at the root.

tfy download skill — full flag reference

Download a committed skill version’s files to disk.

tfy download skill \
  --fqn <skill-version-fqn> \
  --dir <local-destination> \
  [--overwrite] \
  [--progress | --no-progress]

Flag	Required	Default	Description
`--fqn`	yes	—	Skill version FQN. Version must be a positive integer; `:latest` is not supported.
`--dir` / `-d`	no	`.`	Local destination directory. Created if missing. Skill files land inside a sub-directory named after the skill.
`--overwrite`	no	`false`	When set, existing files in the destination are overwritten.
`--progress` / `--no-progress`	no	auto	Show a progress bar while downloading.

tfy apply — agent-skill manifest reference

Field	Required	Description
`type`	yes	Must be `agent-skill`.
`name`	yes	Skill name. Must match the `name` in `SKILL.md` frontmatter.
`ml_repo`	yes	Name of the target Repository. (The field is named `ml_repo` for consistency with other TrueFoundry manifests.)
`metadata`	yes	Free-form key/value metadata. Use `{}` if you don’t need any.
`source.type`	yes	`local` for GitOps. Other source types exist but are server-managed.
`source.skill_dir`	yes	Path to the local skill folder, relative to your `tfy apply` working directory — typically the root of your Git repo. The folder must contain `SKILL.md`.

Get Started

LLM Gateway

MCP Registry and Gateway

Skills Registry

Prompt Registry

Guardrails and Security

Observability

Deployment

Admin Guide

Chat

Messages

Embeddings

Rerank

Responses

Image

Audio

Batch

Files

Fine-tuning

Moderations

Models

Create, Manage, and Use Skills

Prerequisites

Publish

Use the Skill

CLI Reference

​Prerequisites

​Publish

​Use the Skill

​CLI Reference

Prerequisites

Publish

Use the Skill

CLI Reference