How to Configure Subagent Profiles for Different Task Types in Reasonix

Reasonix implements subagent profiles as specialized Skills with runAs: subagent, allowing you to configure isolated agents with distinct system prompts, models, and tool access through YAML files managed via the CLI.

The DeepSeek-Reasonix repository treats subagent profiles as first-class configuration objects that enable task-specific isolation. By configuring these profiles, you can dedicate specific models, effort levels, and tool permissions to distinct task types—such as code exploration, security review, or deployment workflows—ensuring each subagent operates within a tailored sandbox environment.

Understanding Subagent Profiles in Reasonix

In Reasonix, a subagent profile is technically a Skill with the runAs field explicitly set to subagent. When invoked, the profile's body serves as the system prompt for an isolated subagent runner. This architecture, implemented in internal/skill/profile.go (lines 52-63), validates that the profile meets specific criteria before execution: the runAs field must equal subagent, and the invocation field must be set to manual for user-created profiles.

The isolation model allows each profile to specify its own:

• Model selection (e.g., deepseek-pro)
• Effort level (e.g., max, normal)
• Tool permissions and constraints
• System prompt instructions

Creating and Managing Subagent Profiles via CLI

Creating a New Profile

Use the reasonix subagent create command to generate a new profile. According to internal/cli/subagent.go (line 209), this command writes a new skill file to ~/.reasonix/skills/<name>.yaml with the appropriate header structure.

reasonix subagent create delivery-only

This opens your default editor with a template containing the required YAML frontmatter:

---
description: Ship code to production
runAs: subagent
model: deepseek-pro
effort: max
invocation: manual
---
You are a deployment assistant. Follow the user's instructions to package
and ship the provided code. Do not modify files outside the /src directory.

The frontmatter fields control the subagent's execution environment, while the content below the dashes becomes the system prompt.

Editing and Deleting Profiles

To modify an existing profile, use the edit command which opens the skill file in your configured editor. Upon successful modification, the CLI confirms the update (as implemented in internal/cli/subagent.go at line 291).

reasonix subagent edit delivery-only

To remove a profile entirely, the delete command removes the underlying skill file (confirmed at line 334 of internal/cli/subagent.go):

reasonix subagent delete delivery-only

Configuring Profile Specifications

Each subagent profile supports several configuration fields in its YAML header:

• runAs: subagent – Required identifier distinguishing it from inline skills
• model – Overrides the default LLM (e.g., deepseek-pro, deepseek-chat)
• effort – Controls reasoning depth: max for complex analysis or normal for quick tasks
• invocation: manual – Required for profiles created through the CLI editor
• description – Human-readable summary for tool listings

The body text below the YAML frontmatter serves as the complete system prompt, allowing you to embed specific instructions, constraints, or persona definitions for the isolated agent.

Invoking Subagent Profiles

Run a configured profile using the --profile flag with the reasonix run command:

reasonix run --profile delivery-only "Deploy the latest version of the auth service to staging."

The tool resolver in internal/skill/tools.go performs validation before execution: it verifies the profile exists in the skill store, confirms runAs: subagent, and checks that invocation: manual is set (indicating creation via the profile editor). Once validated, Reasonix spawns the subagent with the configured model and effort level, passing the profile body as the system prompt.

Built-in Profile Wrappers

Reasonix ships with four built-in subagent profiles (explore, research, review, security_review) accessible via wrapper tools defined in internal/skill/tools.go under "BuiltinSubagentTools". These wrappers forward task descriptions directly to their respective profiles, allowing invocation from the CLI or from within other skills without explicit --profile flags.

Global Configuration and Concurrency Control

Configure default behaviors for all subagents in your global configuration file (typically reasonix.example.toml or ~/.reasonix/config.toml):

# Global default model for all sub-agents

subagent_model = "deepseek-pro"

# Per-skill model overrides

subagent_models = { review = "deepseek-pro", security_review = "deepseek-pro" }

# Concurrency limits

max_subagent_concurrency = 6

The max_subagent_concurrency setting controls how many subagents can run simultaneously. When tasks spawn multiple subagents—for example, during wide codebase searches—Reasonix respects this limit and organizes agents into fleets (managed in internal/agent/fleet.go). Each fleet can specify a profile name, allowing the same configuration to be reused across parallel subagents while maintaining consistent system prompts.

Summary

• Subagent profiles are specialized Skills stored in ~/.reasonix/skills/ with runAs: subagent and invocation: manual.
• Create, edit, and delete profiles using reasonix subagent <create|edit|delete> <name> commands implemented in internal/cli/subagent.go.
• Configure models, effort levels, and system prompts through YAML frontmatter in the skill file.
• Invoke profiles via reasonix run --profile <name> or use built-in wrappers for explore, research, review, and security_review.
• Control global defaults and concurrency limits in reasonix.example.toml using subagent_model, subagent_models, and max_subagent_concurrency.

Frequently Asked Questions

What is the difference between a subagent profile and a regular skill?

A subagent profile is a specific type of Skill where the runAs field is set to subagent and the invocation field is set to manual. While regular skills typically execute inline or as simple function calls, subagent profiles spawn isolated agents with their own system prompts, sandboxes, and resource limits. The profile body becomes the system prompt for the isolated runner, as validated in internal/skill/profile.go.

How do I set different models for different types of subagents?

You can specify models at three levels: per-profile using the model: field in the YAML frontmatter, globally via subagent_model in reasonix.example.toml, or per-skill using the subagent_models mapping (e.g., subagent_models = { review = "deepseek-pro", explore = "deepseek-chat" }). Profile-specific settings override global defaults.

Can I run multiple subagent profiles in parallel?

Yes, Reasonix supports concurrent subagent execution up to the max_subagent_concurrency limit defined in your configuration file. The fleet manager in internal/agent/fleet.go groups parallel subagents and can apply the same profile across multiple instances, ensuring consistent behavior while respecting resource constraints.

Where are subagent profiles stored on disk?

User-created subagent profiles are stored as YAML files in the ~/.reasonix/skills/ directory. Each profile is a standalone skill file that can be edited directly or managed through the reasonix subagent CLI commands, which handle file creation, validation, and deletion operations.

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