Add a tool to Tarsk with two files

The list of tools the model can call is not compiled into Tarsk. It comes from folders you can open, read and copy. read, bash, notes, computer and the rest arrive the same way a tool you write arrives.

That makes a new tool a small writing job. Two files, then a chat.

Two files and a name

A tool lives inside a skill. Create a folder in the project’s .agents/skills/ directory with two files:

.agents/skills/deploy-status/
  SKILL.md
  scripts/deploy_status.js

SKILL.md names the tool:

---
name: deploy-status
description: Reports the deploy status of the current project.
version: 1.0.0
tools:
  - deploy_status
---

The folder name and name must match, or Tarsk skips the package. The tool name comes from the tools list, not from the file name. A file called deploy_status.js under a tools list that says something else publishes nothing, and Tarsk treats it as an ordinary helper script.

What the script exports

Three exports, in a plain JavaScript file:

export const description = "Report the deploy status of the current project.";

export const parameters = {
  type: "object",
  properties: { environment: { type: "string" } },
};

export async function execute(args, context) {
  const out = await context.shell.run("deploy", ["status"]);
  return { content: [{ type: "text", text: out }] };
}

The model reads the description when it decides whether this tool fits the request, and tool search matches on it. Write the words a user would use: “deploy”, “release”, “staging”.

A project script cannot import a module. Tarsk rejects the file and the tool never appears. Everything the script needs comes from context, which is how Tarsk keeps its own path checks, permission prompts and sandbox in the loop.

Where it lands

The tool joins the next run. The chat you have open keeps the tool set it started with, so send a message or start a chat to see it.

One rough edge: Settings → Tools has a row for each tool Tarsk ships, and no row for a tool you write. A custom tool also cannot go in a project’s disabled list, because Tarsk drops names it does not recognize. To remove your tool, delete or rename the folder.

Deferred tools and search

Thirty-eight tools ship with Tarsk across thirty-two skills. Ten of them sit in front of the model all the time: read, write, edit, bash, find, grep, run_js, read_skill, ask_user, connect_mcp. The other twenty-eight are deferred. The model sees their names and searches for the rest when a task calls for one.

You choose deferral per skill with a deferred-tools list. Defer the heavy ones and keep the common ones in front. A deferred tool with a thin description is close to invisible, because search reads names and descriptions and never the parameters.

What happens when it breaks

A broken tool fails quietly. It is absent from the next run and the log holds one warning. Four causes cover most cases:

• The folder name and name in the front matter disagree, so Tarsk skips the whole package.
• The tools list names a tool with no matching script.
• The script is missing description, parameters or execute.
• A project script imports a module.

Editing a tool script through the agent is the exception. Tarsk reloads the file as the edit lands, and if the new code fails to load it restores the previous bytes and reports what went wrong in the chat.

Editing a tool Tarsk ships

Settings → Tools has an Eject action. It copies the shipped tool skills into your project so you can edit them, and from then on your copy wins. Only skills whose contents changed stay in the repository: Tarsk prunes copies that match the shipped version.

If the chat runs on a remote machine, commit the skill folder. The remote side sees committed files only, so an uncommitted .agents/skills/ folder publishes nothing there. The shipped tools travel with the app install and work either way.

Try it

• Write the two files for a small tool, then ask the agent to use it in a new chat.
• Eject the tools, open scripts/grep.js in your editor, and change how much output it returns.
• Defer a tool you rarely use and find it again by asking for it by name.

Download Tarsk or read the documentation.