> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Skills

> Skills are an open standard to extend agent capabilities. At its core, a skill is a folder containing a `SKILL.md` file with instructions that the agent can follow when working on specific tasks.

## What Are Skills?

Skills are portable, version-controlled packages of knowledge that extend the agent's capabilities to perform domain-specific tasks.

When you start a conversation in Kombai, the agent sees the names, descriptions, and file paths of all available skills. If your task matches a skill's description, the agent then reads the entire `SKILL.md` file and follows the instructions while performing the task.

You can also invoke a skill explicitly by typing `/skill-name` in the chat input.

### Benefits of Skills

<Columns cols={2}>
  <Card title="Human-Readable" icon="book-open" color="#3B82F6">
    Skills are just plain Markdown files that anyone on your team can read,
    review, and improve.
  </Card>

  <Card title="Cross-Agent Compatible" icon="arrows-rotate" color="#8B5CF6">
    Skills work across all AI agents that support the [Agent Skills Open
    Standard](https://agentskills.io/home).
  </Card>

  <Card title="Flexible & Extensible" icon="puzzle-piece" color="#F59E0B">
    Skills can be lightweight instructions or complex packages with scripts, docs,
    templates, and other assets as needed.
  </Card>

  <Card title="Portable & Shareable" icon="share-nodes" color="#10B981">
    Skills are self-contained folders that can easily be distributed across
    projects, teams, or the broader community.
  </Card>
</Columns>

## How to create a Skill

1. Create a folder inside `.kombai/skills/` in your project (or `~/.kombai/skills/` for global skills).
2. Add a `SKILL.md` file with YAML frontmatter (`name`, `description`) and Markdown instructions.
3. Kombai now detects the new skill automatically via a filesystem watcher. You don't have to reload the IDE.

## How Kombai uses a Skill

1. **Discovery:** When you start a conversation, the frontmatter (`name`, `description`, `filepath`) of all the available skills is added to the context.
2. **Evaluation:** The agent evaluates your request against all descriptions.
3. **Activation:** If the agent determines a skill clearly matches the assigned task, it adds the full `SKILL.md` to the context.
4. **Execution:** The agent follows the instructions in the skill to perform the task.

## Skill directories

Skills are automatically loaded from these locations:

| Location | Path                                                           | Scope                                |
| -------- | -------------------------------------------------------------- | ------------------------------------ |
| Global   | `~/.kombai/skills/` or `~/.agents/skills/`                     | Personal. Available in all projects. |
| Project  | `<workspace>/.kombai/skills/` or `<workspace>/.agents/skills/` | Team. Version-controlled.            |

## Mode-specific Skills

You can create a skill that only appears in a specific mode using the directory naming pattern `skills-{mode}`:

```
.kombai/
├── skills/              # Available in all modes
├── skills-ask/          # Ask mode only
├── skills-code/         # Code mode only
├── skills-plan/         # Plan mode only
└── skills-debug/        # Debug mode only
```

### Example command to create a mode-specific Skill

```bash theme={null}
# For Code mode only
mkdir -p .kombai/skills-code/typescript-patterns

# For Plan mode only
mkdir -p .kombai/skills-plan/microservices
```

## Skill folder structure

`SKILL.md` is the only required file in the Skills folder. You can optionally include additional resources:

```
my-skill/
├── SKILL.md         # Main instructions file
├── scripts/         # Executable code the skill can invoke
├── references/      # Supplementary docs loaded on demand
└── assets/          # Templates, design tokens, examples
```