# `Minga.Extension.Agent`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga/extension/agent.ex#L1)

Agent surface for Minga extensions.

This module provides the DSL macros and compile-time wiring for agent-specific extension components: hooks, skills, MCP servers, slash commands, and semantic UI contributions.

`use Minga.Extension.Agent` is the recommended way to define an extension that contributes agent-side features. It injects the `Minga.Extension` behaviour, registers compile-time accumulate attributes for each agent component, provides a default `child_spec/1`, and imports the agent DSL macros.

Agent extensions can also declare config options with `option/3`, just like editor extensions.

## Types

Hook specs are `{event, opts}` tuples where `event` is an atom like `:pre_tool_use` or `:session_start` and `opts` is a keyword list with keys like `:tool`, `:command`, etc.

Skill specs are path strings pointing to a skill directory on disk.

MCP server specs are `{name, opts}` tuples where `name` is an atom or string identifier and `opts` is a keyword list with keys like `:command` and `:args`.

Slash command specs are `{name, description, opts}` tuples where `name` is an atom or string, `description` is a human-readable string, and `opts` is a keyword list with keys like `:command`.

Agent UI specs are maps or keyword lists that already contain semantic render-model values. The semantic UI registry validates that payloads are existing `Minga.RenderModel.UI.*` values before render builders read them.

## Usage

    defmodule MingaLint do
      use Minga.Extension.Agent

      option :auto_fix, :boolean,
        default: false,
        description: "Automatically apply lint fixes"

      hook :pre_tool_use, tool: "write_*", command: "hooks/lint.sh"
      hook :session_start, command: "hooks/hello.sh"

      skill "skills/greet"

      mcp_server :my_mcp, command: "servers/my-mcp", args: ["--port", "3000"]

      slash_command :my_cmd, "Runs my custom command", command: "commands/my-cmd.sh"

      agent_ui id: "status", surface: :panel, payload: %Minga.RenderModel.UI.ExtensionPanel.Panel{...}

      @impl true
      def name, do: :minga_lint

      @impl true
      def description, do: "Linting hooks for agent sessions"

      @impl true
      def version, do: "0.1.0"

      @impl true
      def init(_config), do: {:ok, %{}}
    end

For extensions that contribute editor-side components (commands, keybindings, modeline segments, capabilities), see `Minga.Extension.Editor`.

# `__using__`
*macro* 

Injects the `Minga.Extension` behaviour, agent DSL macros, and a default `child_spec/1`.

The injected macros are: `option/3`, `hook/2`, `skill/1`, `mcp_server/2`, `slash_command/3`, and `agent_ui/1`.

At compile time, each macro accumulates declarations into module attributes. The `__before_compile__` hook then generates `__option_schema__/0`, `__hook_schema__/0`, `__skill_schema__/0`, `__mcp_server_schema__/0`, `__slash_command_schema__/0`, and `__agent_ui_schema__/0` functions that the framework reads at load time.

# `agent_ui`
*macro* 

Declares a semantic agent UI contribution.

The payload must be an existing render-model value accepted by `MingaEditor.Agent.SemanticUI.Entry`, such as an agent chat message body, extension-panel content, or an extension-panel panel.

## Examples

    agent_ui id: "status", surface: :panel, payload: %Minga.RenderModel.UI.ExtensionPanel.Panel{...}
    agent_ui id: "note", surface: :transcript_enrichment, payload: {:system, "Ready", :info}

# `hook`
*macro* 

Declares a lifecycle hook this extension provides.

Hooks fire at specific agent lifecycle events and can run shell commands or invoke functions.

Accumulated at compile time and exposed via `__hook_schema__/0`.

## Options

- `:command` (required) -- path to the script or executable to run
- `:tool` -- glob pattern to match tool names (only for tool-related events)

## Examples

    hook :pre_tool_use, tool: "write_*", command: "hooks/lint.sh"
    hook :session_start, command: "hooks/hello.sh"

# `mcp_server`
*macro* 

Declares an MCP server this extension provides.

MCP (Model Context Protocol) servers expose tools and resources to the agent through a standardized protocol.

Accumulated at compile time and exposed via `__mcp_server_schema__/0`.

## Options

- `:command` (required) -- path to the server executable
- `:args` -- list of command-line arguments (default: `[]`)

## Examples

    mcp_server :my_mcp, command: "servers/my-mcp", args: ["--port", "3000"]
    mcp_server :db_tools, command: "servers/db-tools"

# `skill`
*macro* 

Declares a skill directory this extension provides.

Skills are directories containing agent instructions, prompts, and tool definitions that extend the agent's capabilities.

Accumulated at compile time and exposed via `__skill_schema__/0`.

## Examples

    skill "skills/greet"
    skill "skills/refactor"

# `slash_command`
*macro* 

Declares a slash command this extension provides.

Slash commands are user-invokable agent commands prefixed with `/` in chat interfaces.

Accumulated at compile time and exposed via `__slash_command_schema__/0`.

## Options

- `:command` (required) -- path to the script or executable to run

## Examples

    slash_command :my_cmd, "Runs my custom command", command: "commands/my-cmd.sh"
    slash_command :deploy, "Deploy the current branch", command: "commands/deploy.sh"

---

*Consult [api-reference.md](api-reference.md) for complete listing*