Overview

The core philosophy of DeepSeek Harness (DSH) is “everything is a plugin”. When building complex workflows, managing multiple subagents’ role definitions, tool permissions, and invocation budgets often requires hard-coded configuration. dsh-plugin-subagent-roles solves this problem by allowing subagent roles to be defined through the file system.

Plugin Introduction

This is a DSH plugin maintained by user troytse. It defines subagent roles as Markdown files and configures them using YAML front matter. The plugin supports project-level and global-level directory storage, provides tool filtering policies and tool invocation budget limits, and registers a delegation tool for invocation.

Core Features

  • File-based definitions: Define roles via Markdown files, including YAML front matter and role persona body.
  • Multi-level storage: Support storing role files in the project directory .dsh/roles/ and the global directory ~/.dsh/roles/.
  • Routing and configuration: Configure display name, routing description, and LLM routing (provider/model) in the YAML front matter.
  • Permissions and budget: Provide tool filtering policies and tool invocation budget limits, and strictly reject unknown front-matter keys.
  • Directory display: Register a delegation tool and display the role directory.

Installation and Enabling

Before installing, ensure the environment meets the dependency requirements: Node.js 20 or later, and @deepseek-ai/dsh-tools and @deepseek-ai/dsh-subagent provided by DSH.

In CLI mode (for example dsh web), run the following command:

dsh plugin --profile web add dsh-plugin-subagent-roles

After installation, restart the corresponding Profile (for example dsh web).

Typical Usage

1. Create a Role File

Create a role file in the project root or global directory. The file name must be kebab-case. The file format is YAML front matter followed by a Markdown body.

Example: .dsh/roles/code-reviewer.md

---
displayName: Code Reviewer
description: Reviews a diff for correctness, security, and missing tests, and reports findings by severity.
provider: deepseek-official
model: deepseek-v4-flash
reasoningEffort: low
tools: [read, grep, glob]
---
You are a code reviewer. Read the diff before judging it, separate blocking
issues from suggestions, and cite file and line for every finding.

2. Invoke a Role

You can trigger a subagent by tool call or by natural language instruction.

  • By tool call:
subagent_role({ role: "code-reviewer", prompt: "Review the staged diff.", description: "review staged diff" })
  • By natural language instruction:
have the code-reviewer role review this diff

Notes

  • Version limitations: maxToolCalls related features require plugin version >= 0.4.0. In older versions, this feature is unavailable.
  • Configuration changes: Version 0.2.0 removed the settings namespace registered by the plugin; configuration options are set by overriding lines in cordis.patch.yml.
  • File naming: Role file names must be kebab-case.
  • Key name strictness: The plugin strictly rejects unknown front-matter keys, preventing tool permissions from being unexpectedly expanded due to configuration errors.
  • Dependencies: The plugin depends on @deepseek-ai/dsh-tools and @deepseek-ai/dsh-subagent.

Summary

dsh-plugin-subagent-roles provides DSH with a structured, version-controllable way to manage subagents. Through the file system, developers can clearly define the behavior, permissions, and resource limits of different roles, making it suitable for scenarios that require fine-grained management of multi-agent collaboration.

  • Directory page: https://www.skillhub.cn/plugins/troytse/dsh-plugin-subagent-roles
  • GitHub: https://github.com/troytse/dsh-plugin-subagent-roles