# Skills

A skill is a set of instructions that shapes how an agent behaves. It's a Markdown file with YAML frontmatter — no code, no compilation, no deployment. Write one in a text editor, and your agents can use it immediately.

## How skills work

Skills live in `~/.crabtalk/local/skills/<name>/SKILL.md`. When loaded, the skill's content is injected into the agent's context, guiding its behavior for the current session.

Load a skill two ways:

- **Slash command**: type `/<skill-name>` in the REPL
- **Automatic**: agents discover skills via BM25 search over names and descriptions

## SKILL.md format

```
---
name: code-review
description: Review code for bugs, security issues, and style problems
allowed-tools:
  - read_file
  - search_files
---

Review instructions go here in Markdown...
```

| Field          | Required | Description                                                                 |
|----------------|----------|-----------------------------------------------------------------------------|
| `name`        | Yes      | Identifier, used in `/name` slash commands                                  |
| `description` | Yes      | One-line summary — affects search ranking                                   |
| `allowed-tools` | No      | YAML list of tool names to pre-approve                                      |
| `license`     | No       | License reference                                                            |
| `compatibility` | No      | Requirements (e.g., "Requires git")                                       |

## Discovery

The skill registry indexes names and descriptions using BM25 search. When an agent needs a capability, it searches the registry by keyword. Better descriptions rank higher — be specific about what the skill does.

Fuzzy matching handles typos and partial names in slash commands.

## Scoping

Agents can be restricted to specific skills:

```
[agents.writer]
skills = ["technical-writing", "blog-post"]
```

Empty list means access to all skills. Scoping keeps agents focused on their role.

## Installing from the hub

```
crabtalk pull <scope>/<package>
```

Skills are auto-discovered from the package's source repository — any `SKILL.md` file gets picked up after install.

## What's next

- [Write a Skill](/content/blog/write-a-skill/index.html) — create your own skill step by step
- [Agents](/content/docs/crabtalk/agents/index.html) — how agents load and scope skills

### On this page