Concept

Les agents AI comme Claude Code, Cursor et Codex utilisent des fichiers d'instructions (souvent appelés "skills") pour personnaliser leur comportement. Chaque agent stocke ces fichiers dans un répertoire différent : • Claude Code → .claude/skills/ • Cursor → .cursor/skills/ • Codex → .codex/skills/ Maintenir manuellement des copies identiques de skills dans chacun de ces répertoires est fastidieux, source d'erreurs et difficile à mettre à jour.

maconfai résout ce problème en introduisant une source de vérité unique. Les skills sont stockés dans un répertoire canonique (.agents/skills/) et des symlinks sont créés vers les répertoires de chaque agent. Cela signifie qu'un seul fichier physique alimente tous vos agents. Mettre à jour une skill met automatiquement à jour tous les agents qui l'utilisent.

maconfai fonctionne en trois phases distinctes : 1. Découverte — Le repository source est cloné (ou lu localement) et maconfai recherche tous les fichiers SKILL.md dans les répertoires skills/. Chaque fichier SKILL.md définit une skill avec ses métadonnées. 2. Sélection — Une interface interactive permet de choisir quelles skills installer et pour quels agents. Les skills déjà installées sont pré-cochées. 3. Installation — Les fichiers sont copiés vers .agents/skills/ et des symlinks sont créés dans les répertoires de chaque agent sélectionné.

Chaque skill est définie par un fichier SKILL.md placé dans un sous-répertoire de skills/. Ce fichier contient les instructions que l'agent AI suivra. maconfai utilise ce fichier comme point de découverte : tout répertoire contenant un SKILL.md est considéré comme une skill installable.

skills/
├── ma-skill-1/
│   └── SKILL.md
└── ma-skill-2/
    └── SKILL.md
mcps/
├── github/
│   └── mcp.json
└── filesystem/
    └── mcp.json
hooks/
└── pre-commit/
    └── hooks.json

Au-delà des skills (SKILL.md), maconfai gère également : • Serveurs MCP — Définis dans des fichiers mcp.json placés dans un répertoire dédié mcps/ (ex : mcps/github/mcp.json, mcps/filesystem/mcp.json), fusionnés dans la configuration spécifique de chaque agent. • Hooks — Définis dans des fichiers hooks.json pour les gestionnaires d'événements spécifiques à chaque agent. Ces trois types de configuration (skills, MCP, hooks) sont traités uniformément par le système d'installation.

maconfai maintient un fichier ai-lock.json à la racine du projet. Ce fichier de verrouillage enregistre : • Les skills, serveurs MCP et hooks installés • L'URL source de chaque configuration • Le hash Git (tree SHA) pour détecter les changements • L'horodatage de l'installation Ce fichier permet à la commande maconfai check de comparer les versions installées avec celles disponibles en amont et de proposer les mises à jour nécessaires.

// Exemple simplifié de ai-lock.json
{
  "skills": {
    "ma-skill": {
      "source": "vbarrai/skills",
      "treeHash": "abc123...",
      "installedAt": "2026-03-19T10:00:00Z"
    }
  },
  "mcps": { ... },
  "hooks": { ... }
}