Skills

Skills are modular extensions to the AI agent. A skill can provide:

• Domain knowledge — documentation, conventions, or constraints injected into the agent’s system prompt
• Runnable scripts — tools the agent can call during a task (shell scripts, Python scripts, TypeScript, executables)
• Reference files — documentation the agent can query mid-task

Skills allow you to give the agent specialised expertise for specific frameworks, internal APIs, company conventions, or complex workflows without modifying Tarsk itself.

How Skills Work

When you send a message, Tarsk scans all available skills and automatically activates those whose descriptions match keywords in your message. Activated skills are appended to the system prompt under an # Available Skills section before the agent processes your request.

You can also explicitly enable or disable specific skills per thread (see below).

Skill Structure

A skill is a directory containing a SKILL.md file. The minimum structure is:

my-skill/
  SKILL.md

The SKILL.md file uses YAML frontmatter followed by the content injected into the system prompt:

---
name: My Skill
description: Provides guidance for working with the internal payments API.
---

## Payments API

Always use the `PaymentService` class from `src/services/payment.ts`.
Never call the Stripe API directly — use the abstraction layer.
...

Frontmatter Fields

Field	Required	Description
name	Yes	Display name for the skill
description	Yes	Used for auto-activation keyword matching
license	No	License identifier (e.g. MIT)
compatibility	No	Intended Tarsk version range
allowed-tools	No	Restrict which agent tools this skill can invoke

Optional Subfolders

my-skill/
  SKILL.md
  scripts/          ← runnable tools exposed to the agent
    generate.sh
    validate.py
    scaffold.ts
  references/       ← documentation the agent can read on demand
    api-spec.md
    schema.json

scripts/ — Any executable file here becomes an agent tool named execute_skill_script. The agent can call it with arguments. Supported types: .sh, .py, .js, .ts, and native executables.

references/ — Files the agent can read via read_skill_reference. Useful for large specifications or schemas you don’t want injected into every prompt automatically.

Skill Discovery Locations

Tarsk looks for skills in two locations:

Location	Scope
~/.tarsk/skills/	Global — available to all projects and threads
<threadPath>/.tarsk/skills/	Project-level — only available within that project

Project-level skills take precedence over global skills with the same name. This lets you override a global skill’s behaviour for a specific project.

Enabling and Disabling Skills Per Thread

By default, skills are auto-activated based on keyword matching. To override this behaviour for a thread:

1. Click the Skills section in the thread’s sidebar panel.
2. Toggle individual skills on (always enabled) or off (always disabled) regardless of keyword matching.

This is useful when a skill is relevant to a project but not to a specific thread, or when you want to force a skill to always be active.

Creating a Skill

1. Create a directory in ~/.tarsk/skills/ (global) or <threadPath>/.tarsk/skills/ (project-level):

   mkdir -p ~/.tarsk/skills/my-skill

2. Create SKILL.md with the frontmatter and instructions.
3. Optionally add scripts/ and references/ subdirectories.
4. Start a new conversation — the skill is available immediately.

Example: Framework Conventions Skill

---
name: React Query Conventions
description: Conventions for using React Query and TanStack Query in this project.
---

## Query Keys

Always define query keys as constants in `src/query-keys.ts`.
Never inline query key strings.

## Mutations

Use the `useMutation` hook from `@tanstack/react-query`.
Always invalidate related queries in `onSuccess`.
...

This skill activates automatically when the user’s message mentions “query”, “fetch”, “mutation”, or similar terms.