What is a DSH plugin? 5 concepts before you install

dsh plugin means one thing: a code extension package — install it, and DSH gains a capability. Before installing anything, sort out five concepts — plugin, bundle, profile, plugin market and the dsh plugin command — because nearly every later confusion lives on the boundary between them.

DSH plugin concept one: a code package in its own layer from skills, models and MCP

A plugin is a code extension package, a skill is a loadable Markdown instruction set for the model, a model is the reasoning capability itself, and an MCP server is an external tool source — four different layers (source). Pin the division down with a table:

Work from the table:

1. Deciding which road adds a capability — code capability goes through plugins, teaching the model goes through skills, changing reasoning goes through model configuration, and external tools go through an MCP server. Expected: four separate entrances that never substitute for each other.
2. Confirming why plugins are the only installable form — only plugins are managed as install and uninstall units; the other three are configuration or files. Expected: every row in an installed list is a plugin.

For what a plugin is on its own, read what a DSH plugin is; for the whole landscape at once, read the plugin ecosystem.

DSH plugin concept two: a bundle is a preset combination of plugins

A bundle is a preset combination of plugins, listed in a profile's dsh.profile.bundles, resolving first from the dsh install directory and then from that profile's node_modules (source). Three things to fix in mind:

1. It is how several plugins ship as one unit — the official bundles cover different runtime shapes, such as a base combination and a web app combination. Expected: you never install that baseline plugin by plugin; starting a profile already brings it.
2. The resolution order is fixed — the dsh install directory first, the profile's own node_modules second. Expected: this is also why an out-of-tree plugin installed into the profile can be resolved at all.
3. Bundles are maintained upstream — whatever is listed in bundles is the default combination and is not something you installed. Expected: when tracing where a capability came from, check bundles before your own plugins.

DSH plugin concept three: a profile is a stacked runtime

A profile is not a pile of settings but a stacked runtime: bundle patches → that profile's cordis.patch.yml → the home-level patch → the --patch overlay, with later layers further out (source). Three consequences:

1. Each profile owns its plugin list and node_modules — so a plugin installed in web does not appear in headless. Expected: the two stay independent.
2. Some profiles initialise themselves — web, headless, sdk, sdk-minimal and acp initialise from shipped templates on first use. Expected: any other profile name has to be created through dsh plugin.
3. One plugin can behave differently per profile — because the patch layers and lists differ. Expected: when a plugin misbehaves, first confirm which profile you are in.

For a profile's directory contents and config file locations, see where the DSH config files are.

DSH plugin concepts four and five: the market and the dsh plugin command

The plugin market handles discovery and install, while dsh plugin --profile <name> <pnpm args> forwards those arguments to pnpm inside that profile directory — two roads landing in the same node_modules (source). Use them side by side:

1. When you want to browse first — go through the market's search and categories. Expected: descriptions, versions and stars are visible, which beats guessing package names at a prompt.
2. When you know what to install — run dsh plugin --profile <name> add <target>. Expected: the command runs inside the named profile, and the installed list shows the same result.
3. When you need to confirm which profile received it — read the --profile in the command, or check the installed list of the profile shown in the market UI. Expected: the two agree, so you never hit "installed but missing".
4. Remember three sentences — a plugin is a code package while a skill is instructions; bundles and patches decide what a profile contains; the market and the command are just two roads. Expected: those three cover most beginner confusion.

The plugin market is the graphical entry point for discovering and installing plugins, and DSH Plugin Hub folds search, categories, versions and updates into one page; for the command-line side, see the dsh plugin command guide.

DSH plugin caveats before you install

1. Never install a skill as a plugin: dsh plugin add only installs plugins, while skills are discovered by being dropped into a root directory.
2. Confirm the profile first: a plugin's install location, list entry and patch layers all belong to one profile, so installing into the wrong one looks like "nothing happened".
3. A bundle is not your plugin: bundles are maintained upstream, so keep them apart from what you installed when tracing a capability.
4. Watch the names: plugin names, package names and repository names all follow their own conventions, and grabbing the wrong one installs something else — see naming across the ecosystem first.
5. The market and the command share one source: both edit the same dependency list, so neither can install something twice.

Once the concepts are clear, the practical side is just two moves: pick plugins in the market and manage them in the installed list. DSH Plugin Hub holds both in a single interface.

Sources: dsh CLI README (official repository), Skills subsystem reference (official docs), dshplugin/dsh-plugin-hub