Customization
Skills, commands, plugins, hooks, MCP, and ACP — and the trust boundary that runs through all of them.
Harmony is extensible at several layers. Before the mechanics, the boundary:
SECURITY
Extension code is not sandboxed by default. Skills, plugins, extensions,
and hooks run with the privileges of the process that loads them. Installing
one is a decision to run someone else's code on your machine with your
credentials in scope. Treat it exactly as seriously as npm install of an
unfamiliar package.
The layers
| Layer | What it extends | Reach |
|---|---|---|
| Skill | What an agent can do | Invoked by an agent |
| Command | The composer | Typed by you |
| Prompt | Reusable instruction text | Content only |
| Extension / plugin | The application | Application privileges |
| Hook | Lifecycle events | Fires automatically |
| MCP | Tools Harmony publishes to other agents | Outbound |
| ACP | External harnesses Harmony drives | Outbound |
Direction matters
Two of these point outward and are commonly confused:
- MCP — Harmony acts as a server, publishing tools to hosts like Claude Code or Codex. Those agents call into your workspace.
- ACP — Harmony acts as a client, driving an external Agent Client Protocol harness. Harmony calls out.
See MCP.
Scope and precedence
Configuration can be defined at project scope or user scope. Project scope is discovered per repository root and is trust-gated — a project file does not silently gain the ability to run things because you opened the folder.
IMPORTANT
A repository is untrusted input. A project-scoped configuration file is content written by whoever wrote the repository, not by you.
Permission ceilings
An extension cannot grant itself more authority than the permission ceiling allows. Ceilings are how a skill that only needs to read files does not implicitly get the ability to run shell commands.
Where a gate exists for extension permissions, it applies at load time — which is why a newly installed extension may prompt before it is usable.
Safe mode
When something loaded at startup breaks the application, safe mode starts without optional extension code so you can remove the offender. Reach for it before deleting your configuration.
Failure isolation
A failing extension should degrade its own feature rather than take the application down. If a single extension can crash the app, that is a defect worth reporting, not expected behaviour.
What is not claimed
- Extension code is not sandboxed.
- A checksum or version pin proves which code you got, not that it is safe.
- Trust classes describe provenance, not intent.