You have rules your coding should follow. Review the log, patch the smallest file, keep a test for each fix. Tarsk does not know those rules until you teach it. A Skill is the package you use to teach it: a folder with instructions, optional helper scripts, and reference material that the agent loads only when the task needs it.
Why skills matter
Every conversation sends a prompt to a model. Dump your full project handbook into every prompt and you waste tokens and attention on rules that do not apply. Skills solve that with lazy loading. You can keep many of them cheaply, and Tarsk pulls in the relevant instructions only when a task matches.
A skill also carries tools. A script in a skill becomes something the agent can call, so you can package a trend report, a log summarizer, or a pricing lookup and let the agent run it instead of asking you to paste results.
How a skill is shaped
A Skill is a directory with a SKILL.md file at its root. The file has two parts:
- Frontmatter: fields such as
name,description, andallowed-tools. - Instructions: markdown that tells the agent how to behave and when to apply the skill.
You can add a scripts/ folder whose executables become agent-callable tools, and a references/ folder for longer documents the agent reads only on demand.
The description is the key. Tarsk uses it to decide when the skill activates, so it should say what the skill does and when to reach for it. A description that is too thin makes the skill easy to miss.
Three-tier loading
Skills keep context lean with progressive disclosure:
- Metadata: each skill’s name and description, about a hundred words, loads in every conversation. This is the layer that drive activation matching.
- Instructions: the full skill body loads only when the skill activates for the task.
- References: longer documents load only when the agent reads them.
The result is predictable. With ten skills installed, you carry ten short descriptions in context. You carry one or two full instruction sets for the skills that fired, and you read reference files only when a run needs them. Large skill libraries stay cheap because the heavy content stays out of the prompt.
Activation
Tarsk matches the words in your message against each installed skill’s description. Skills above a relevance threshold activate, up to about five for the task, and their instructions join the prompt.
You can trigger a skill explicitly with a slash command such as /skill-name. A skill author can set disable-model-invocation so the skill activates only when you call it this way, which suits a skill you do not want firing on its own.
Scripts become tools
Put an executable in the skill’s scripts/ folder and the agent gains a tool to run it. Call the agent tool with the skill name and script name, pass arguments, and read the result. Shell, Python, JavaScript, and TypeScript scripts run in their matching runtimes, and other executables run directly.
Follow one best practice when you write a script: make it self-contained. Accept arguments, write structured output to standard out, write errors to standard error, and keep the default run short. The agent can then act on the output instead of asking you to interpret it.
Live data in instructions
A skill can inject live data into its instructions at activation time. Two mechanisms keep the agent current without hard-coded values:
- Model pricing: the
!`tarsk:models`placeholder expands to your enabled models with prices and coding intelligence, sorted cheapest first. - Shell interpolation: an inline
!`command`or a multi-line block runs an allowed command and pastes its output into the instructions.
This is the engine behind a common pattern. One skill lists the cheapest enabled models and then delegates simple subtasks to a subagent pinned to that model, while the main thread stays on a capable model.
What a skill can do for you
Reusable project conventions
Write the rules you keep repeating, once. A skill that says to run the fast check set before finishing, that prefers small patches, and that names the tests to update, turns loose guidance into a repeatable standard.
Packaged helpers
Attach a script that summarizes agent logs or counts failures. Instead of asking for a report each time, the agent runs the script, reads the output, and acts on it.
Cheaper delegation
Add a skill that lists your cheapest enabled models and reach for it when you have low-stakes work. The agent spawns a subagent on the cheap model and keeps the important thread on the capable one.
Common mistakes
Descriptions that under-trigger
If the skill never activates, the description is probably too vague or too passive. Rewrite it with the concrete situations where you want it used, including the words a user would say when they need it.
Bloated instruction files
Keep the skill body under a few hundred lines. Move long material into references/ so it loads on demand, and keep the always-loaded part short.
Authorizing shell commands by accident
Shell interpolation is gated by the skill’s allowed-tools. If you do not declare a shell allowance, the agent cannot run inline commands for that skill. Declare only the patterns you need, so a helper cannot run everything.
Summary
A Skill packages knowledge, scripts, and reference material into something the agent loads only when relevant. Three-tier loading keeps many skills cheap, activation decides when one fires, and interpolation brings in live data like model pricing.
Start a project skill with one convention you keep repeating. Write it in a skill folder, describe when to use it, and let the agent apply it on the next matching task.