Skip to main content
Version: v3 (beta)

Skills

A skill is a set of instructions the agent loads on demand. It is not a tool: a tool lets the model act, a skill tells it how to approach a kind of task — the steps, the order, the gotchas, and the checks to run before claiming success.

This matters because a prompt cannot carry every workflow. Loading all of them would cost more context than the task itself, so TF Code keeps them on disk and loads the one that fits.

Why skills exist​

Three things follow from "load on demand", and they are the whole design:

  1. The agent has to be able to find the skill. A skill nobody can discover is a file in a repository. TF Code exposes skill_search for exactly this.
  2. The catalogue must stay cheap. Skill names are advertised; full instructions are not. Above eight skills the prompt switches to a compact list and points at skill_search — about 1,500 tokens saved per request.
  3. Scripts and references belong with the skill. A workflow often needs a helper script or a reference table. Both live in the skill's directory and are only read when needed.

Where skills come from​

TF Code discovers skills from several places. Precedence runs top to bottom — a skill closer to your project wins a name collision:

SourceLocationNotes
Project.tfcode/skill/<name>/SKILL.mdTravels with the repository
User configthe tfcode config directory, e.g. ~/.config/tfcode/skill/<name>/SKILL.mdYour own skills, available everywhere
Existing conventions~/.claude/skills/, ~/.agents/skills/Reuses skills you already have
Workspacetf://<id>Synced from your ToothFairyAI workspace — read only
Bundledinside the binaryShipped with TF Code, read only

Bundled and workspace skills are read-only on purpose: an upgrade or a sync must be able to update them without colliding with your edits. Customising a bundled skill means copying it into .tfcode/skill/ under the same name — your copy then shadows the bundled one.

Bundled skills​

TF Code ships with workflow skills so a fresh install is useful before you write anything:

SkillWhat it does
reviewReview a diff, commit, branch, or PR — in an isolated worktree, with the repo's real checks run before any verdict
batchApply one mechanical change across many files, with a gate for "is this actually a batch?"
simplifyClean up shape without changing behaviour
stuckTell a machine problem apart from a reasoning loop, and log-first before guessing
initCreate or improve an AGENTS.md that describes how the repo really works
loopsAuthor and operate structured step-by-step workflows
modelsInspect the model catalogue and pick a model deliberately
tf-migrate-agentMigrate agents from a legacy TF Code install
reverse-engineerUnderstand unfamiliar code or a binary from the outside in (alias: /rea)

These are ordinary skills, not privileged ones. Read them, copy them, replace them.

Skill structure​

A skill is a directory. Only SKILL.md is required.

.tfcode/skill/deploy/
├── SKILL.md # required: frontmatter + the instructions
├── references/
│ └── runbook.md # read when the workflow needs it
└── scripts/
└── verify.sh # executed by the agent, never loaded as text

The split is deliberate:

  • SKILL.md is what gets loaded when the skill is invoked. Keep it focused.
  • references/ holds detail that is only sometimes needed — long tables, schemas, environment notes. The agent reads a specific file instead of paying for the whole document.
  • scripts/ holds runnable helpers. These are executed, not read into context, so a script costs nothing until it produces output.

When a skill is loaded, TF Code lists the files it ships, so the agent knows what it can read or run.

Frontmatter​

---
name: deploy
description: Deploy the service to staging or production, with a pre-flight check and a rollback path. Use whenever the user asks to deploy, ship, release, or roll back.
aliases: [ship, release]
---

# Deploy

...
FieldRequiredPurpose
nameyesMust match the directory name
descriptionyesWhat the skill does and when to use it — this is what search matches on
aliasesnoExtra slash commands that resolve to this skill, e.g. aliases: [rea]
Write the description for search

The description is the most important field. skill_search ranks a skill's name and description higher than its body, because the declared intent is stronger evidence than one sentence inside it. A description that says when to use the skill ("use whenever the user asks to deploy, ship, or roll back") will match far better than one that only says what it does.

The agent does not guess at skill names. When a task looks procedural and no name obviously fits, it calls skill_search with the task's own vocabulary:

{ "query": "review this pull request safely", "limit": 5 }

Each hit returns four things:

FieldMeaning
namepass this to skill to load it
scorerelative confidence — compare hits against each other, not a fixed number
descriptionthe skill's declared intent
snippeta short window from the body, to confirm the match

Matching is semantic rather than literal: the query and each skill's name, description, and body are scored with a local hashed n-gram cosine. It needs no network call and no model, and a paraphrase still works — "ship this to prod" finds a deployment skill that never uses the word "ship".

A weak top score is useful information: it usually means no skill covers the task, and the agent should proceed on its own rather than force the closest match.

Search covers every source — bundled, project, user, ~/.claude, ~/.agents, and workspace skills. A skill your team wrote for its own review or deploy process is searched exactly like a built-in one, and should be preferred for that team's work, because it encodes conventions a bundled skill cannot know.

Loading: the skill tool​

{ "name": "review" }

The response is a <skill_content name="..."> block with the skill's instructions. If the skill ships files, their paths are listed so the agent can read or run the ones it needs.

Slash commands​

Every skill is also addressable as a slash command. A skill named review is /review; aliases add extra names, so reverse-engineer with aliases: [rea] is reachable as both /reverse-engineer and /rea. Browse the whole catalogue with /skills in the TUI or the web app.

Authoring skills​

Skills are usually written with the skill_manage tool rather than by hand, so the agent can create or refine one as it works:

ActionPurpose
listevery skill with its source and whether it is read-only
reada skill's body
create / update / deletewrite local skills (read-only sources are refused)
filesthe files a skill ships
read_file / write_file / delete_filemanage the files inside a skill's directory
searchthe same matcher behind skill_search
history / restoreroll a skill back to an earlier version

Writing a file into a skill is how you give it a references/ or scripts/ directory:

{
"action": "write_file",
"name": "deploy",
"path": "scripts/verify.sh",
"content": "#!/bin/sh\nset -eu\ncurl -fsS localhost:8080/health\n"
}

Paths are resolved inside the skill's own directory: absolute paths, .., and NUL bytes are rejected, so a skill write can never escape into the rest of the repository.

Skill history

If self_improve_skills is on, every update snapshots the previous version. See Self-improving skills.

Lean mode​

Skills are never removed by lean mode. skill, skill_search, and question are exempt from the lean allowlist, because lean mode exists to drop tools — not to strand the workflows the system prompt advertises. A lean session told to call skill_search and unable to would be worse than a large one.

See Lean mode.

Permissions​

The skill permission key gates the whole surface — loading, managing, and searching:

{
"agent": {
"build": {
"permission": {
"skill": "deny"
}
}
}
}

Search is read-only across the catalogue and is not blocked by a skill-scoped rule, so denying one skill does not make the rest undiscoverable. Denying skill outright removes the catalogue from the prompt as well.