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

Custom skills in Reasonix are reusable markdown playbooks that are discovered via configured filesystem roots, indexed at session startup in 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 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, 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 (or reasonix.example.toml) controls which directories are scanned:

[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, lines 19-27) recursively scans configured paths for files named 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, 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, 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:

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

Invoke via JSON tool call:

{
  "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:

---
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:

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 or <name>.md in configured directories.
• The indexer (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 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 (lines 1518-1525) and prevents invocation via slash commands or the run_skill tool.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}