How to Use the Updated Skills UI

The updated Skills UI makes it easier to discover, install, and manage skills. You can browse what is installed, search what is available, switch between skill sources, add your own catalog, and open installed skills directly in the Explorer.

This guide explains how to use the updated Skills UI in Tarsk, what skills actually are, how custom sources work, and how the code implements the system behind the screen.

What you will learn

By the end of this guide, you will know how to:

browse installed and available skills
switch between the default source and external catalogs
add your own GitHub-based skill source
install a skill into a thread
inspect and edit installed skills in the Explorer
create your own .agents/skills/<skill-name>/SKILL.md

Before you start

You need:

a project selected in Tarsk
a thread selected if you want to install skills from the UI
a GitHub repository URL if you want to add a custom source

The screen already reflects those requirements. If no project is selected, the page tells you to select one. If no thread is selected, install actions stay disabled until you choose one.

What a skill is

A skill is a reusable instruction package for the agent.

At the file level, the core unit is a folder with a SKILL.md file inside it. That markdown file contains the skill’s identity, a description of when it should be used, and the instructions the agent should follow. A skill can also include helper files such as scripts, templates, and reference notes.

That structure matters because the UI is only one layer. Tarsk works with real files and directories, and the Skills page reflects that file-based model.

A minimal skill looks like this:

.agents/skills/my-skill/
└── SKILL.md

A more complete skill can look like this:

.agents/skills/my-skill/
├── SKILL.md
├── scripts/
│   └── generate-report.py
└── references/
    └── api-notes.md

That model matches the broader Agent Skills pattern: a skill is discoverable by its metadata, activated when relevant, and then expanded into full instructions only when needed. Tarsk follows the same basic idea in its own implementation.

How Tarsk implements skills

The main loader lives in cli/src/features/skills/skills.manager.ts.

That part of the code treats a skill as a directory containing SKILL.md. It loads skills from supported locations, parses frontmatter, validates naming rules, and makes the skill available for activation later.

The system also supports:

frontmatter parsing in skills.frontmatter.ts
auto-activation in skills.activation.ts
explicit skill references in skills.references.ts
argument substitution in skills.arguments.ts
tool restrictions in skills.allowed-tools.ts
external catalogs in skills.catalog.ts
custom source persistence in skills.custom-sources.ts

So when you use the Skills UI, you are not managing a separate product feature. You are managing the actual skill runtime.

Open the Skills page

Go to Settings -> Skills.

The page is rendered by app/components/settings-skills-view.tsx.

You will see two main sections:

Installed
Available

That split is important. Installed skills are already present in your project or thread files. Available skills come from the active source and can be installed.

Use the Installed section

The Installed section shows skill folders already available to the current project and thread.

The UI builds this list from the AI file tree and merges project-level skills with thread-level skills when needed.

Each installed row lets you:

click the skill name to open SKILL.md in the Explorer
remove the skill with the delete action

This is one of the better parts of the updated UI. It does not trap you inside a catalog screen. You can jump straight from discovery to the underlying file and edit it like any other project artifact.

Use the Available section

The Available section is where the newer workflow lives.

From here you can:

search skills by name or description
switch the active source
add a source
edit a selected custom source
preview a skill before installing it

The page uses useSkillCatalog() to manage source selection, source loading, and available catalog items.

Install a skill from the default source

If you just want to try the new UI, start with the default source.

Step 1: Select a thread

Choose a thread first. Installs go into that thread’s AI files, so the UI needs to know where to place the skill.

Step 2: Search in Available

Use the Search available skills... field.

When Default is selected, Tarsk loads a built-in list of popular skills with getPopularSkills() and filters that list by the search text.

Step 3: Open the install preview

Click a skill card.

The page opens SkillInstallPreviewDialog, which gives you a chance to inspect the skill before anything is written into your thread.

Step 4: Confirm the install

After confirmation, Tarsk writes the skill into:

.agents/skills/<skill-id>/SKILL.md

For default-source skills, the UI can generate the SKILL.md content directly from the skill metadata. That includes fields such as:

name
description
allowed-tools when present
license when present

After the write completes, the UI refreshes the Explorer and the skill appears as installed.

Understand skill sources

A skill source is where the Available list comes from.

The source dropdown sits beside the search field. It always includes Default, and it can also include bundled and custom sources.

Bundled sources are defined in cli/src/features/skills/skills.sources.json.

These sources point at GitHub folders that contain multiple skill directories. Tarsk clones the referenced folder, scans each top-level subdirectory, and keeps the ones that contain SKILL.md.

The catalog scanner in cli/src/features/skills/skills.catalog.ts extracts metadata for each skill and returns items like:

id
name
description
sourceId
gitHubRepo
gitHubFolder
gitHubRef

Each source in the UI maps to a real catalog backed by skill folders in a version-controlled repository.

Add your own skill source

This is the part that makes the updated UI much more useful for teams.

Step 1: Click the plus button

When Default is selected, the action button beside the source dropdown shows a plus icon. Click it to open AddSkillSourceDialog.

Step 2: Enter a title and GitHub tree URL

Tarsk expects a GitHub tree URL that points to a folder containing one or more skill directories.

Examples:

https://github.com/owner/repo/tree/main/skills
https://github.com/owner/repo/tree/main/skills/engineering

Step 3: Verify the source

Verification runs through POST /sources/verify in cli/src/features/skills/skills.routes.ts.

During verification, Tarsk:

trims the title and URL
parses the GitHub tree URL
creates a custom source ID with a custom- prefix
clones the target folder into a temp cache
scans for subdirectories that contain SKILL.md
rejects the source if no valid skills are found
saves the source under customSkillSources

Persistence for this lives in cli/src/features/skills/skills.custom-sources.ts.

Step 4: Switch to your new source

After verification succeeds, the source appears in the dropdown. Select it and the Available section changes from the default list to the fetched catalog.

That catalog is loaded through GET /catalog?sourceId=....

Step 5: Edit or remove a custom source

When a custom source is selected, the action button changes from a plus icon to a pencil icon.

That lets you:

update the title or URL
remove the source entirely

Only custom sources can be edited or removed. Bundled sources are fixed.

Install a skill from a custom catalog

The install flow looks almost the same in the UI, but the underlying file behavior is different.

When the selected skill belongs to a catalog source, Tarsk uses installCatalogSkillToThread(...) and can copy the full skill directory into the thread.

That matters because catalog skills often include more than SKILL.md.

A catalog skill may contain:

SKILL.md
scripts/
references/
templates or supporting assets

Tarsk caches cloned sources in cli/src/features/skills/skills.catalog-cache.ts, then copies the whole skill directory into .agents/skills/<skill-id> during installation.

External catalogs are useful because they can deliver complete, structured skills, including scripts, references, and templates.

Open, inspect, and remove installed skills

After installation, the skill appears in Installed.

Click it and Tarsk opens:

.agents/skills/<skill-id>/SKILL.md

From there you can inspect the instructions, adjust the wording, add files, or turn a community skill into a team-specific local version.

If you remove a skill, the page tries to delete it from project AI files first, then thread AI files if necessary. After deletion, it refreshes the Explorer and updates the installed state.

Create your own skill

The UI is useful, but the bigger advantage is that you can make your own skills with the same structure.

Step 1: Create a folder

Create a new folder under .agents/skills.

.agents/skills/release-checklist/

Step 2: Add `SKILL.md`

Use valid frontmatter.

---
name: release-checklist
description: Run the release checklist for app changes, verify checks, and prepare a safe handoff.
---

# Release Checklist

Use this skill when the user asks for a release pass or pre-ship review.

## Instructions

1. Run the required checks.
2. Review changed files.
3. Summarize risk areas.
4. Call out anything that still needs human approval.

Tarsk validates several rules when it loads the skill:

the directory name must match name
the name must use lowercase letters, numbers, and hyphens only
the name cannot start or end with a hyphen
the name cannot contain consecutive hyphens
the description must be present and stay within the allowed length

Step 3: Add optional metadata

The frontmatter parser in skills.frontmatter.ts supports more than just the basic fields.

Useful optional fields include:

license
compatibility
when_to_use
allowed-tools
disable-model-invocation
arguments
argument-hint
nested metadata

That gives you a path from simple reusable prompt to more controlled, structured agent behavior.

Step 4: Add scripts or references

If your skill needs helper code, put it in scripts/. If it needs documentation or notes, put them in references/.

Example:

.agents/skills/release-checklist/
├── SKILL.md
├── scripts/
│   └── collect-notes.ts
└── references/
    └── release-policy.md

Tarsk can expose scripts as tools and load reference files when the skill needs them.

How Tarsk decides when to use a skill

The UI manages skills, but activation happens in the runtime.

Auto-activation

cli/src/features/skills/skills.activation.ts handles automatic matching.

Tarsk:

extracts keywords from the task description
removes common stop words
compares the remaining keywords against each skill’s description and usage text
scores relevance based on overlap
activates up to five skills above the threshold

If a skill has disable-model-invocation, it is skipped for automatic activation.

Explicit references

Tarsk also supports direct invocation in the prompt:

/skill-name [args] for project or global skills
//skill-name [args] for bundled skills

That logic lives in cli/src/features/skills/skills.references.ts.

If you pass arguments, Tarsk can substitute them into the skill content using placeholders handled in cli/src/features/skills/skills.arguments.ts.

How tool restrictions work

Some skills should only have access to a narrow set of tools.

The allowed-tools field provides that control. Tarsk parses it in skills.frontmatter.ts and resolves it in cli/src/features/skills/skills.allowed-tools.ts.

That lets a skill limit itself to specific tool families such as read, write, bash, fetch, or agent.

Tarsk also keeps a few coordination tools available even when restrictions are active:

ask_user
todo
tool_search

And when a skill allows certain tool types, Tarsk can expose related skill helpers such as:

execute_skill_script
read_skill_reference

Where skills live

Tarsk supports three skill scopes:

global skills in ~/.agents/skills
project skills in <threadPath>/.agents/skills
bundled skills shipped with the app

skills.manager.ts loads global skills first and then project skills, so a project skill can override a global skill with the same name.

That model works well in practice:

keep personal helpers in your global skills directory
commit team skills into the project repository
override shared behavior locally when a project needs different instructions

Validate that everything works

After you install or create a skill, verify three things:

it appears in Installed
clicking it opens SKILL.md in the Explorer
it activates for matching tasks or via /skill-name

If something fails, check the basics first:

the folder contains SKILL.md
the folder name matches the frontmatter name
the description uses the words people are likely to type
the name follows the required lowercase hyphenated format

Why the updated Skills UI matters

For many teams, the hardest part of using skills has been visibility, trust, and control.

The updated Skills UI solves the practical parts:

you can see what is already installed
you can browse what is available
you can switch between sources
you can add your own GitHub-based catalogs
you can inspect the files after installation
you can treat skills as editable project assets

The interface stays simple, and the underlying implementation supports catalogs, caching, validation, argument handling, activation rules, and tool restrictions.

Summary

The updated Skills UI acts as a lightweight package manager for agent behavior.

Start with the default source. Add a custom source when your team has its own library. Install a skill, inspect the files, and edit the instructions until the behavior fits your workflow.

If you want the most control, create your own .agents/skills/<name>/SKILL.md and build from there. Tarsk already supports the full path from discovery to activation.