Agent Commons v0.2.0 — Protocol v2.0

Protocol version: 1.0 → 2.0 (breaking layout)

Two distinct kinds of change ship together:

1. skills/ becomes a directory of named skills

~/.agent-commons/skills/
└── agent-commons/   ← was directly in skills/, now isolated
    ├── SKILL.md
    └── manifest.json

Future shared skills can live alongside (e.g. skills/<your-skill>/) without naming collisions. Aligns with how mainstream AI runtimes lay out skill collections.

2. New convention-layer directories (non-normative, optional)

~/.agent-commons/
├── skills_data/<name>/   ← per-skill persistent data
├── mcp/<server>/         ← shared MCP server configs
├── plugins/<name>/       ← shared plugins
└── tools/<name>/         ← shared CLI scripts/utilities

Agent Commons does not read or interpret anything in the convention layer — it belongs to the skills/MCPs/plugins/tools that own each subdirectory. Skills that adopt the convention get free backup/sync semantics: the user backs up ~/.agent-commons/ once, all participating skills come along.

See CONVENTIONS.md for the full spec.

Where joined agents now put persistent data (recommended)

Once an agent has joined, it should default to placing data in the convention layer instead of inventing a private location elsewhere:

Need	Default location
Per-skill persistent data	~/.agent-commons/skills_data/<skill-name>/
Shared MCP server	~/.agent-commons/mcp/<server-name>/
Shared plugin	~/.agent-commons/plugins/<plugin-name>/
Shared CLI tool	~/.agent-commons/tools/<tool-name>/

ONBOARDING.md now teaches new agents this default; the runtime SKILL.md exposes a Capability 6 — Recommend persistence locations.

First adopter

soul-archive is moving its data location to ~/.agent-commons/skills_data/soul-archive/ for users who have joined Agent Commons. Standalone usage (without Agent Commons) still works; data falls back to ~/.skills_data/soul-archive/.

Migration

If you joined under 1.x, the new SKILL.md detects the protocol_version drift and redirects you to re-execute ONBOARDING.md. Re-running install.sh / install.ps1 is idempotent — it lays down the new dirs and refreshes protocol files without touching your data.

License: MIT.

Agent Commons v0.1.0

Initial public release.

Agent Commons is a local-first, plaintext-only shared memory protocol for AI agents. Multiple agents (Claude Code, Cursor, WorkBuddy, CodeBuddy, OpenClaw, etc.) on the same machine share a central directory at ~/.agent-commons/ so they don't forget what each other learned.

What's in this release

• Protocol decoupling: ONBOARDING.md (one-time joining flow) is separate from skills/SKILL.md (recurring runtime capability). Agents read onboarding once; the runtime skill carries the day-to-day capabilities forward.
• Discover-first install: agents must locate their own user-extensible / 'custom skills' directory before installing — not a built-in tier (where files would land but never trigger), and not another agent's directory.
• Closed-loop trigger test: install ≠ done. The runtime must actually invoke / list / describe the skill before the install is considered complete. Adaptive fallback ladder symlink → copy → readonly walks itself, only asking for help if all three tiers fail.
• Mirror-correct update strategy: Tier 2 (copy) agents must use rsync --delete / Robocopy /MIR / staged-tempdir-and-atomic-swap to handle adds, modifies, deletes, AND renames. Plain cp -R is a protocol violation — it leaves ghost files. Post-update, the trigger self-test runs again.
• Cross-platform installer: install.sh (POSIX) + install.ps1 (Windows PowerShell, with UTF-8 BOM + chcp 65001 + UTF-8 byte-array Chinese to defeat PS 5.1 mojibake).

Install

macOS / Linux / WSL / Git Bash:

curl -fsSL https://raw.githubusercontent.com/dqsjqian/agent-commons/main/install.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/dqsjqian/agent-commons/main/install.ps1 | iex

Then tell any AI agent:

Read ~/.agent-commons/ONBOARDING.md and join Agent Commons.

License: MIT.