multica/src/agent/skills

Skills System

English | 中文

Skills extend agent capabilities through SKILL.md definition files.

Table of Contents

• SKILL.md Specification
• Skill Invocation
• Loading & Precedence
• CLI Commands

---

SKILL.md Specification

Each skill is a directory containing a SKILL.md file with YAML frontmatter + Markdown content.

Basic Structure

---
name: My Skill
version: 1.0.0
description: What this skill does
metadata:
  emoji: "🔧"
  requires:
    bins: [git]
---

# Instructions

Detailed instructions injected into the agent's system prompt...

Frontmatter Fields

Field	Type	Required	Description
name	string	Yes	Display name
version	string	No	Version number
description	string	No	Short description
homepage	string	No	Homepage URL
metadata	object	No	See below
config	object	No	See below
install	array	No	See below

metadata.requires

Defines eligibility requirements:

metadata:
  emoji: "📝"
  requires:
    bins: [git, node]        # All must exist
    anyBins: [npm, pnpm]     # At least one must exist
    env: [API_KEY]           # All must be set
    platforms: [darwin, linux]  # Current OS must match

Field	Description
bins	Required binaries (all must exist in PATH)
anyBins	Alternative binaries (at least one must exist)
env	Required environment variables
platforms	Supported platforms: darwin, linux, win32

config

Runtime configuration options:

config:
  enabled: true
  requiresConfig: ["skills.myskill.apiKey"]
  options:
    timeout: 30000

install

Dependency installation specifications:

install:
  - kind: brew
    package: jq

  - kind: npm
    package: typescript
    global: true

  - kind: uv
    package: requests

  - kind: go
    package: github.com/example/tool@latest

  - kind: download
    url: https://example.com/tool.tar.gz
    archiveType: tar.gz
    stripComponents: 1

Supported install kinds:

Kind	Description	Key Fields
brew	Homebrew	package, cask
npm	npm/pnpm/yarn	package, global
uv	Python uv	package
go	Go install	package
download	Download & extract	url, archiveType

Common fields: id, label, platforms, when

---

Skill Invocation

Skills can be invoked by users via slash commands (/skill-name) or automatically by the AI model.

User Invocation

In the interactive CLI, type / followed by a skill name to invoke it:

You: /pdf analyze report.pdf

Tab completion: Type /p then press Tab to see matching skills like /pdf.

List available skills: Type /help to see all available skill commands.

Invocation Control

Control how skills can be invoked using frontmatter fields:

---
name: My Skill
user-invocable: true           # Can be invoked via /command (default: true)
disable-model-invocation: false # Include in AI prompt (default: false)
---

Field	Default	Description
user-invocable	true	Enable /command invocation in CLI
disable-model-invocation	false	If true, skill is hidden from AI's system prompt

Use cases:

• User-only skill (disable-model-invocation: true): User can invoke via /command, but AI won't use it automatically
• AI-only skill (user-invocable: false): AI can use it, but no /command available
• Disabled skill (both false): Hidden from both user and AI

Command Dispatch

For advanced integrations, skills can dispatch directly to tools:

---
name: PDF Tool
command-dispatch: tool
command-tool: pdf-processor
command-arg-mode: raw
---

Field	Description
command-dispatch	Set to tool to enable tool dispatch
command-tool	Name of the tool to invoke
command-arg-mode	How arguments are passed (raw = as-is)

Command Name Normalization

Skill names are normalized for command use:

• Converted to lowercase
• Special characters replaced with underscores
• Truncated to 32 characters max
• Duplicate names get numeric suffixes (e.g., pdf_2)

---

Loading & Precedence

Skills load from multiple sources with precedence (lowest to highest):

Priority	Source	Path	Description
1	bundled	<project>/skills/	Built-in skills
2	extraDirs	Configured	Additional directories
3	plugins	node_modules/*/	npm packages with multica.plugin.json
4	managed	~/.super-multica/skills/	CLI-installed skills
5	profile	~/.super-multica/agent-profiles/<id>/skills/	Profile-specific

Higher priority sources override skills with the same ID.

Plugin System (npm packages)

For npm packages that provide skills, the plugin system auto-discovers them if they include a multica.plugin.json manifest:

{
  "id": "my-plugin",
  "name": "My Skills Plugin",
  "description": "A collection of useful skills",
  "version": "1.0.0",
  "skills": ["./skills/pdf", "./skills/image"]
}

When to use plugins vs add command:

Method	Use When
pnpm skills:cli add owner/repo	Installing from GitHub (recommended for most cases)
npm install @company/plugin	Package author provides multica.plugin.json, or you need npm's dependency management

Note: Most third-party skills (like vercel-labs/agent-skills) are distributed via GitHub without multica.plugin.json. Use the add command for these.

Eligibility Filtering

After loading, skills are filtered by:

1. Platform check (platforms)
2. Binary check (bins, anyBins)
3. Environment check (env)
4. Config check (requiresConfig)
5. Enabled check (config.enabled)

Only skills passing all checks are marked as eligible.

---

CLI Commands

List Skills

pnpm skills:cli list           # List all skills
pnpm skills:cli list -v        # Verbose mode
pnpm skills:cli status         # Summary status
pnpm skills:cli status <id>    # Specific skill status

Install from GitHub

Example: Installing from anthropics/skills

The repository structure:

anthropics/skills/
├── skills/
│   ├── algorithmic-art/
│   │   └── SKILL.md
│   ├── brand-guidelines/
│   │   └── SKILL.md
│   ├── pdf/
│   │   └── SKILL.md
│   └── ... (16 skills total)

Install the entire repository (all 16 skills):

pnpm skills:cli add anthropics/skills
# Installs to: ~/.super-multica/skills/skills/
# All skills available: algorithmic-art, brand-guidelines, pdf, etc.

Install a single skill only:

pnpm skills:cli add anthropics/skills/skills/pdf
# Installs to: ~/.super-multica/skills/pdf/
# Only the pdf skill is installed

Install from a specific branch or tag:

pnpm skills:cli add anthropics/skills@main

Using full URL:

pnpm skills:cli add https://github.com/anthropics/skills
pnpm skills:cli add https://github.com/anthropics/skills/tree/main/skills/pdf

Force overwrite existing:

pnpm skills:cli add anthropics/skills --force

Supported formats:

Format	Example	Description
owner/repo	anthropics/skills	Clone entire repository
owner/repo/path	anthropics/skills/skills/pdf	Single directory (sparse checkout)
owner/repo@ref	anthropics/skills@v1.0.0	Specific branch or tag
Full URL	https://github.com/anthropics/skills	GitHub URL
Full URL + path	https://github.com/.../tree/main/skills/pdf	URL with specific path

Remove Skills

pnpm skills:cli remove <name>   # Remove installed skill
pnpm skills:cli remove          # List installed skills

Install Dependencies

pnpm skills:cli install <id>              # Install skill dependencies
pnpm skills:cli install <id> <install-id> # Specific install option

---

Status Diagnostics

The status command provides detailed diagnostics for understanding why skills are or aren't eligible.

Summary Status

pnpm skills:cli status        # Show summary with grouping by issue type
pnpm skills:cli status -v     # Verbose mode with hints

Output shows:

• Total/eligible/ineligible counts
• Ineligible skills grouped by issue type (binary, env, platform, etc.)

Detailed Skill Status

pnpm skills:cli status <skill-id>

Output includes:

• Basic skill info (name, version, source, path)
• Eligibility status with detailed diagnostics
• Requirements checklist showing which binaries/env vars are present
• Install options with availability status
• Quick actions with actionable hints to resolve issues

Diagnostic Types

Type	Description	Example Hint
disabled	Skill disabled in config	Enable via skills.<id>.enabled: true
not_in_allowlist	Bundled skill not allowed	Add to config.allowBundled array
platform	Platform mismatch	"Only works on: darwin, linux"
binary	Missing required binary	"brew install git"
any_binary	No alternative binary found	"Install any of: npm, pnpm, yarn"
env	Missing environment variable	"export OPENAI_API_KEY=..."
config	Missing config value	"Set config path: browser.enabled"

---

Async Serialization

The skills system uses async serialization to prevent concurrent operations from corrupting files or causing race conditions.

How It Works

Operations with the same key are executed sequentially:

import { serialize, SerializeKeys } from "./skills/index.js";

// These will execute sequentially, not in parallel
const p1 = serialize(SerializeKeys.skillAdd("my-skill"), () => addSkill(...));
const p2 = serialize(SerializeKeys.skillAdd("my-skill"), () => addSkill(...));

// This runs in parallel (different key)
const p3 = serialize(SerializeKeys.skillAdd("other-skill"), () => addSkill(...));

Built-in Serialization

The following operations are automatically serialized:

• addSkill() - by skill name
• removeSkill() - by skill name
• installSkill() - by skill ID

Utility Functions

import {
  isProcessing,   // Check if key is being processed
  getQueueLength, // Get pending operations count
  getActiveKeys,  // Get all active operation keys
  waitForKey,     // Wait for key operations to complete
  waitForAll,     // Wait for all operations
} from "./skills/index.js";

---

Troubleshooting

Skill not showing as eligible?

Run pnpm skills:cli status <skill-id> to see detailed diagnostics with actionable hints.

Override a bundled skill?

Create a skill with the same ID in ~/.super-multica/skills/ or profile skills directory.

Hot reload not working?

Ensure chokidar is installed: pnpm add chokidar

Concurrent operations causing issues?

All add/remove/install operations are automatically serialized. If you're building custom integrations, use the serialize() function with appropriate keys.