# Apache Maka Skill Catalog Architecture and Skill Invocation Flow Explained

> Explore Apache Maka's dual-layer skill catalog architecture and understand its seven-step skill invocation flow, from token parsing to runtime dispatch. Learn how Maka manages and executes skills.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-08-27

---

**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/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/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/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/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/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/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/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/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/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:

```typescript
// 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/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/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/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.