How to Set Up Custom Skills in DeepSeek-Reasonix Using `paths` and `excluded_paths`

Configure custom skills in DeepSeek-Reasonix by editing the [skills] section in reasonix.toml, using paths to add skill directories and excluded_paths to hide default locations without deleting them.

DeepSeek-Reasonix discovers playable skills (playbooks) by scanning designated directories called skill roots. To customize which skills are available to the model, you edit the [skills] configuration block in your reasonix.toml file, specifying additional search paths and excluding unwanted default directories.

Understanding the [skills] Configuration Section

The [skills] section controls where Reasonix looks for skill definitions. A valid skill is any folder containing a SKILL.md file with proper front-matter. The configuration supports two primary mechanisms for controlling the scan: paths for inclusion and excluded_paths for exclusion.

Adding Skill Roots with paths

The paths array appends directories to the skill discovery list. When Reasonix initializes, it scans these locations (plus defaults) for valid SKILL.md files. Paths support tilde expansion (~/) for the user home directory and relative paths from the configuration file location.

Hiding Directories with excluded_paths

The excluded_paths array prevents specific directories from being scanned, even if they exist in the default convention hierarchy. This lets you suppress built-in or global skill roots without physically removing the folders from your system.

Editing the Configuration File

Locate the user-editable configuration at the repository root (reasonix.toml) or inside a project-specific .reasonix/reasonix.toml. According to the source code in internal/config/render.go (lines 425-434), the [skills] block is only written to the file when you supply values; otherwise, the renderer outputs commented examples.

Add your custom configuration under the [skills] header:

[skills]
paths = ["~/my-skills", "../shared/skills"]
excluded_paths = ["~/.agents/skills"]

After saving, restart Reasonix or reload the configuration to apply the new skill roots.

Practical Configuration Examples

Example 1: Custom Skill Roots and Excluded Defaults

This configuration adds two custom directories while hiding the conventional ~/.agents/skills location:

# reasonix.toml

[skills]
paths = ["~/my-skills", "../shared/skills"]
excluded_paths = ["~/.agents/skills"]

Example 2: Advanced Skill Management

For fine-grained control, combine path management with depth limits and specific skill blacklisting:

[skills]
paths = ["~/my-skills", "../shared/skills"]
excluded_paths = ["~/.agents/skills"]
max_depth = 3
disabled_skills = ["review"]

The max_depth parameter limits how many directory levels deep Reasonix searches (default is 3), while disabled_skills hides specific skill names from the prompt and slash invocation without removing their files.

Registering Skills via Command Line

You can register a skill root without manually editing TOML by using the install_source tool implemented in internal/installsource/install_source.go (lines 38-41). This command adds the directory to [skills].paths automatically:

reasonix install_source --op=install --source=/path/to/my-skill \
  --mode=register --scope=project

The --mode=register option updates the configuration file for you, making the skill available immediately after the command completes.

Scope Hierarchy and Discovery Behavior

DeepSeek-Reasonix evaluates skills using a layered scope system:

• Project-level roots (defined in ./.reasonix/reasonix.toml or ./reasonix.toml) override global roots
• Global roots are conventionally scanned from ~/.reasonix/skills, ~/.agents/skills, and similar standard locations
• Discovery depth defaults to three levels; subdirectories beyond this depth are ignored unless you increase max_depth

When multiple roots contain skills with identical names, project-level definitions take precedence over global ones.

Summary

• Edit reasonix.toml and add the [skills] section to enable custom configuration
• Use paths to append directories containing SKILL.md files to the discovery list
• Use excluded_paths to suppress default directories like ~/.agents/skills without deleting them
• Adjust max_depth to control how many subdirectory levels Reasonix scans (default: 3)
• Use disabled_skills to hide specific skill names from the model's available tools
• Apply changes by restarting Reasonix or reloading the configuration file

Frequently Asked Questions

Where does DeepSeek-Reasonix look for skills by default?

By default, Reasonix scans conventional global directories including ~/.reasonix/skills and ~/.agents/skills. It also checks the project-level configuration file for additional roots defined in [skills].paths.

How do I disable specific skills without removing the files?

Add the skill name to the disabled_skills array in the [skills] section. For example, disabled_skills = ["review"] prevents the "review" skill from appearing in prompts and slash commands while keeping the source files intact.

Can I use relative paths in the paths array?

Yes. Paths in paths and excluded_paths support relative references resolved from the configuration file's location, as well as absolute paths and tilde expansion for the home directory.

How do I apply configuration changes after editing the file?

Restart the Reasonix process or trigger a configuration reload. The engine reads reasonix.toml at startup; changes to skill roots are not picked up dynamically while the process is running.

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