Principle:Openclaw Openclaw Extension Type Identification

Extension Type Identification

Extension Type Identification is the principle of distinguishing between the two fundamental kinds of extensions in the OpenClaw gateway: plugins and skills. Each extension type serves a distinct purpose, follows its own lifecycle, and is governed by a separate configuration schema. Understanding the boundary between these two types is essential for correctly extending the system.

Overview

OpenClaw is a multi-channel AI agent gateway built in TypeScript. It supports two orthogonal extension mechanisms:

Extension Type	Definition	Artifact	Registration Model
Plugin	A TypeScript module with a package.json manifest that declares openclaw.extensions entry points. Plugins register channels, tools, providers, hooks, CLI commands, gateway methods, HTTP handlers, and services.	npm package, archive, local directory, or single file	Imperative: the module exports a register(api) callback that receives an OpenClawPluginApi handle.
Skill	A markdown file (SKILL.md) that teaches an agent how to use existing tools. Skills carry YAML frontmatter with eligibility metadata (OS, required binaries, environment variables, config flags).	Directory containing SKILL.md	Declarative: the skill is discovered by scanning directories and is included in the agent prompt when eligibility criteria pass.

Why the Distinction Matters

Plugins and skills address fundamentally different concerns:

1. Plugins add capabilities. A plugin can introduce a new messaging channel (e.g., Microsoft Teams), a new model provider (e.g., a custom LLM endpoint), a new agent tool (e.g., a database query tool), or a background service. Plugins execute arbitrary TypeScript code during the gateway lifecycle.
2. Skills add knowledge. A skill tells the agent how to accomplish a task using tools that already exist (either built-in or contributed by plugins). Skills are passive: they are injected into the system prompt, and the agent decides when to invoke them.

This separation keeps the security and trust model clean. Plugins run code and therefore require manifest validation, security scanning, and explicit enablement. Skills are text documents that influence prompting and therefore need only eligibility filtering.

Plugin Characteristics

A plugin is identified by:

• A package.json with an openclaw.extensions array listing TypeScript/JavaScript entry points.
• An optional id, name, description, version, and kind exported from the module.
• An origin indicating where the plugin was discovered: bundled, global, workspace, or config.

Plugins are installed into ~/.openclaw/extensions/ or a workspace-local .openclaw/extensions/ directory. They are loaded synchronously via jiti (a just-in-time TypeScript importer), and their register function is invoked with a rich API handle for registering capabilities.

Skill Characteristics

A skill is identified by:

• A directory containing a SKILL.md file.
• YAML frontmatter in the markdown that may specify metadata including OS restrictions, required binaries, required environment variables, required config paths, and invocation policies.

Skills are discovered from multiple directories in priority order: extra directories (lowest), bundled, managed (~/.openclaw/skills/), and workspace (<workspace>/skills/) (highest). When two skills share the same name, the higher-precedence source wins.

Configuration Separation

Each extension type has its own top-level configuration section:

• plugins -- controlled by PluginsConfig: global enable/disable, allow/deny lists, per-plugin entry config, install records, slot assignments, and additional load paths.
• skills -- controlled by SkillsConfig: bundled-skill allowlist, extra scan directories, watcher settings, install preferences, and per-skill entry config.

This separation ensures that plugin and skill configuration cannot conflict and that each system can evolve independently.

Related Concepts

• Plugin Installation -- how plugins are acquired from npm, archives, or local paths.
• Skill Loading -- how skills are discovered, parsed, and filtered.
• Extension Configuration -- how plugins and skills are enabled, disabled, and configured.
• Extension Verification -- how loaded extensions are validated and their status reported.

Implementation

Implementation:Openclaw_Openclaw_PluginsConfig_SkillsConfig_Types