diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b3c0d4d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,127 @@
+# agents_core
+
+Bibliothèque partagée pour le système multi-agents. Fournit toutes les briques communes : communication MQTT/XMPP, LLM, gestion des tâches, chargement des skills, et découverte des capacités entre agents.
+
+## Installation
+
+```bash
+pip install -e /opt/agents_core
+```
+
+## Architecture
+
+```
+XMPP (slixmpp)          MQTT (Mosquitto local)
+utilisateur  ←→  nexus  ←→  agents/nexus/inbox
+                         ←→  agents/+/status      (retained)
+                         ←→  agents/+/capabilities (retained)
+                         ←→  agents/broadcast
+                         ←→  agents/llm/switch     (retained)
+```
+
+## Modules
+
+| Fichier | Rôle |
+|---------|------|
+| `base_agent.py` | Classe abstraite `BaseAgent` — à hériter dans chaque agent |
+| `mqtt_client.py` | Client MQTT (paho), reconnexion auto, publish/subscribe/reply |
+| `xmpp_client.py` | Client XMPP (slixmpp 1.13), reconnexion auto, MUC, thread-safe |
+| `llm_client.py` | Wrapper Ollama — chat, historique, extraction de skill calls |
+| `message_bus.py` | Enveloppe `Message` standard (type, payload, sender, reply_to…) |
+| `skill_loader.py` | Auto-découverte et exécution des plugins `.py` dans `skills/` |
+| `task_queue.py` | Queue SQLite FIFO avec worker thread |
+| `capabilities.py` | `AgentCapabilities` + `CapabilitiesRegistry` — annuaire des agents |
+| `command_parser.py` | Parse `/cmd`, `@agent msg`, langage naturel |
+
+## Créer un agent
+
+```python
+from agents_core import BaseAgent, AgentContext
+
+class MonAgent(BaseAgent):
+    AGENT_TYPE = "mon_type"
+    DESCRIPTION = "Description courte utilisée pour le routage LLM"
+    DEFAULT_CONFIG_PATH = "/opt/mon_agent/config/config.json"
+
+    def get_skills_dir(self) -> str:
+        return "/opt/mon_agent/skills"
+
+    def on_start(self):
+        self.mqtt.send_to("nexus", f"{self.agent_id} en ligne.")
+
+if __name__ == "__main__":
+    MonAgent().run()
+```
+
+## Format config.json
+
+```json
+{
+  "agent_id": "mon_agent",
+  "xmpp": {
+    "jid": "mon_agent@xmpp.ovh",
+    "password": "...",
+    "admin_jid": "sylvain@xmpp.ovh",
+    "muc_room": "agents@muc.xmpp.ovh"
+  },
+  "mqtt": {
+    "host": "localhost",
+    "port": 1883
+  },
+  "llm": {
+    "base_url": "http://192.168.7.119:11434",
+    "model": "ministral-3:latest",
+    "temperature": 0.3
+  },
+  "llm_profiles": {
+    "local": "ministral-3:latest",
+    "cloud": "gpt-oss:120b-cloud"
+  },
+  "queue_db": "/opt/mon_agent/data/queue.db"
+}
+```
+
+## Créer un skill
+
+Un skill est un fichier `.py` dans le dossier `skills/` de l'agent :
+
+```python
+# skills/mon_skill.py
+
+NAME = "mon_skill"
+DESCRIPTION = "Fait quelque chose d'utile. Args: <paramètre>"
+
+def run(args: str, context) -> str:
+    # context.agent, context.mqtt, context.xmpp, context.llm
+    return f"Résultat pour : {args}"
+```
+
+Le LLM appelle le skill avec : `SKILL:mon_skill ARGS:paramètre`
+
+## Hooks disponibles dans BaseAgent
+
+| Méthode | Déclencheur |
+|---------|-------------|
+| `on_start()` | Au démarrage, après connexion MQTT |
+| `on_xmpp_connected()` | Quand la connexion XMPP est établie |
+| `on_agent_status_change(agent_id, status)` | Quand un agent passe online/offline |
+| `on_broadcast(msg)` | Réception d'un message broadcast MQTT |
+| `handle_custom_command(cmd, args, msg)` | Commande `/xxx` non gérée par BaseAgent |
+| `setup_extra_subscriptions()` | Pour ajouter des souscriptions MQTT custom |
+
+## Topics MQTT
+
+| Topic | Usage |
+|-------|-------|
+| `agents/{id}/inbox` | Tâches entrantes |
+| `agents/{id}/status` | Statut online/offline (retained + LWT) |
+| `agents/{id}/capabilities` | Skills déclarés (retained) |
+| `agents/broadcast` | Message à tous les agents |
+| `agents/llm/switch` | Changement de modèle LLM global (retained) |
+
+## Dépendances
+
+- Python ≥ 3.10
+- paho-mqtt ≥ 1.6
+- slixmpp ≥ 1.8
+- requests ≥ 2.28