# How to Extend Maka's Capabilities Using the Skills System

> Learn how to extend Maka's capabilities by creating a SKILL.md file. Regenerate the catalog and let Maka automatically load new skills at runtime for enhanced functionality.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-08-22

---

**Extending Maka's capabilities requires creating a declarative [`SKILL.md`](https://github.com/apache/maka/blob/main/SKILL.md) file in the bundled-skills directory, regenerating the catalog with `scripts/gen-bundled-skill-catalog.mjs`, and allowing the SkillManager to automatically load the new capability at runtime.**

The Apache Maka project provides a modular architecture for AI agent capabilities through its self-describing skills system. Developers can extend Maka's capabilities using the skills system by authoring markdown-based skill definitions that declare tool dependencies and execution workflows without modifying core runtime code. This design keeps the system modular while allowing infinite growth through simple configuration files.

## What Are Maka Skills?

Maka skills are **self-describing units** that tell the runtime which tools a model may invoke and how to invoke them. Each skill consists of a [`SKILL.md`](https://github.com/apache/maka/blob/main/SKILL.md) file containing YAML frontmatter that specifies the skill name, description, category, and tool requirements, followed by human-readable instructions that guide the model's execution flow. According to the apache/maka source code, these definitions live in `packages/runtime/resources/bundled-skills/` and serve as the single source of truth for the skill catalog.

The runtime consumes these definitions through a generated TypeScript catalog rather than scanning the filesystem at runtime, ensuring fast and reproducible skill discovery.

## Step-by-Step Guide to Adding a New Skill

### Create a Skill Definition

Begin by adding a new folder under `packages/runtime/resources/bundled-skills/` and placing a [`SKILL.md`](https://github.com/apache/maka/blob/main/SKILL.md) file inside it. This markdown file must include frontmatter declaring the skill metadata and a workflow section describing the execution steps.

The frontmatter supports these key fields:

- **`allowed-tools`**: Tools the model may request without explicit loading
- **`required-tools`**: Tools that must be loaded first via `load_tools` before execution
- **`category`**: Classification for UI organization (e.g., "效率工具")

Reference the existing [`packages/runtime/resources/bundled-skills/computer-use/SKILL.md`](https://github.com/apache/maka/blob/main/packages/runtime/resources/bundled-skills/computer-use/SKILL.md) for the canonical structure used by built-in capabilities.

### Generate the Bundled-Skill Catalog

After authoring the skill definition, run the generation script to validate and compile the catalog:

```bash
npm run generate:bundled-skills

```

This command executes `scripts/gen-bundled-skill-catalog.mjs`, which reads every [`SKILL.md`](https://github.com/apache/maka/blob/main/SKILL.md) in the bundled-skills directory, validates the frontmatter, computes a SHA-256 digest of the content for integrity verification, and emits [`packages/runtime/src/bundled-skill-catalog.generated.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/bundled-skill-catalog.generated.ts). This generated file maps skill IDs to their complete definitions as a deterministic TypeScript object.

### Bundle the Catalog into the Runtime

The generated TypeScript module is compiled into the `packages/runtime` npm package. At startup, the **SkillManager** loads this catalog and registers each entry, creating `SkillEntry` objects that expose properties including `id`, `name`, `description`, `category`, `requiredTools`, `allowedTools`, and status flags like `enabled`, `pinned`, and `managedUpdateStatus`.

Because the catalog is generated at build time, the runtime serves skills without filesystem scans, keeping skill discovery fast and reproducible.

### Expose UI Hooks

The UI layer consumes the catalog through the runtime's public API. The [`packages/ui/src/skills-panel.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/skills-panel.tsx) component calls `getSkillsCopy()` to retrieve the latest catalog and renders each skill entry with actions including **install**, **enable/disable**, **preview update**, and **delete**. The companion [`packages/ui/src/skill-status.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/skill-status.tsx) file provides visual indicators for diagnostic flags such as "shadowed skill" and "update available", while [`packages/ui/src/skills-copy.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/skills-copy.ts) handles safe cloning of the catalog for UI consumption.

### Consume the Skill

Once registered, application code or model prompts can invoke the skill using the command syntax `/skill:<skill-name>`. The runtime resolves the skill ID through `runSkillAction`, ensures required tools are loaded via `load_tools` if necessary, and executes the prescribed workflow steps.

## Skill Metadata and Configuration

The [`SKILL.md`](https://github.com/apache/maka/blob/main/SKILL.md) frontmatter establishes a declarative contract between the skill author and the runtime. When a model emits `/skill:computer-use`, the runtime checks the `required-tools` list (e.g., `maka_computer`) and automatically loads them before observing windows and executing click actions.

This metadata-driven approach ensures that the model cannot invoke tools that haven't been explicitly declared, maintaining security boundaries while providing clear instruction sets for complex automation tasks.

## Code Example: Creating a Custom Notes Editor Skill

Here is a complete example of adding a new capability that edits notes using the computer automation tool.

First, create the skill definition at [`packages/runtime/resources/bundled-skills/notes-editor/SKILL.md`](https://github.com/apache/maka/blob/main/packages/runtime/resources/bundled-skills/notes-editor/SKILL.md):

```markdown
---
name: Notes Editor
description: Edit plain-text notes in the built-in Notes app.
category: 效率工具
allowed-tools:
  - load_tools
required-tools:
  - maka_computer
---

# Notes Editor

1. Load the `maka_computer` tool if not already present.
2. Observe the Notes window.
3. Use `set_value` to replace the note body.
4. Click the "Save" button.

```

Next, regenerate the catalog to include the new skill:

```bash
npm run generate:bundled-skills

```

The UI will automatically display the new skill in [`packages/ui/src/skills-panel.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/skills-panel.tsx) without additional code changes. Models can now invoke the capability:

```text
User: "Please add a TODO item to my notes."
Assistant: "/skill:notes-editor"

```

When invoked, the runtime executes `runSkillAction`, which loads `maka_computer`, observes the Notes window, sets the value, clicks Save, and returns the final observation to the model.

## Summary

- **Skill definitions** reside in `packages/runtime/resources/bundled-skills/` as [`SKILL.md`](https://github.com/apache/maka/blob/main/SKILL.md) files containing YAML frontmatter and workflow instructions.
- **Catalog generation** is handled by `scripts/gen-bundled-skill-catalog.mjs`, which validates content and emits [`bundled-skill-catalog.generated.ts`](https://github.com/apache/maka/blob/main/bundled-skill-catalog.generated.ts) with SHA-256 integrity checks.
- **Runtime registration** occurs through the SkillManager, which creates `SkillEntry` objects exposing metadata and status flags.
- **UI integration** is automatic via [`packages/ui/src/skills-panel.tsx`](https://github.com/apache/maka/blob/main/packages/ui/src/skills-panel.tsx), which reads the catalog through `getSkillsCopy()` and supports management actions.
- **Skill invocation** uses the `/skill:<name>` syntax, triggering `runSkillAction` to load required tools and execute the workflow.

## Frequently Asked Questions

### What is the difference between allowed-tools and required-tools?

**`required-tools`** are dependencies that must be loaded via `load_tools` before the skill executes, while **`allowed-tools`** are tools the model may request during execution without explicit pre-loading. The runtime enforces these constraints during `runSkillAction` to ensure the model only accesses authorized capabilities.

### How do I regenerate the skill catalog after adding a new skill?

Execute `npm run generate:bundled-skills` from the repository root. This runs `scripts/gen-bundled-skill-catalog.mjs`, which scans all [`SKILL.md`](https://github.com/apache/maka/blob/main/SKILL.md) files, validates their frontmatter, computes content digests, and rebuilds [`packages/runtime/src/bundled-skill-catalog.generated.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/bundled-skill-catalog.generated.ts).

### Can I use a skill immediately after adding its SKILL.md file?

No, you must regenerate the catalog and rebuild the runtime package first. The SkillManager reads from the generated TypeScript catalog rather than scanning the filesystem at runtime, so the build step is mandatory for the new skill to appear in `getSkillsCopy()` and the UI.

### Where does the runtime store the generated skill catalog?

The catalog is stored as a TypeScript module at [`packages/runtime/src/bundled-skill-catalog.generated.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/bundled-skill-catalog.generated.ts). This file is imported by the SkillManager during runtime initialization and compiled into the final npm package, ensuring skills are available immediately upon startup without filesystem I/O.