# How Custom Skills Work in Reasonix: Discovery, Loading, and Execution Mechanisms

> Discover how Reasonix custom skills work. Learn about their filesystem discovery, session startup indexing, and on-demand loading mechanisms using the run_skill tool.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: internals
- Published: 2026-08-07

---

**Custom skills in Reasonix are reusable markdown playbooks that are discovered via configured filesystem roots, indexed at session startup in [`internal/skill/index.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/index.go), and loaded on-demand through the `run_skill` tool, which executes them either inline or as isolated sub-agents based on YAML front-matter flags.**

DeepSeek-Reasonix (esengine/DeepSeek-Reasonix) treats skills as self-contained automation scripts that extend the agent's capabilities without modifying core code. The system employs a lazy-loading architecture defined in [`internal/skill/tools.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/tools.go) that keeps initial prompts lightweight while enabling dynamic discovery from multiple configurable paths.

## Skill Types and Execution Models

Reasonix supports two distinct execution models determined by a skill's front-matter configuration:

- **Inline skills** — When the `[🧬 subagent]` flag is absent, the markdown body is read and returned directly to the model as a tool result. No separate process is spawned, and the content renders as plain text (`<skill-pin …>`) in the prompt.
- **Sub-agent skills** — Marked with `runAs: subagent` in the front-matter, these spawn an isolated Reasonix session via `SubagentRunner` ([`internal/skill/tools.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/tools.go), lines 17-20). Only the final distilled answer returns to the parent session, making this ideal for complex, sandboxed tasks.

## Discovery and Indexing Mechanism

When a Reasonix session initializes, it builds a searchable **Skills index** by scanning configured filesystem roots before the model receives its first prompt.

### Configuration via TOML

The `[skills]` configuration block in your [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) (or [`reasonix.example.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.example.toml)) controls which directories are scanned:

```toml
[skills]
paths = ["~/my-skills", "../shared/skills"]   # extra custom skill roots

excluded_paths = ["~/.agents/skills"]        # hide convention roots without deleting

disabled_skills = ["review"]                 # omit from prompt and tool invocation

```

Default roots always include `.reasonix/skills` within the project directory, plus `.agents/skills` and `.claude/skills` if present in the user's home directory.

### The Indexing Process

The indexer ([`internal/skill/index.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/index.go), lines 19-27) recursively scans configured paths for files named [`SKILL.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/SKILL.md) or `<name>.md`. It extracts the bare identifier (filename without extension) and metadata into an in-memory map that `run_skill` and `read_skill` consult during invocation. Crucially, the actual markdown bodies are **not** loaded during this phase to minimize memory footprint and startup latency.

## Loading and Execution Architecture

Skills employ an on-demand loading pattern that defers file I/O until the moment of invocation.

### Lazy Loading via Tool Dispatch

When the model calls `run_skill` or issues a slash command, the tool looks up the skill's canonical path from the pre-built index and reads the file from disk at that exact moment ([`internal/skill/tools.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/tools.go), lines 42-48). This ensures that edits to skill files on disk take effect immediately on the next turn without requiring a session restart.

### Execution Path Determination

The `run_skill` implementation checks the skill's YAML front-matter for the `runAs` flag:

- If `runAs: subagent` is present, it initializes a `SubagentRunner`, feeds the skill body as the sub-agent's system prompt, and supplies the `arguments` parameter as the sub-agent's sole task.
- If the flag is absent, the raw markdown body is returned as a tool result, allowing the parent model to process the instructions directly.

### Tool Contracts and Schemas

The skill system exposes strict JSON schemas ([`internal/skill/tools.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/tools.go), lines 60-78) defining required arguments including `name`, optional `arguments`, and for sub-agents, `continue_from`. Additionally, the `install_skill` function (lines 460-548) enables programmatic creation of new skills, triggering the `InstalledHook` callback to refresh the index without restarting the Reasonix process.

## Creating and Installing Custom Skills

Skills are standard markdown files with YAML front-matter stored in configured directories.

### Inline Skill Example

Create `~/my-skills/quick-note.md`:

```markdown
---
description: Take a quick note
---
Write the following note to a file called "note.txt":
{{arguments}}

```

Invoke via JSON tool call:

```json
{
  "tool": "run_skill",
  "arguments": {
    "name": "quick-note",
    "arguments": "Remember to buy milk."
  }
}

```

The model receives the rendered template and can execute the instruction.

### Sub-Agent Skill Example

For isolated heavy computation, create `~/my-skills/research-paper.md`:

```markdown
---
description: Research a scientific paper
runAs: subagent
---
Search scholarly databases for recent papers about "{{arguments}}" and summarize the top three findings.

```

This spawns a temporary Reasonix session that performs the research and returns only the final summary to the parent context.

### CLI Discovery

To verify that your custom paths are correctly indexed, use:

```bash
reasonix skill list

```

This command displays all discovered skills, including those from custom `paths` defined in your TOML configuration.

## Summary

- **Custom skills** in Reasonix are markdown files stored as [`SKILL.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/SKILL.md) or `<name>.md` in configured directories.
- The **indexer** ([`internal/skill/index.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/index.go)) scans paths defined in the `[skills]` TOML block at session startup, mapping skill names to file locations without loading content into memory.
- **Lazy loading** occurs in [`internal/skill/tools.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/skill/tools.go) when `run_skill` or `read_skill` is invoked, reading the file from disk at execution time to support hot-reloading.
- **Execution models** differ by front-matter: inline skills return raw markdown immediately, while `runAs: subagent` spawns isolated sessions via `SubagentRunner`.
- **Dynamic installation** via `install_skill` updates the index through `InstalledHook`, enabling zero-downtime skill additions as implemented in the source code of esengine/DeepSeek-Reasonix.

## Frequently Asked Questions

### Where does Reasonix look for custom skills by default?

Reasonix automatically scans `.reasonix/skills` in the current project directory, plus `.agents/skills` and `.claude/skills` in the user's home directory. You can append additional roots via the `paths` array under the `[skills]` section in your TOML configuration file.

### Do I need to restart Reasonix after adding a new skill?

No. Because skills are loaded on-demand when `run_skill` is called, new files discovered by the indexer are available immediately on the next turn. If you install skills programmatically via `install_skill`, the `InstalledHook` callback refreshes the index instantly without requiring a process restart.

### What is the difference between `run_skill` and `read_skill`?

`run_skill` executes the skill—returning the body inline for standard skills or spawning a sub-agent when `runAs: subagent` is set—while `read_skill` performs a read-only fetch of the markdown body without triggering execution logic. Use `read_skill` to inspect skill contents before invocation or to retrieve templates without side effects.

### How do I prevent a skill from appearing in the system prompt?

Add the skill's identifier to the `disabled_skills` array in your `[skills]` configuration block. This excludes it from the Skills index block generated in [`internal/boot/boot.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/boot/boot.go) (lines 1518-1525) and prevents invocation via slash commands or the `run_skill` tool.