PKUfudawei/dsh-capability-menu

Table of Contents

• Capability Overview
  • Capability Model
  • Capability Menu
• Installation and Uninstallation
  • Install from npm (recommended)
  • Install from source
  • Verify the install
  • Uninstall
• Exposure Policy
  • Tools and Skills three-tier exposure and execution
• Configuration
  • All configuration options
  • On-demand search catalog (catalogFile)

---

Capability Overview

• Builds a unified capability catalog (ctx.capability) for DeepSeek Harness tools (including MCP and built-in tools) and skills.
• Provides three policy tiers — Resident / On-demand / Disabled — to manage capability exposure and invocation.
• Supplies on-demand capabilities only when needed, reducing the tool definitions sent with each request and saving tokens and context.

Capability Model

Capability is the umbrella concept introduced by this plugin: a Tool and a Skill are different kinds of capability.

kind	provides to the agent	action	notes
tool	executes an action (an MCP tool or a harness-native built-in tool)	execute	indexed by ctx.tools
skill	the method / flow / knowledge for a class of tasks	load	indexed by ctx.skills

The model gets two meta tools:

tool	role	corresponding entry
meta_search	Search capabilities visible to the current session; list mode supports offset pagination and reports total, returned, and has-more values; detail returns descriptions and tool schemas	@daweifu/capability-menu/search
meta_invoke	Unified execution surface for Tools and Skills; pass force: true to reload updated Skill instructions	@daweifu/capability-menu/invoke

Capability Menu

After installation, open Settings and select Capability Menu from the settings navigation to manage Tools and Skills.

Task	How to do it
Change a tier	Click the dot beside a capability. Click a tier count at the top to change the whole group.
Find a capability	Use the filter below the tabs to search by name or group. Regex is supported and matching is case-insensitive.
View details	Click a Tool to see its definition. Click a Skill to expand its files and preview them; content is rendered as Markdown.
Register a capability	Click Register in the top right to add an MCP server or Skill directory; Skills accept local paths or public GitHub URLs.
Edit or remove	Click Edit on a server group in Tools or a Skill row in Skills.
View rules and catalog	Click Policy & catalog on the right side of the page header. The catalog tab also sets the search description limit.
Edit search description	Set a Tool or Skill to On-demand, then click Search description beside it to edit a short version of the provider description.

MCP tool rows omit the repeated mcp__server__ display prefix inside their server group. Hover to see the full name; search and invocation still use the full ID.

Registering an MCP server writes its patch configuration; a missing file or parent directory is created automatically. MCP credentials such as request headers are stored in the config; keep it secure. Skill registration creates a link or imports a directory into the selected skill root.

GitHub Skill imports accept a default-branch root URL (the root must contain SKILL.md), a specific branch root https://github.com/{owner}/{repo}/tree/{branch}, or a Skill subdirectory https://github.com/{owner}/{repo}/tree/{branch}/{skill-directory}. Local paths are also supported. Only public repositories are supported; Git must be installed on the machine running dsh. The plugin validates SKILL.md and copies only the selected directory.

Installation and Uninstallation

Prerequisites: Node.js and the dsh CLI. Installing from npm needs no separate pnpm install; installing from source requires pnpm.

Install from npm (recommended)

Install it in the Web profile:

dsh plugin --profile web add @daweifu/capability-menu

Install from source

git clone https://github.com/PKUfudawei/dsh-capability-menu.git
cd dsh-capability-menu
pnpm install                   # the prepare script builds lib/ (server) and lib/client.js (front-end)

dsh plugin --profile web add .

Verify the install

cd "${DSH_HOME:-$HOME/.dsh}/profiles/web" && pnpm list @daweifu/capability-menu && dsh --profile web --dump-config | grep -m1 '== @daweifu/capability-menu'

Uninstall

dsh plugin --profile web remove @daweifu/capability-menu

Exposure Policy

All capabilities (Tool and Skill) fall into three tiers by their exposure level (what the model sees in the context) and their execution mode:

Tools and Skills three-tier exposure and execution

tier	capability	what the model sees	how to find it	how to use it
Resident	tool	Tool definition is included with every request	No search needed	Call directly; it goes through the full ctx.tools pipeline
	skill	Name and summary appear in <available_skills>	No search needed	The skill tool loads the content when needed
On-demand	tool	Tool definition is not included with requests	Search candidates with meta_search or search the capability catalog YAML (catalogFile)	Inspect parameters by exact ID, then call with meta_invoke
	skill	Not shown in <available_skills>	Search with meta_search or search the capability catalog YAML (catalogFile)	Load SKILL.md with meta_invoke
Disabled	tool	Tool definition is not included with requests	Hidden from search results and the capability catalog	Calls are rejected
	skill	Not shown in <available_skills>	Hidden from search results and the capability catalog	Loads are rejected

Scope & reserved tools:

• Tiers apply to MCP and harness-native built-in tools; built-ins use the reserved built-in group. Do not name an MCP server built-in.
• meta_search and meta_invoke are always Resident and cannot be disabled. run_code is reserved for Code Mode; it is excluded from the catalog and menu and needs no tier rule.
• Keep high-frequency core tools Resident: For an On-demand built-in, find its ID with meta_search({query}), inspect the exact-ID schema, then call meta_invoke.

Configuration

Hand-written rules belong under config in the capability-menu-policy entry. This is a config fragment; see cordis.patch.yml for the complete installation patch.

• The default patch is ${DSH_HOME:-~/.dsh}/cordis.patch.yml. A profile can override the entry in its own patch.
• Tier changes in Capability Menu apply immediately and are written to a separate stateFile about 1.5 seconds after input stops. These writes do not reload the plugin. Patch rules remain the base; UI choices override exact rules for the same capability, while Disabled wildcards still take priority.
• By default, stateFile sits beside patchFile, so profiles share UI choices. Set a different stateFile per profile to isolate them. To clear UI choices, stop DSH and delete the state file; patch rules remain in effect.

config:
  tools:
    on-demand: # On-demand
      - 'mcp__example__*'    # tools from one MCP server
    disabled: # Disabled
      - 'mcp__secret__*'
  skills:
    on-demand: # On-demand
      - example_skill        # unlisted capabilities default to Resident

All configuration options

Option	Entry	Default	Description
tools / skills / metaTools	capability-menu-policy	see bundled patch	Base tier rules in the patch; UI moves are saved separately
catalogFile	capability-menu-registry	${DSH_HOME:-~/.dsh}/capability-catalog.yaml	Materialized on-demand catalog path; empty disables it
searchMetadataFile	capability-menu-registry	${DSH_HOME:-~/.dsh}/capability-menu-search-metadata.json	Saved search descriptions and UI limit setting; empty prevents saving changes
summaryMaxChars	capability-menu-registry	320	Initial character limit for search descriptions, meta_search list summaries, and catalog descriptions; minimum 20; a UI-saved value takes precedence
refreshDebounceMs	capability-menu-registry	200	Debounce window (ms) for change-event rebuilds; 0 disables debouncing
patchFile	capability-menu-policy	~/.dsh/cordis.patch.yml ($DSH_HOME wins)	Patch file that MCP server registration writes to
stateFile	capability-menu-policy	capability-menu-policy.json beside patchFile	UI tier state; set to an empty string to disable persistence
skillsDir	capability-menu-policy	~/.dsh/skills	Skill root used by skill directory registration
persistDebounceMs	capability-menu-policy	1500	Debounce window (ms) before a clicked tier change is written to the state file

These settings belong to their respective plugin entries and usually live in the same cordis.patch.yml. The plugin creates stateFile and searchMetadataFile automatically. catalogFile is the generated catalog for model-side search, while skillsDir is a directory for Skills.

Rule priority (evaluated in order: Disabled always wins; between Resident and On-demand, exact rules beat wildcards):

priority	rule	example	effect
1	disabled exact	disabled: [forbidden_skill]	hardest deny, overrides everything
2	disabled wildcard	disabled: ['mcp__secret__*']	block a whole group
3	resident exact	resident: [bash]	keep one capability resident
4	on-demand exact	on-demand: [example_skill]	one capability on-demand (what a Capability Menu click writes)
5	resident wildcard	resident: ['mcp__gongfeng__*']	keep a whole group resident
6	on-demand wildcard	on-demand: ['mcp__*']	bulk on-demand fallback
default	no rule matched	—	resident

If a higher-priority rule overrides a selected tier, the UI reports that the classification did not apply.

On-demand search catalog (catalogFile)

The plugin writes On-demand Tools and Skills to a YAML search catalog. Resident and Disabled capabilities are excluded.

• Catalog file: Defaults to ${DSH_HOME:-~/.dsh}/capability-catalog.yaml; with no On-demand capabilities it contains capabilities: []. Set catalogFile: '' to disable generation. It updates when capabilities, tiers, or search descriptions change, so do not edit the generated file directly.
• Search description: An On-demand row opens an editor prefilled with the provider description shortened to summaryMaxChars characters (320 by default, preferring word or punctuation boundaries). Edits affect meta_search lists and keyword matching and are written to the catalog; the provider definition and exact detail stay unchanged. Restore resets the field, and Save applies it.
• Description limit: Set it in Policy & catalog → On-demand search catalog (minimum 20). The saved value in searchMetadataFile takes priority over summaryMaxChars in the patch. Shorten any custom descriptions above a proposed lower limit before saving.
• Search and invoke: Find a candidate with meta_search({query}) or a catalog id, inspect the full parameter schema with meta_search({id, kind}), then call or load it with meta_invoke({id, kind, args}). The catalog contains search summaries, not parameter schemas. If the model can read the catalog path, it can also search the file with grep / read. meta_search returns 20 entries per page by default (50 maximum); the next offset is the current offset + returned. A Skill must be registered in ctx.skills; pass force: true to reload one already read in this session.

Generated file example:

capabilities:
  - id: mcp__km__search
    kind: tool
    description: Search the knowledge base
    server: km
  - id: example_skill
    kind: skill
    description: A low-frequency skill for analyzing logs
    whenToUse: Use when investigating log issues

License

This project is licensed under the Apache License 2.0.