Glixo Builder Docs docs.glixo.dev

Agent extensions

These three contributes.* blocks let an extension add to what the agent itself can do: call a new tool, read a skill doc, or talk to an MCP server. All three require a matching capability.glixo.agent.*.register entry in the manifest's top-level requires[] — the C# validator (glixo-platform/src/Glixo.ServiceCatalog/ModuleManifestValidator.cs) rejects a manifest that declares the contribution without the capability.

Agent tool (contributes.tools)

What it is / when to use it. A model-invokable tool the agent can call during a run, backed by your extension's own logic (not a subprocess-per-call MCP server). Use it for a single well-scoped, host-mediated action — e.g. a read-only lookup — that should show up as one namespaced tool in the model's tool list.

Manifest fragment (from the developer example at glixo-community-modules/examples/code/memory-inspector/glixo.module.json):

"requires": [
  "ui",
  "capability.glixo.agent.tools.register",
  "capability.glixo.agent.skills.register",
  "capability.glixo.memory.read",
  "capability.glixo.memory.search"
],
"contributes": {
  "tools": [
    {
      "id": "glixo.memoryInspector.listSavedMemory",
      "name": "list_saved_memory",
      "title": "List saved memory",
      "description": "List or search everything the agent has saved to memory (workspace memory pack, per-repo run log, shared/vector memory, code_remember notes), with provenance. Read-only; secrets are never returned.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "Optional keyword/semantic search across all memory sources. Omit to list recent entries." },
          "source": { "type": "string", "enum": ["workspace_pack", "runs_log", "shared_memory", "code_note"], "description": "Restrict to a single source. Omit for all." },
          "scope": { "type": "string", "enum": ["user", "workspace", "project", "session"], "description": "Restrict to a scope." },
          "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Max entries (default 50)." }
        }
      },
      "permission": "read",
      "capability": "glixo.memory.search",
      "scopes": ["user", "workspace", "project", "session"]
    }
  ]
}

Required fields per the SDK type (glixo-sdk/packages/nodejs/src/extensionRegistry.ts:247-257, ExtensionToolContribution): name, title, description, inputSchema, permission (id, capability, scopes, timeoutSeconds optional). The doc-verified rule table in glixo-code/docs/current-state/03-module-manifest.md:50 additionally requires name to match ^[a-zA-Z0-9_-]{1,128}$ and be unique.

The code you write. This memory-inspector sample is a "client-bundled-in-app" placeholder module (entry.command: "echo") — the tool's actual handler logic ships inside the Glixo Code host build itself, keyed by the tool's name/capability, not as a separate process you write and ship. There is no separate handler source file in the sample; the manifest + inputSchema is the full public contract.

How the host consumes it. The host namespaces every declared tool as `ext__<sanitized-extension-id>__<toolName>` before exposing it to the model (namespacedToolName, glixo-code/sources/extensions/agentContributions.ts:89), so two extensions can't collide on a tool name.

Sample to study. Prefer the self-contained glixo-extensions-docs/samples/agent/agent-tool tutorial. The older host-backed Memory Inspector example lives under glixo-community-modules/examples/code/memory-inspector and is not a marketplace product.

Agent skill (contributes.skills)

What it is / when to use it. A Markdown doc with frontmatter that teaches the agent when and how to use something (a tool, an MCP server, a workflow) — it is not code, it's steering text injected into the agent's context. Use it alongside a tool or MCP server contribution to give the model usage guidance, or standalone to bias behavior for a scope.

Manifest fragment (from glixo-community-modules/catalog/code/gitnexus/glixo.module.json):

"requires": [
  "capability.glixo.agent.mcp.register",
  "capability.glixo.agent.skills.register"
],
"contributes": {
  "skills": [
    {
      "id": "glixo.gitnexus.skill",
      "title": "GitNexus",
      "description": "When and how to use the GitNexus MCP tools for repository graph questions.",
      "path": "skills/gitnexus",
      "scopes": ["workspace", "project", "session"],
      "capability": "glixo.gitnexus.skill"
    }
  ]
}

Required fields per ExtensionSkillContribution (glixo-sdk/packages/nodejs/src/extensionRegistry.ts:237-245): id, title, path (description, scopes, activation, capability optional). path points at a directory containing a SKILL.md.

The code you write. Not code — a SKILL.md with YAML frontmatter. GitNexus's actual file (glixo-community-modules/catalog/code/gitnexus/skills/gitnexus/SKILL.md):

---
name: gitnexus
description: Use when repository structure, symbols, call graphs, dependency impact, or blast radius matter and GitNexus MCP tools are available.
---

# GitNexus

Use GitNexus when the user asks questions that depend on indexed repository
structure rather than only literal text: ...

Prefer the `mcp__gitnexus__*` tools when they are connected. ...

The Memory Inspector example's skill additionally carries a metadata.extensionId / metadata.scopes block in its frontmatter (glixo-community-modules/examples/code/memory-inspector/skills/memory-inspector/SKILL.md) — frontmatter fields beyond name/description are informational, read by tooling/humans, not schema-enforced.

How the host consumes it. ExtensionRegistry.listSkills(scope) filters the registered skills[] contributions by scope for the current session — glixo-sdk/packages/nodejs/src/extensionRegistry.ts:956-959.

Sample to study. glixo-community-modules/catalog/code/gitnexus is a real product integration; glixo-extensions-docs/samples/agent/agent-skill is the isolated teaching sample. The host-backed Memory Inspector example is under glixo-community-modules/examples/code/memory-inspector.

MCP server (contributes.mcpServers)

What it is / when to use it. Registers a full Model Context Protocol server (stdio, http, or sse) that the host spawns/connects per session, exposing all of that server's own tools to the agent under one mcp__<id>__* prefix. Use this when you're wrapping an existing or third-party MCP server rather than writing a single host-mediated tool.

Manifest fragment (from glixo-community-modules/catalog/code/gitnexus/glixo.module.json):

"requires": [
  "capability.glixo.agent.mcp.register",
  "capability.glixo.agent.skills.register"
],
"contributes": {
  "mcpServers": [
    {
      "id": "gitnexus",
      "title": "GitNexus",
      "description": "Local GitNexus MCP server. Index each repository first with `npx gitnexus@1.6.5 analyze .` from the repository root.",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "gitnexus@1.6.5", "mcp"],
      "env": { "GITNEXUS_SKIP_OPTIONAL_GRAMMARS": "1" },
      "scopes": ["workspace", "project", "session"],
      "capability": "glixo.gitnexus.mcp"
    }
  ]
}

Required fields per ExtensionMcpServerContribution (glixo-sdk/packages/nodejs/src/extensionRegistry.ts:261-274): id, title, transport (stdio | http | sse), plus command for stdio or url for http/sse. Note: contributes.mcpServers is absent from glixo.module.schema.json entirely — it is validated only in C# (ModuleManifestValidator.ValidateMcpServers, glixo-platform/src/Glixo.ServiceCatalog/ModuleManifestValidator.cs:554-643), which also enforces id matches ^[a-zA-Z0-9_-]{1,128}$ and is unique, and cross-checks command/url against transport.

The code you write. None shipped in this repo — you point command/args at an existing MCP server binary (here, the published gitnexus npm package invoked via npx). If you're authoring your own MCP server, it just needs to speak MCP over the declared transport; nothing Glixo-specific is required in the server itself.

How the host consumes it. ExtensionRegistry.listMcpServers(scope) filters registered servers by scope (glixo-sdk/packages/nodejs/src/extensionRegistry.ts:966-969); the connected server's tools then surface to the model as mcp__gitnexus__*, per the sample's own README (glixo-community-modules/catalog/code/gitnexus/README.md:8-10).

Sample to study. glixo-community-modules/catalog/code/gitnexus (manifest at glixo-community-modules/catalog/code/gitnexus/glixo.module.json).