Apache Maka Skill Catalog Architecture and Skill Invocation Flow Explained

Apache Maka implements a dual-layer skill catalog (bundled and managed) that exposes rich metadata through the SkillEntry interface, while skill invocation follows a strict seven-step pipeline from token parsing through runtime host dispatch.

Apache Maka treats skills as first-class, reusable capabilities that extend conversational AI through discoverable, sandboxed code. Understanding the skill catalog architecture and the precise skill invocation flow is essential for developers building custom automations or integrating with the Maka Marketplace. This article examines the TypeScript source code in the apache/maka repository to reveal how the system discovers, validates, and executes skills at runtime.

Skill Catalog Architecture

The catalog system separates available skills from installed skills through two distinct layers: the bundled (built-in) catalog and the managed (marketplace) catalog. Both feed into a unified workspace representation that the UI renders as interactive cards.

Bundled and Managed Catalog Layers

Bundled (built-in) catalog entries ship with the desktop client and describe skills that can be installed on demand. These entries are defined by the BundledSkillCatalogEntry interface in [module-panel-types.ts](https://github.com/apache/maka/blob/main/packages/ui/src/module-panel-types.ts#L40-L48).

Managed (marketplace) catalog entries populate from remote skill sources (e.g., the Maka Marketplace). They are grouped by taxonomy using ManagedSkillCategory and defined by ManagedSkillSourceEntry in [module-panel-types.ts](https://github.com/apache/maka/blob/main/packages/ui/src/module-panel-types.ts#L26-L33).

Installed Workspace Catalog and SkillEntry Metadata

Once a skill exists in a workspace (typically under a skills/<id> folder), it becomes a SkillEntry—the primary metadata contract consumed by the UI and runtime. This interface lives in [module-panel-types.ts](https://github.com/apache/maka/blob/main/packages/ui/src/module-panel-types.ts#L29-L63) and carries the following fields:

• sourceType — Indicates origin as workspace, bundled, managed, or unknown.
• declaredTools — Lists the tools the skill requests access to (e.g., file, network).
• validationStatus and managedUpdateStatus — Store static validation results and update availability.
• runtimeStatus — Tracks activation state (enabled, disabled, state_error).
• contextStatus — UI-level visibility state (advertised, invalid, shadowed).
• enabled and pinned — Boolean flags for user-controlled activation and pinning.
• needsReview — Flags whether the skill requires a security or metadata audit.

The UI layer (packages/ui) consumes these definitions to render the Skills pane, filter catalog views, and expose actions such as Install, Enable, Pin, and Update.

Skill Invocation Flow

When a user mentions a skill using tokens like /@<skill-name> or /skill:<name>, Maka executes a deterministic pipeline defined in [skill-invocation.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/skill-invocation.ts). The process converts raw text into sandboxed execution results through seven distinct phases.

1. Token Extraction

The parseSkillInvocationTokens function scans the user’s message for skill tokens and returns a list of SkillInvocationToken objects. This parsing logic resides at lines 103–110 of [skill-invocation.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/skill-invocation.ts#L103-L110).

2. Skill Resolution

resolveSkillInvocations receives the token list and maps each name to an InvocableSkillEntry—a thin wrapper around SkillEntry that includes a runtime-host reference. This function verifies that the skill is enabled and that requested tools are permitted in the current sandbox (lines 166–183).

3. Receipt Generation

For every token, the runtime generates a receipt object:

• loadedSkillInvocationReceipt — Successful load and validation.
• failedSkillInvocationReceipt — Validation failure or sandbox denial.
• overflowSkillInvocationReceipt — Triggered when requests exceed MAX_SKILL_INVOCATION_REQUESTS.

These receipt factories are implemented in [skill-invocation-receipt.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/skill-invocation-receipt.ts#L42-L117).

4. Message Composition

composeSkillInvocationMessage constructs a new user-visible message that strips the original skill tokens and embeds an array of loaded skill objects. This composed message is what the underlying model receives, allowing it to reference skill outputs (lines 315–326).

5. Preparation and Validation

prepareSkillInvocationMessage bundles the composed message with the receipt collection and performs final validation via validatedSkillInvocationResult. This step ensures all invocations are sanitized before leaving the renderer process (lines 259–285).

6. Runtime Host Dispatch

The prepared message crosses the IPC boundary to the runtime host (e.g., the desktop Node.js process). The host executes the skill code inside a sandbox, captures output, and returns a SkillInvocationResult. This dispatch coordination occurs in [message-coordinator.ts](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/message-coordinator.ts#L30-L38).

7. UI Feedback Rendering

The UI layer reads the SkillInvocationResult through the preload bridge and renders status indicators—such as success dots, error badges, or labels—using the logic in [skill-status.ts](https://github.com/apache/maka/blob/main/packages/ui/src/skill-status.ts#L55-L73). The feedback component [skill-invocation-feedback.tsx](https://github.com/apache/maka/blob/main/apps/desktop/src/renderer/skill-invocation-feedback.tsx) displays these results to the user.

End-to-End Implementation Example

The following TypeScript pseudo-code demonstrates the complete flow from user input to host dispatch:

// 1️⃣ Parse the user's text for skill tokens
const tokens = parseSkillInvocationTokens(userMessage);

// 2️⃣ Resolve each token to an invocable skill entry
const resolutions = await resolveSkillInvocations(
  source,     // WorkspaceSkillSource instance
  host,       // RuntimeHost reference for sandbox execution
  tokens.map(t => t.name)
);

// 3️⃣ Build the skill-invocation message (sent to the model)
const prepared = await prepareSkillInvocationMessage({
  text: userMessage,
  source,
  host,
  resolve: (req) => resolveSkillInvocations(source, host, req)
});

// 4️⃣ Dispatch to the runtime host (CLI or desktop shell)
await runtimeHost.send(prepared);

// 5️⃣ UI renders the result (success, error, or overflow)
renderSkillInvocationFeedback(prepared.skillInvocation);

Summary

• Dual-layer catalog: Maka separates bundled (client-shipped) and managed (marketplace) skill definitions, both converging on the SkillEntry metadata interface.
• Rich metadata: The SkillEntry type in [module-panel-types.ts](https://github.com/apache/maka/blob/main/packages/ui/src/module-panel-types.ts#L29-L63) exposes validation states, tool declarations, and user preferences that drive the Skills UI.
• Seven-step invocation: The pipeline moves from parseSkillInvocationTokens through resolution, receipt generation, message composition, preparation, runtime host dispatch, and final UI feedback.
• Sandboxed execution: Actual skill code runs inside the runtime host process, with results marshaled back to the renderer via SkillInvocationResult for safe UI rendering.

Frequently Asked Questions

What is the difference between bundled and managed skills in Maka?

Bundled skills ship with the Maka desktop client as offline-capable defaults defined by BundledSkillCatalogEntry. Managed skills originate from remote sources like the Maka Marketplace and are represented by ManagedSkillSourceEntry. Both types ultimately resolve to a local SkillEntry once installed in the workspace, but managed skills carry additional taxonomy metadata for categorization.

How does Maka handle skill invocation failures or sandbox denials?

During the resolution phase, resolveSkillInvocations validates sandbox permissions and skill state. If a skill fails validation or exceeds the limit defined by MAX_SKILL_INVOCATION_REQUESTS, the runtime generates a failedSkillInvocationReceipt or overflowSkillInvocationReceipt instead of loading the skill. These receipts propagate through prepareSkillInvocationMessage and render as error badges in the UI via [skill-status.ts](https://github.com/apache/maka/blob/main/packages/ui/src/skill-status.ts#L55-L73).

What metadata does the SkillEntry interface expose for UI rendering?

SkillEntry exposes runtimeStatus (enabled/disabled/error), contextStatus (advertised/invalid/shadowed), declaredTools for security transparency, and boolean flags like enabled, pinned, and needsReview. The UI layer uses these fields to display install buttons, toggle switches, security warnings, and update indicators without executing skill code.

Where does the actual skill code execution happen in the architecture?

Execution occurs in the runtime host (the main Node.js process), not the renderer. The prepareSkillInvocationMessage function sends the validated invocation request across the IPC bridge to [message-coordinator.ts](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/message-coordinator.ts#L30-L38) in the runtime host package. The host loads the skill from the workspace folder, runs it inside a sandbox, and returns a SkillInvocationResult that the renderer consumes for display.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}