Canonical Agents

canonical-agents

An [OpenClaw](https://docs.openclaw.ai) plugin that watches directories for `.agent.md` and `AGENTS.md` files — markdown with YAML frontmatter — and dynamically provisions them as OpenClaw agents via configuration reconciliation.

Define agents in human-readable markdown files, version them in git, and have OpenClaw pick them up automatically — without editing `openclaw.json` by hand.

Intended Use

This plugin is designed for teams and individuals who want to:

• Version control agent definitions — each agent lives in its own markdown file, trackable with git.
• Share agents across projects — keep a canonical agents repository (~/agents-repo/) and point multiple OpenClaw instances at it.
• Rapidly prototype agents — edit a markdown file, save, and the agent updates automatically via hot reload. No restart needed.
• Separate agent configuration from prompts — YAML frontmatter holds config (model, tools, sandbox), while the markdown body holds the system prompt.

The plugin watches your agent files with [chokidar](https://github.com/paulmillr/chokidar), parses them with [gray-matter](https://github.com/jonschlinkert/gray-matter), and reconciles them into `openclaw.json` using SHA-256 hash-based change detection. Unchanged files are skipped; removed files cause their agents to be cleaned up.

Getting Started

Installation

Install the plugin with your preferred package manager:

npm install openclaw-canonical-agents
# or
pnpm add openclaw-canonical-agents

Basic Configuration

Register the plugin in your `openclaw.json`:

{
  "plugins": {
    "canonical-agents": {
      "enabled": true,
      "watchDirs": ["~/agents-repo"]
    }
  }
}

Creating Your First Agent

Create a directory for your agents and add a markdown file:

mkdir -p ~/agents-repo/helper

Create `~/agents-repo/helper/AGENTS.md`:

---
id: helper
description: General-purpose assistant
---

You are a help