How to Extend Maka's Capabilities Using the Skills System

Extending Maka's capabilities requires creating a declarative 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 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 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 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:

npm run generate:bundled-skills

This command executes scripts/gen-bundled-skill-catalog.mjs, which reads every 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. 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 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 file provides visual indicators for diagnostic flags such as "shadowed skill" and "update available", while 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 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:

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

npm run generate:bundled-skills

The UI will automatically display the new skill in packages/ui/src/skills-panel.tsx without additional code changes. Models can now invoke the capability:

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 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 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, 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 files, validates their frontmatter, computes content digests, and rebuilds 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. 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.

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