emyann/créer-un-agent

Créer un agent dans Nemia

Un agent est un employé : une personne avec un métier, des standards (ses compétences) et un équipement (ses outils). Une étape d'un workflow est un poste qu'il occupe ; un agent peut occuper des postes dans plusieurs workflows. Les factories d'une personne ne reçoivent aucun agent de Nemia : l'équipe d'un dépôt se trouve dans workflows/, celle d'une personne dans ~/.agent-workflows/workflows/, et la page Agents du board écrit la seconde. Lisez le README de Nemia, Un agent est une attache d'un nœud, pour le format complet ; voici la procédure, et ce qu'il en a coûté d'apprendre.

Qui il est

• Son nom est celui de son fichier, agents/<nom>.md, un prénom en minuscules (nora), et une étape le nomme par ce nom (agent: nora). Le board affiche le nom comme un prénom (Nora) à côté d'un visage généré à partir de celui-ci (Blobatar), identique partout où il apparaît.
• role: est le poste qu'il occupe, en quelques mots (Ingénieur produit) ; description: indique quand l'attacher, une ligne. Les deux sont des lignes propres à l'agent, avec harnessPrompt: : une étape qui en définit un est refusée. Les skills: d'une étape s'ajoutent à celles de son agent (Ses compétences).
• mcp: nomme les serveurs MCP que ses sessions chargent, par les noms que le .mcp.json du checkout leur donne (mcp: playwright). Les mcp: d'une étape s'ajoutent à ceux de son agent, comme ses skills: le font : un serveur que seul un dépôt possède est nommé par l'étape qui en a besoin, afin que l'agent reste portable. Une session charge les serveurs que son agent et son étape nomment, et aucun autre : sans ligne ni sur l'un ni sur l'autre, elle n'en charge aucun, et un nom que le checkout ne déclare pas refuse la session à son démarrage. Charger un serveur n'autorise aucun de ses outils : son périmètre de sécurité décide toujours. Un agent qui en nomme un ne peut pas être essayé, car un essai n'a pas de checkout.
• Une ligne name: doit être égale au nom du fichier ; card: est obsolète (la carte est générée à partir de ses compétences : npx wf agents card <nom>).

Le fichier

Le frontmatter, puis ses instructions. Les autres clés définissent comment ses sessions s'exécutent — harness, model, effort, context, remote, output, et son périmètre de sécurité — et une étape qui le nomme reprend chacune sauf si elle définit les siennes. Le câblage est du ressort de l'étape et refusé ici : after, input, workspace, check, gate, loop, budget, background.

• Le périmètre de sécurité se trouve sous le bloc de son harness : claude: { fence: { permissionMode, tools, allowedTools, disallowedTools } }, ou codex: { fence: { sandbox } }. Le bloc ne contient que fence, et un bloc pour un autre harness que celui du fichier est refusé. Une clé fence au niveau supérieur est l'ancienne orthographe, encore lue ; nemia frontmatter rewrite <dossier> la déplace dans le bloc.
• Indiquez ce qu'une étape peut surcharger : overridable: model, effort, fence, skills, chaque mot étant l'un des OVERRIDABLE (model, effort, context, harness, remote, output, fence, skills, mcp). Une étape qui définit autre chose est refusée au chargement, en nommant la clé et l'agent. Sans ligne, une étape peut tout surcharger, et nemia start demande d'en ajouter une.

---
role: Relecteur de code
harness: claude
model: opus
overridable: model, effort, fence
claude:
  fence:
    permissionMode: dontAsk
    tools: Read, Grep, Glob, Bash
    allowedTools: Bash(git log:*), Bash(git diff:*)
---

• Le frontmatter est du YAML, comme celui d'une étape et d'une compétence, chaque valeur lue comme le texte écrit. Mettez entre guillemets une valeur qui contient : ou #, ou qui commence par un signe YAML ([, {, *, &, !, |, >, -, ?), comme dans description: "Relit une modification : son exactitude". Écrivez une valeur longue sous forme de bloc littéral, |- et la valeur sur les lignes en dessous, en retrait. Une clé de liste prend Read, Grep ou [Read, Grep] ; le board écrit la première forme.
• Indiquez effort: et context: (200k) : un emploi ne lit pas les paramètres utilisateur, et une session sans limite lit jusqu'à un million de tokens à chaque appel.
• auto est refusé au chargement sur les modèles mesurés pour l'abandonner (haiku, claude-sonnet-4-5) ; nommez dontAsk avec des règles.

Ses instructions

Le corps est ses instructions, ajoutées à l'invite propre de Claude Code (harnessPrompt: keep ; no-coding supprime la section de codage du harness, replace met les instructions à sa place). Gardez-les génériques et courtes : qui il est, de quoi il est responsable, ce qu'il ne fait jamais, comment il termine un tour, ce que contient sa clôture. La procédure appartient à une compétence, et une règle détenue par la machinerie (un périmètre de sécurité, une barrière) n'a pas besoin de phrase. Une session reprise conserve le corps avec lequel elle a commencé : une modification atteint l'exécution suivante, jamais une en cours.

Les cinq couches

Les instructions sont l'une des cinq couches qui façonnent un agent en dehors de sa tâche, chacune écrite par celui qui la possède :

1. Instructions — le corps de l'agent : qui il est, partout où il est embauché.
2. Instructions personnalisées — ce qu'une personne ajoute à un agent qu'elle utilise sans le réécrire, conservé dans son magasin, un fichier par nom d'agent (wf agents custom <nom>), jamais dans le dossier de l'agent. Mots uniquement : ils ne définissent aucune clé, donc ils n'élargissent jamais le périmètre de sécurité ni ne donnent d'outil. Une exécution les fige au démarrage, donc une modification n'atteint que les exécutions suivantes.
3. Les fichiers du dossier — les fichiers que le harness lit depuis le dossier dans lequel l'agent travaille (aujourd'hui CLAUDE.md, AGENTS.md) : ce qui s'y trouve pour chaque agent travaillant dans ce dossier. Nemia ne les compose pas. Ils se classent au-dessus des instructions propres de l'agent et en dessous des règles de la factory et de la politique de l'étape, bien qu'un harness les présente comme écrasant tout : ce cadrage est celui du harness.
4. Les règles de la factory — les règles et politiques d'une factory, communiquées à chaque agent embauché dans celle-ci : un fichier par factory, conservé dans le magasin (nemia factory rules <nom>), jamais dans un dépôt. Mots uniquement, figés par une exécution à son démarrage, comme les instructions personnalisées. Aucune n'est communiquée à une étape sur un agent distant.
5. La politique de l'étape — les mots et clés propres de l'étape : ce que ce poste de ce processus demande à un rôle. Une couche normale, pas un contournement : dites-y ce qu'un workflow attend, et gardez-le hors des instructions. Une étape peut ajouter des compétences, jamais en enlever.

Le nombre est la précédence : lorsque deux couches disent des choses différentes, le nombre le plus élevé l'emporte, et la tâche est au-dessus de toutes. L'ordre dans lequel les mots arrivent est une chose distincte — instructions, instructions personnalisées, règles de la factory, politique de l'étape, puis la tâche, les fichiers du dossier étant lus par le harness là où l'agent travaille. La couche qui possède une nouvelle instruction est la propre règle de routage de Nemia, Où va une nouvelle instruction, énoncée une fois dans le passage Cinq couches fourni : demandez-la plutôt que de deviner. Les périmètres de sécurité ne font que se resserrer : une étape peut réduire le périmètre de son agent et jamais l'élargir — les disallowedTools: d'une étape s'ajoutent à ceux de son agent, et le chargeur refuse les tools:, allowedTools:, permissionMode: ou sandbox: d'une étape qui donneraient à l'agent ce que son fichier ne donne pas. Ainsi, les instructions disent ce qui s'applique au rôle partout, et rien sur un workflow ou un espace de travail particulier.

Sa clôture

output: <nom>.schema.json, un schéma JSON à côté de l'agent : ce que l'étape remet, décodé strictement. Style maison : chaque champ described, required, additionalProperties: false.

• Réservés : outcome, summary, artifacts, needs sont propres à l'exécution sur chaque clôture ; le chargeur refuse un schéma qui en déclare un. (L'intention d'Iris propose proposedOutcome pour cette raison.)
• Gardez un schéma identique entre les essais d'une session : une session continuée à laquelle on donne un schéma modifié reconstruit tout son cache d'invite.
• Une étape lit une clôture avec input: <étape> depuis n'importe quelle étape qu'elle attend, y compris à travers les étapes intermédiaires ; une étape qui boucle (loop:) ne peut attendre qu'une seule étape, donc elle lit ce qui est arrivé avant la boucle de cette manière (une étape de relecture lit ainsi la spécification).

Ses compétences

skills: <a>, <b> nomme des dossiers contenant un SKILL.md, recherchés dans skills/ à côté du dossier des agents, puis dans .claude/skills/ du dépôt, puis dans celui du magasin, puis dans les compétences propres de Nemia, en dernier. tools: doit autoriser Skill. Le .claude/skills/ du dépôt n'est trouvé que lorsque le dépôt est le lieu de l'étape, comme un démarrage le donne : un test qui charge un dossier passe aussi le lieu. Une étape avec un agent peut ajouter des compétences avec ses propres skills: : la session reçoit celles de l'agent, puis celles de l'étape, chacune une fois. Le périmètre de sécurité de l'agent doit déjà les charger ; une étape ne l'élargit jamais.

• Écrivez une compétence avec la méthode de skill-creator : une description: qui dit quand l'utiliser, un corps court, des détails dans des fichiers à côté.
• Utilisez celle d'un autre sans modification : dans un projet temporaire, DO_NOT_TRACK=1 npx skills add <propriétaire>/<dépôt> --skill <nom> --agent claude-code --copy -y ; copiez le dossier dans .claude/skills/, fusionnez son entrée dans skills-lock.json, et ajoutez son auteur, sa source et sa licence à THIRD_PARTY_NOTICES.md (MIT demande la notice dans chaque copie). Ne l'éditez jamais — le verrou la fixe — et adaptez-la dans le corps de l'agent. Importez la compétence qu'un modèle peut invoquer : une compétence avec disable-model-invocation: true est une commande slash de la personne (grill-me appelle uniquement grilling).

Son périmètre de sécurité

• Un rôle qui n'écrit rien exécute dontAsk. Seulement des lectures dans son espace de travail, des commandes en lecture seule, et ce qu'une règle d'autorisation nomme s'exécute ; le reste est refusé sans demander. Les paramètres du dépôt peuvent autoriser des commandes dont d'autres rôles ont besoin qui écrivent dans l'espace de travail (une compilation, par exemple), donc un agent doté de Bash refuse chacune par son nom dans disallowedTools:. Un sous-agent hérite du mode et des règles ; listez Agent dans allowedTools: afin que le dispatch lui-même ne soit jamais refusé. Autorisez par nom exact chaque vérification que le rôle exécute et que les paramètres n'autorisent pas ; sa compétence épelle chacune nue, un par appel (une commande enveloppée, canalisée, redirigée, ou derrière cd, git -C, VAR= ou for est refusée), et envoie une lecture ou une recherche à Read, Grep ou Glob, pas à Bash.
• Un rôle qui édite exécute auto, et refuse par nom ce qu'il ne doit jamais faire : Bash(git push), Bash(git push:*), Bash(git branch -D:*), Bash(git branch --delete --force:*), Bash(pkill:*), Bash(killall:*), mcp__playwright__browser_run_code_unsafe.
• Une étape ne fait que le resserrer, et uniquement là où overridable: nomme fence. Une étape qui a besoin d'un outil, d'une autorisation ou d'un mode que le fichier de son agent ne donne pas a besoin d'un autre agent ; les disallowedTools: d'une étape s'ajoutent à ceux de son agent : écrivez uniquement les refus que l'étape ajoute ; elle ne peut jamais enlever ceux de l'agent.

Dialoguer avec une personne

Une étape est un travail sur l'Agent SDK : elle ne peut pas attendre à l'intérieur d'une conversation. Pour demander, elle signe blocked avec ses questions ; la personne répond sur le board ou avec wf retry <exécution> <étape> --message "…", et la même session continue avec les réponses comme son tour suivant. Dites-le dans le corps d'un agent qui interviewe, et barriez l'étape dont une personne doit accepter la clôture (gate: true). Le dernier tour d'un travail est sa conclusion : un agent qui exécute des commandes longues (l'e2e) doit les exécuter au premier plan ou les attendre, jamais conclure avec une en cours d'exécution (le premier build web d'un ingénieur a une fois conclu avant la fin de son e2e). Une clôture signée blocked est lue seule, donc un agent qui demande en tours de charge transporte tout ce qui a été décidé jusqu'à présent dans chaque tour : le troisième tour d'un intervieweur a un fois perdu ses décisions antérieures. Déclarez les questions comme un champ du schéma de sortie, { "x-shape": "questions", "description": "…" }, que le chargeur étend en une forme stricte unique : le board les dessine comme des choix qu'une personne répond en cliquant. Une étape barrée qui connaît le coût des étapes suivantes déclare { "x-shape": "budgets", "description": "…" } à côté : une liste de { step, usd, why }, chacun une étape après la barrière, une fois, en dollars au-dessus de zéro, why les éléments sur lesquels le montant s'est basé. La barrière les affiche à côté de la clôture, et les approuver en fait les plafonds de ces étapes, avec tout montant que la personne a modifié (nemia approve <exécution> <étape> --budget <étape>=<montant>) ; un plafond supérieur au budget: propre d'une étape est indiqué là, et jamais approuvé sans demande. Une clôture dont les budgets nomment une autre étape, ou aucun montant, est refusée et renvoyée à sa session.

Vérifiez-le

1. npx wf agents card <nom> depuis le dépôt : le véritable chargeur lit le fichier — ses clés, les noms réservés de son schéma, chaque compétence trouvée — et affiche la carte, ou refuse en mots qui nomment la correction.
2. Les vérifications propres du dépôt, là où ses gardes lisent chaque dossier qu'il livre (les périmètres de sécurité, les étapes figées, le rendu aller-retour) : exécutez-les en contournant tout cache qui ne voit pas le dossier des workflows.
3. Exécutez-le : un workflow barré qui le nomme, sur une petite carte réelle, et lisez sa clôture avant d'approuver.
4. Nommez le nouvel agent là où le dépôt liste ses agents.

Quand vous apprenez quelque chose

Créer un agent est la manière dont cette compétence est testée. Lorsqu'une étape ici était erronée ou manquante — un refus que vous avez rencontré, une clé qui vous a surpris — corrigez ce fichier dans la même modification que l'agent, en trois lignes au maximum, avec le fichier qui contient la règle.