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:
- 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_searchfor exactly this. - 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. - 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:
| Source | Location | Notes |
|---|---|---|
| Project | .tfcode/skill/<name>/SKILL.md | Travels with the repository |
| User config | the tfcode config directory, e.g. ~/.config/tfcode/skill/<name>/SKILL.md | Your own skills, available everywhere |
| Existing conventions | ~/.claude/skills/, ~/.agents/skills/ | Reuses skills you already have |
| Workspace | tf://<id> | Synced from your ToothFairyAI workspace — read only |
| Bundled | inside the binary | Shipped 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:
| Skill | What it does |
|---|---|
review | Review a diff, commit, branch, or PR — in an isolated worktree, with the repo's real checks run before any verdict |
batch | Apply one mechanical change across many files, with a gate for "is this actually a batch?" |
simplify | Clean up shape without changing behaviour |
stuck | Tell a machine problem apart from a reasoning loop, and log-first before guessing |
init | Create or improve an AGENTS.md that describes how the repo really works |
loops | Author and operate structured step-by-step workflows |
models | Inspect the model catalogue and pick a model deliberately |
tf-migrate-agent | Migrate agents from a legacy TF Code install |
reverse-engineer | Understand 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.mdis 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
...
| Field | Required | Purpose |
|---|---|---|
name | yes | Must match the directory name |
description | yes | What the skill does and when to use it — this is what search matches on |
aliases | no | Extra slash commands that resolve to this skill, e.g. aliases: [rea] |
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.
Discovery: skill_search
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:
| Field | Meaning |
|---|---|
name | pass this to skill to load it |
score | relative confidence — compare hits against each other, not a fixed number |
description | the skill's declared intent |
snippet | a 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:
| Action | Purpose |
|---|---|
list | every skill with its source and whether it is read-only |
read | a skill's body |
create / update / delete | write local skills (read-only sources are refused) |
files | the files a skill ships |
read_file / write_file / delete_file | manage the files inside a skill's directory |
search | the same matcher behind skill_search |
history / restore | roll 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.
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.