msd-core/docs/how-to/import-a-capability-from-a-url.md

How to import a capability from a URL

This guide is for MSD users who want to install a published capability — from a git repository, an npm package, a tarball, or a local path. It covers running the install command, understanding the pre-install summary, consenting to executable surfaces, verifying integrity, and choosing a scope.

Before installing a third-party capability, read Capability trust model to understand how MSD treats external code.

---

Run the install command

The install subcommand accepts several source spec forms. Use whichever matches how the capability was published.

Git repository at a tag:

msd capability install https://github.com/some-org/msd-cap-example.git#v1.0.0

Git repository pinned to a commit SHA (fully reproducible):

msd capability install https://github.com/some-org/msd-cap-example.git#sha:abc123def456...

npm package:

msd capability install npm:@some-org/msd-cap-example@1.0.0

Tarball at an HTTPS URL:

msd capability install https://example.com/releases/msd-cap-example-1.0.0.tgz

Local path (for testing a capability you are developing):

msd capability install ./path/to/capability

---

Read the pre-install summary

Before asking for confirmation, MSD fetches the manifest and displays a summary:

Capability:  Example Planning Step
Version:     1.0.0
Author:      Some Org <hello@some-org.example>
Homepage:    https://github.com/some-org/msd-cap-example
License:     MIT
engines.msd: >=1.6.0

Artefacts:   3 files (skills: 1, agents: 1, fragments: 1)

Executable surfaces:
  hooks:      plan:pre (step), ship:pre (gate, blocking)
  MCP servers: none
  command modules: none

If the capability declares hooks, MCP servers, or command modules, these are listed under Executable surfaces. These surfaces run as part of the MSD loop on your machine. Review them carefully.

---

Consent to executable surfaces

If the capability declares any executable surface — hooks, MCP servers, or command modules — MSD displays a consent prompt:

This capability registers executable hooks that will run during your MSD sessions.
Do you consent to installing it? [y/N]

If you do not trust the source, type N or press Enter to cancel. The capability will not be installed and nothing will be written to disk.

If the capability declares no executable surfaces (skills, agents, and prompt fragments only), MSD installs without a consent prompt.

After initial consent, if you later run msd capability update and the updated version adds new executable surfaces that were not present when you first consented, MSD will prompt for consent again before applying the update.

---

Verify integrity (recommended for tarballs)

If the capability author has published an sha512 integrity hash, pass it with --integrity to verify the download before extraction:

msd capability install https://example.com/releases/msd-cap-example-1.0.0.tgz \
  --integrity sha512-AbCdEf...

If the computed hash does not match the value you provide, MSD aborts the install. Nothing is written to disk. This protects against a tampered or corrupted download.

For Git and npm installs, the hosting platform provides its own transport-layer assurance. The --integrity flag is most important for tarball URLs hosted outside a verified registry.

---

Choose a scope

Use --scope project to install the capability for the current project only. The files land in .msd/capabilities/<id>/ relative to the project root, and the ledger entry goes into the project's local config.

msd capability install <spec> --scope project

Use --scope global (the default) to install for all your projects on this machine. The files land in ~/.msd/capabilities/<id>/ and the ledger is written per runtime (for example, ~/.claude/.msd-capabilities.json).

msd capability install <spec> --scope global

Project-scoped capabilities take precedence over global ones when both are present. Use project scope when the capability is specific to one codebase, or when you want to pin a version independently of your global install.

---

Handle a version mismatch

If the capability's engines.msd requirement is not satisfied by your installed MSD version, the install will be blocked:

Error: Capability requires msd >=1.7.0 but you have 1.6.2.

In this case, either upgrade MSD with msd update and retry, or ask the capability author whether an older compatible version is available. If the capability publishes compatVersions, MSD may offer to install the newest version compatible with your current MSD:

A compatible older version (0.9.0, requires msd >=1.6.0) is available.
Install that instead? [y/N]

---

Handle a blocked install (strictKnownRegistries)

If your organisation has set strictKnownRegistries to a non-empty allowlist in your MSD config, installs from sources outside that allowlist will be refused:

Error: Source is not in the known-registries allowlist. Contact your MSD administrator.

To install the capability, either ask your administrator to add the source to the allowlist, or install from an approved source.

---

Skip the confirmation prompt

If you are running in a script or CI context and have already inspected the manifest, pass --yes to proceed without interactive prompts. Use this only when you are certain about what you are installing.

msd capability install <spec> --yes

---

Confirm the installation

After a successful install, verify the capability is active:

msd capability list

The output shows each installed capability, its version, scope, and enabled status. If the capability did not activate as expected, check that your MSD version satisfies engines.msd and that the capability is not disabled.

---

A worked example: projects-sync

projects-sync is a reference third-party capability — it mirrors a project's .planning/ROADMAP.md to GitHub Issues, Milestones, and Projects v2. Install it the same way as any URL spec:

msd capability install https://github.com/The-Artificer-of-Ciphers-LLC/projects-sync-capability.git#v0.1.0 --scope project
msd-tools config-set projects-sync.enabled true   # opt-in, default off
msd-tools projects-sync status                     # dry run

It is a role: feature capability that registers an execute:pre step and a ship:post contribution (both onError: skip) and contributes the projects-sync command family — a concrete model for the manifest shape, hook registration, and command-router conventions described in Develop a capability.

---

Next steps

• Version and update a capability — check for updates with msd capability outdated and apply them with msd capability update.
• Remove a capability — uninstall with msd capability remove, including the --purge-data option.
• Capability trust model — the full explanation of how MSD handles trust for first-party and third-party capabilities.
• Capability manifest — field reference for capability.json.