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.