How Extensions Are Loaded

When a project overrides a global extension of the same name, where each kind of extension is read from, and the two distinct paths that decide when a change takes effect.

  • Skills: the current project's <project>/.klaus/skills is read first, then ~/.klaus/skills. The first match wins, so a skill in the project shadows the global one with the same name. Built-in skills fill in only where the name is still free.
  • Sub-agents: ~/.klaus/agents/*.md.
  • Slash commands: global ~/.klaus/commands, project <project>/.klaus/commands.
  • Output styles: global ~/.klaus/output-styles, then .klaus/output-styles at each directory level walking up from the session's working directory (stopping at the repository boundary). Later matches override earlier ones.
  • Hooks: global ~/.klaus/hooks.json, project <project>/.klaus/hooks.json. Each declared hook must first be trusted in Settings before it is injected into a session — see Hooks.
  • Plugins: loaded by the engine itself from the plugin ledger in its own configuration — see Plugins. Skills, commands, sub-agents, MCP servers, and hooks that ship inside a plugin carry a source tag, so they never appear twice alongside the categories above. Enabling or disabling a plugin is application-wide; there is no project scope for plugins.

When a change takes effect

There are two distinct paths here, and mixing them up produces the wrong answer:

  • Changed in the app (installing a skill from the marketplace, enabling or disabling a plugin, tapping trust on the Hooks page): the client knows the setting changed, marks open sessions as having stale configuration, and rebuilds them automatically between turns with the new values. You do not need to reopen the session, let alone restart the app. This is especially true for plugins — installing, enabling, and disabling all take effect without a restart.
  • Edited on disk by hand (changing hooks.json in your editor, dropping a directory into .klaus/skills): Klaus does not watch these directories, so nothing tells it about your change. This content is read when a session starts, so you need to open a new session for the change to apply.

So "open a new session after installing a skill" is only true for the second case. Anything you install through the UI is picked up on the next turn.