emyann/crear-un-agente

Crear un agente en Nemia

Un agente es un contratado: una persona con un trabajo, estándares (sus habilidades) y equipo (sus herramientas). Un paso de un flujo de trabajo es un puesto que ocupa; un agente puede ocupar puestos en varios flujos de trabajo. Las fábricas de una persona no reciben ningún agente de Nemia: el equipo de un repositorio está en sus workflows/, el de una persona en ~/.agent-workflows/workflows/, y la página de Agentes del tablero escribe el segundo. Lee el README de Nemia, Un agente es un adjunto de un nodo, para el formato completo; este es el procedimiento, y lo que costó aprender.

Quién es

• Su nombre es el de su archivo, agents/<nombre>.md, un nombre de pila en minúsculas (nora), y un paso lo nombra por eso (agent: nora). El tablero muestra el nombre como el de una persona (Nora) junto a una cara dibujada a partir de él (Blobatar), igual dondequiera que se muestre.
• role: es el trabajo que ocupa, en pocas palabras (Product engineer); description: dice cuándo adjuntarlo, una línea. Ambas son líneas propias del agente, con harnessPrompt:: un paso que establece una es rechazado. Los skills: de un paso se añaden a los de su agente (Sus habilidades).
• mcp: nombra los servidores MCP que cargan sus sesiones, por los nombres que el .mcp.json del checkout les da (mcp: playwright). Un paso mcp: se añade al de su agente, como hacen sus skills:: un servidor que solo tiene un repositorio es nombrado por el paso que lo necesita, para que el agente siga siendo portátil. Una sesión carga los servidores que nombran su agente y su paso, y ningún otro: sin línea en ninguno no carga ninguno, y un nombre que el checkout no declara rechaza la sesión al inicio. Cargar un servidor no permite ninguna de sus herramientas: su cerca aún decide. Un agente que nombra uno no puede ser probado, ya que una prueba no tiene checkout.
• Una línea name: debe ser igual al nombre del archivo; card: está retirada (la tarjeta se genera a partir de sus habilidades: npx wf agents card <nombre>).

El archivo

Frontmatter, luego sus instrucciones. Las otras claves son cómo se ejecutan sus sesiones — harness, model, effort, context, remote, output, y su cerca — y un paso que lo nombra toma cada una a menos que establezca la suya propia. El cableado es del paso y se rechaza aquí: after, input, workspace, check, gate, loop, budget, background.

• La cerca va debajo del bloque de su harness: claude: { fence: { permissionMode, tools, allowedTools, disallowedTools } }, o codex: { fence: { sandbox } }. El bloque contiene solo fence, y un bloque para otro harness que el del archivo es rechazado. Una clave fence en el nivel superior es la ortografía anterior, aún se lee; nemia frontmatter rewrite <carpeta> la mueve dentro del bloque.
• Di lo que un paso puede sobrescribir: overridable: model, effort, fence, skills, cada palabra una de OVERRIDABLE (model, effort, context, harness, remote, output, fence, skills, mcp). Un paso que establece cualquier otra cosa es rechazado al cargar, nombrando la clave y el agente. Sin línea, un paso puede sobrescribir todo, y nemia start dice que agregues una.

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

• El frontmatter es YAML, como lo son los de un paso y una habilidad, cada valor se lee como el texto escrito. Pon entre comillas un valor que contenga : o #, o que comience con un signo YAML ([, {, *, &, !, |, >, -, ?), como en description: "Reviews a change: its correctness". Escribe uno largo como un bloque literal, |- y el valor en las líneas debajo, con sangría. Una clave de lista toma Read, Grep o [Read, Grep]; el tablero escribe la primera.
• Di effort: y context: (200k): un trabajo no lee configuraciones de usuario, y una sesión sin límite lee hasta un millón de tokens en cada llamada.
• auto es rechazado al cargar en los modelos medidos para eliminarlo (haiku, claude-sonnet-4-5); nombra dontAsk con reglas allí.

Sus instrucciones

El cuerpo son sus instrucciones, añadidas al prompt propio de Claude Code (harnessPrompt: keep; no-coding elimina la sección de codificación del harness, replace pone las instrucciones en su lugar). Mantenlas genéricas y cortas: quién es, de qué es responsable, qué nunca hace, cómo termina un turno, qué contiene su cierre. El procedimiento pertenece a una habilidad, y una regla que sostiene la maquinaria (una cerca, una puerta) no necesita una oración. Una sesión reanudada mantiene el cuerpo con el que comenzó: una edición alcanza la siguiente ejecución, nunca una en vuelo.

Las cinco capas

Las instrucciones son una de cinco capas que moldean a un agente aparte de su tarea, cada una escrita por quien la posee:

1. Instrucciones — el cuerpo del agente: quién es, dondequiera que sea contratado.
2. Instrucciones personalizadas — lo que una persona añade a un agente que usa sin reescribirlo, guardado en su almacén, un archivo por nombre de agente (wf agents custom <nombre>), nunca en la carpeta del agente. Solo palabras: no establecen ninguna clave, por lo que nunca amplían la cerca ni dan una herramienta. Una ejecución las congela cuando comienza, por lo que una edición solo alcanza las ejecuciones posteriores.
3. Los archivos de la carpeta — los archivos que el harness lee de la carpeta en la que trabaja el agente (hoy CLAUDE.md, AGENTS.md): lo que se sostiene allí para cada agente que trabaja en ella. Nemia no compone nada de ellos. Se clasifican por encima de las propias instrucciones del agente y por debajo de las reglas de la fábrica y la política del paso, aunque un harness los presenta como si anularan todo: ese marco es del harness.
4. Las reglas de la fábrica — las reglas y políticas de una fábrica, dichas a cada agente contratado en ella: un archivo por fábrica, guardado en el almacén (nemia factory rules <nombre>), nunca en un repositorio. Solo palabras, y congeladas por una ejecución cuando comienza, como las instrucciones personalizadas. A un paso en un agente remoto no se le dice ninguna.
5. La política del paso — las propias palabras y claves del paso: lo que esta posición de este proceso le pide a un rol. Una capa normal, no un workaround: di allí lo que un flujo de trabajo espera, y mantenlo fuera de las instrucciones. Un paso puede añadir habilidades, nunca quitar ninguna.

El número es precedencia: donde dos capas dicen cosas diferentes, gana el número más alto, y la tarea está por encima de todas. El orden en que llegan las palabras es algo separado — instrucciones, instrucciones personalizadas, reglas de la fábrica, política del paso, luego la tarea, con los archivos de la carpeta leídos por el harness dondequiera que trabaje el agente. Qué capa posee una nueva instrucción es la propia regla de enrutamiento de Nemia, Donde va una nueva instrucción, dicha una vez en el pasaje Cinco capas enviado: pregúntalo en lugar de adivinar. Las cercas solo se ajustan: un paso puede reducir la cerca de su agente y nunca ampliarla — los disallowedTools: de un paso se añaden a los de su agente, y el cargador rechaza los tools:, allowedTools:, permissionMode: o sandbox: de un paso que le darían al agente lo que su archivo no tiene. Por lo tanto, las instrucciones dicen lo que se sostiene para el rol en todas partes, y nada sobre un flujo de trabajo o un espacio de trabajo.

Su cierre

output: <nombre>.schema.json, un JSON Schema junto al agente: lo que el paso entrega, decodificado estrictamente. Estilo de la casa: cada campo described, required, additionalProperties: false.

• Reservados: outcome, summary, artifacts, needs son propios de la ejecución en cada cierre; el cargador rechaza un esquema que declara uno. (La intención de Iris dice proposedOutcome por esa razón.)
• Mantén un esquema igual a través de los intentos de una sesión: una sesión continuada que recibe un esquema cambiado reconstruye toda su caché de prompt.
• Un paso lee un cierre con input: <paso> de cualquier paso del que espere, también a través de los pasos intermedios; un paso que itera (loop:) puede esperar solo un paso, por lo que lee lo que vino antes del bucle de esa manera (un paso de revisión lee la especificación así).

Sus habilidades

skills: <a>, <b> nombra carpetas que contienen un SKILL.md, buscadas en skills/ junto a la carpeta de agentes, luego en .claude/skills/ del repositorio, luego en el almacén, luego en las propias habilidades de Nemia, por último. tools: debe permitir Skill. El .claude/skills/ del repositorio solo se encuentra cuando el repositorio es el lugar del paso, como lo da un inicio: una prueba que carga una carpeta también pasa el lugar. Un paso con un agente puede añadir habilidades con sus propios skills:: la sesión obtiene las del agente, luego las del paso, cada una una vez. La cerca del agente ya debe cargarlas; un paso nunca la amplía.

• Escribe una habilidad con el método del creador de habilidades: una description: que diga cuándo usarla, un cuerpo corto, detalle en archivos junto a ella.
• Usa la de otro sin cambios: en un proyecto scratch, DO_NOT_TRACK=1 npx skills add <propietario>/<repo> --skill <nombre> --agent claude-code --copy -y; copia la carpeta en .claude/skills/, fusiona su entrada en skills-lock.json, y añade su autor, fuente y licencia a THIRD_PARTY_NOTICES.md (MIT pide el aviso en cada copia). Nunca la edites — el bloqueo la fija — y adáptala en el cuerpo del agente. Vende la habilidad que un modelo puede invocar: una que diga disable-model-invocation: true es un comando de barra de una persona (grill-me solo llama a grilling).

Su cerca

• Un rol que no escribe nada ejecuta dontAsk. Solo lecturas en su espacio de trabajo, comandos de solo lectura, y lo que nombra una regla de permiso se ejecuta; el resto es rechazado sin preguntar. La configuración del repositorio puede permitir comandos que otros roles necesitan que escriben en el espacio de trabajo (una compilación, por ejemplo), por lo que un agente al que se le da Bash deniega cada uno por nombre en disallowedTools:. Un sub-agente hereda el modo y las reglas; lista Agent en allowedTools: para que el envío en sí nunca sea rechazado. Permite por nombre exacto cada verificación que el rol ejecuta que la configuración no; su habilidad deletrea cada una desnuda, una por llamada (una envuelta, con pipe, redirigida, o detrás de cd, git -C, VAR= o for es rechazada), y envía una lectura o búsqueda a Read, Grep o Glob, no a Bash.
• Un rol que edita ejecuta auto, y deniega por nombre lo que nunca debe hacer: 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.
• Un paso solo la ajusta, y solo donde overridable: nombra fence. Un paso que necesita una herramienta, un permiso o un modo que el archivo de su agente no da necesita otro agente; los disallowedTools: de un paso se añaden a los de su agente: escribe solo las denegaciones que el paso añade; nunca puede quitar una del agente.

Hablar con una persona

Un paso es un trabajo en el Agent SDK: no puede esperar dentro de una conversación. Para preguntar, firma como blocked con sus preguntas; la persona responde en el tablero o con wf retry <ejecución> <paso> --message "…", y la misma sesión continúa con las respuestas como su próximo turno. Dilo en el cuerpo de un agente que entrevista, y pon una puerta al paso cuyo cierre una persona debe aceptar (gate: true). El último turno de un trabajo es su firma: un agente que ejecuta comandos largos (el e2e) recibe la instrucción de ejecutarlos en primer plano o esperarlos, nunca de firmar con uno en ejecución (un ingeniero perdió su primera compilación web antes de que su e2e terminara). Un cierre firmado blocked se lee por sí solo, por lo que un agente que pregunta en rondas lleva todo lo acordado hasta ahora en cada una: la tercera ronda de un entrevistador una vez perdió sus decisiones anteriores. Declara las preguntas como un campo del esquema de salida, { "x-shape": "questions", "description": "…" }, que el cargador expande a una forma estricta: el tablero las dibuja como opciones que una persona responde haciendo clic. Un paso con puerta que sabe lo que costarán los pasos posteriores declara { "x-shape": "budgets", "description": "…" } junto a ellos: una lista de { paso, usd, why }, cada uno un paso después de la puerta, una vez, en dólares sobre cero, why las cifras por las que pasó el monto. La puerta los muestra junto al cierre, y aprobarlo los convierte en los límites de esos pasos, con cualquier monto que la persona haya cambiado (nemia approve <ejecución> <paso> --budget <paso>=<monto>); un límite por encima del propio budget: de un paso se dice allí, y nunca se aprueba sin preguntar. Un cierre cuyos presupuestos nombran otro paso, o ningún monto, es rechazado de vuelta a su sesión.

Verificar

1. npx wf agents card <nombre> desde el repositorio: el cargador real lee el archivo — sus claves, los nombres reservados de su esquema, cada habilidad encontrada — e imprime la tarjeta, o rechaza en palabras que nombran la corrección.
2. Las propias verificaciones del repositorio, donde sus guardianes leen cada carpeta que envía (las cercas, los pasos congelados, el viaje de ida y vuelta de renderizado): ejecútalas más allá de cualquier caché que no vea la carpeta de flujos de trabajo.
3. Ejecútalo: un flujo de trabajo con puerta que lo nombre, en una tarjeta real pequeña, y lee su cierre antes de aprobar.
4. Nombra el nuevo agente donde el repositorio lista sus agentes.

Cuando aprendes algo

Crear un agente es cómo se prueba esta habilidad. Cuando un paso aquí era incorrecto o faltaba — un rechazo que encontraste, una clave que te sorprendió — arregla este archivo en el mismo cambio que el agente, en tres líneas como máximo, con el archivo que contiene la regla.