Skills para agentes de codificación

Archyl incluye 11 skills para agentes de codificación que llevan toda tu arquitectura a tu agente de codificación: Claude Code, Codex, Cursor o cualquier herramienta compatible. En lugar de alternar entre tu editor y el panel de Archyl, tu agente puede validar los cambios antes de que escribas código, documentar lo que se ha publicado, revisar pull requests contra tu modelo C4 y anticipar la deriva arquitectónica, todo desde la terminal.

Las skills son de código abierto y están disponibles en github.com/archyl-com/agent-skills.

El flujo de arquitectura nativo de IA

Las 11 skills trabajan juntas para formar un ciclo continuo de arquitectura:

preflight → code → review → CI (GitHub Actions) → postship → generate context
    ↑                                                              |
    └──────────────────────────────────────────────────────────────┘
Paso Skill Qué ocurre
Antes de programar archyl-preflight Valida el enfoque que planeas contra la arquitectura
Mientras programas archyl-developer Más de 200 herramientas MCP para modelado, ADRs, gobernanza y operaciones
Antes de fusionar archyl-review Revisa la PR contra el modelo C4 y las reglas de conformidad
En CI GitHub Actions Ejecuta las comprobaciones de conformidad automáticamente
Después de publicar archyl-postship Actualiza el modelo C4, crea ADRs y solicitudes de cambio
Bajo demanda archyl-changelog Muestra la cronología de la arquitectura
Ante la deriva archyl-autofix Propone correcciones cuando se detecta deriva
Analítica archyl-dora, archyl-roi, archyl-predict Métricas, ROI y previsiones
Multiagente archyl-orchestrate Coordina a los agentes en torno a contratos de API y dependencias

Requisitos previos

  • Una cuenta de Archyl con acceso a la API
  • Una clave API (obtenla desde Perfil > Claves API en el panel de Archyl)
  • Claude Code, Codex, Cursor o un agente de codificación compatible

Instalación

Paso 1: Añadir el marketplace

Ejecuta el siguiente comando en Claude Code:

/plugin marketplace add archyl-com/agent-skills

Luego configura las actualizaciones automáticas:

  1. Ejecuta /plugin
  2. Selecciona Marketplaces
  3. Elige archyl-marketplace
  4. Selecciona Enable auto-update

Paso 2: Instalar el plugin

/plugin install archyl-developer@archyl-marketplace

El plugin archyl-developer instala las 11 skills y el hook del Guard. Reinicia tu agente de codificación después de la instalación.

Paso 3: Configurar el servidor MCP

Añade el servidor MCP de Archyl al archivo .mcp.json de tu proyecto:

{
    "mcpServers": {
        "archyl": {
            "type": "http",
            "url": "https://api.archyl.com/mcp",
            "headers": {
                "X-API-Key": "arch_your_api_key_here"
            }
        }
    }
}

Reemplaza arch_your_api_key_here con tu clave API real del panel de Archyl.

Otros agentes de codificación

Los archivos de las skills son compatibles con cualquier agente que soporte el formato de plugins. También puedes usarlos directamente desde el repositorio agent-skills con Cursor, Codex u otras herramientas.

Configuración rápida

La forma más rápida de empezar es el script de configuración. Genera todos los archivos de configuración que necesita tu agente.

El script de configuración

Ejecútalo desde la raíz de tu proyecto:

npx archyl-setup

Esto crea tres archivos:

Archivo Propósito
CLAUDE.md Instrucciones para Claude Code: le indica al agente que use las skills de Archyl e incluye el ID de tu proyecto y el contexto de arquitectura
.cursorrules Instrucciones para Cursor: el mismo contenido adaptado al formato de Cursor
AGENTS.md Instrucciones para Codex y otros agentes: el mismo contenido en un formato genérico

Plantilla: CLAUDE.md

El CLAUDE.md generado incluye instrucciones como estas:

# Architecture

This project is documented in Archyl (project ID: `proj_xxx`).

## Before coding
Run `/archyl-preflight` to validate your approach against the architecture.

## After shipping
Run `/archyl-postship` to update the C4 model and create ADRs.

## Architecture rules
Always run `/archyl-review` before requesting a code review.

Puedes personalizar estas plantillas para adaptarlas al flujo de trabajo de tu equipo.

Skills principales

archyl-developer

La skill fundamental. Da a tu agente un conocimiento estructurado de las más de 200 herramientas MCP de Archyl en estos dominios:

Dominio Capacidades
Modelado C4 Crear y gestionar sistemas, contenedores, componentes, elementos de código y relaciones
Documentación Registros de decisiones de arquitectura, documentación de proyectos, flujos de usuario/sistema, insights de IA
Gobernanza Reglas de conformidad, detección de deriva, métricas DORA, mapa de propiedad
Operaciones Releases, entornos, contratos de API, canales de eventos, radar tecnológico
Colaboración Comentarios, solicitudes de cambio, pizarras, gestión de equipos
Historial Instantáneas, viaje en el tiempo, comparación de arquitecturas, registros de auditoría
Integraciones Webhooks, widgets del marketplace, vistas de arquitectura global

Ejemplos de prompts:

Create a new system called PaymentPlatform with containers for
the API server, a PostgreSQL database, and a React frontend.

Create an ADR titled "Migrate from REST to gRPC for internal services".
Set it as proposed, explain the context around latency requirements,
and link it to the ApiGateway and PaymentService containers.

Show me the technology radar. Add Temporal as an adopted workflow
orchestration technology and tag it on the OrderProcessing container.

archyl-preflight

Ejecútala antes de empezar a programar para validar el enfoque que planeas contra la arquitectura existente. Preflight contrasta tu plan con el modelo C4, las reglas de conformidad y los ADRs recientes para detectar infracciones cuanto antes.

Ejemplos de prompts:

/archyl-preflight I'm planning to add a new Redis cache between the
API server and the database to reduce read latency.

/archyl-preflight We want to split the UserService into separate
authentication and profile services.

La skill señala problemas como infracciones de dependencias, conflictos de nombres o enfoques que contradicen ADRs existentes, antes de que escribas una sola línea de código.

archyl-postship

Ejecútala después de publicar para actualizar automáticamente tu documentación de arquitectura. Analiza qué cambió en el código base y:

  • Actualiza el modelo C4 (nuevos contenedores, componentes y relaciones)
  • Crea ADRs para las decisiones importantes
  • Abre solicitudes de cambio para que el equipo las revise cuando hace falta

Ejemplos de prompts:

/archyl-postship We just shipped the Redis caching layer.
Update the architecture to reflect the new cache container
and its relationships.

/archyl-postship Document the authentication service split
we shipped this sprint.

archyl-harness

El protocolo de sesiones de trabajo para programar bajo gobernanza: la skill que hay detrás del Archyl Harness. Enseña a tu agente el ciclo completo: plan_work antes de empezar, start_work_session para obtener un contexto enfocado y reservas consultivas, remember/recall para el grafo de conocimiento del proyecto, y finish_work_session con un resultado que puede abrir una solicitud de cambio de arquitectura.

Work under the harness: plan, declare a session, respect the
guardrails, and finish with an honest summary.

Skills de revisión y gobernanza

archyl-review

Un bot de revisión de arquitectura estructurado. Analiza los diffs contra tu modelo C4, tus reglas de conformidad y tus ADRs para aportar comentarios de revisión de código conscientes de la arquitectura.

Ejemplos de prompts:

/archyl-review Review the current branch against the architecture.
Flag any conformance violations or undocumented dependencies.

/archyl-review Check if PR #42 introduces any new cross-system
dependencies that aren't in the C4 model.

archyl-changelog

Genera un changelog de arquitectura: una cronología de cambios que incluye ADRs, releases, comprobaciones de conformidad, eventos de deriva y actualizaciones del modelo.

Ejemplos de prompts:

/archyl-changelog Show the architecture timeline for the last month.

/archyl-changelog What changed in the PaymentPlatform system
since the v2.0 release?

archyl-autofix

Cuando se detecta deriva entre tu código y tu documentación de arquitectura, autofix propone correcciones concretas, ya sea en el código o en el modelo, para volver a sincronizarlos.

Ejemplos de prompts:

/archyl-autofix We have drift on the PaymentService container.
Propose fixes to resolve it.

/archyl-autofix Show all current drift issues and suggest
the fastest path to zero drift.

Skills de inteligencia

archyl-dora

Correlaciona los cambios de arquitectura con las métricas de rendimiento de entrega DORA. Descubre cómo influyen las decisiones arquitectónicas en la frecuencia de despliegue, el lead time, la tasa de fallos en cambios y el tiempo medio de recuperación.

Ejemplos de prompts:

/archyl-dora Show DORA metrics for the last quarter.
Did the microservice split improve deployment frequency?

/archyl-dora Correlate recent architecture changes
with our change failure rate trend.

archyl-roi

Calcula el impacto económico de las decisiones de arquitectura. Estima el tiempo ahorrado, los incidentes evitados y los cambios en la productividad de los desarrolladores gracias a las mejoras arquitectónicas.

Ejemplos de prompts:

/archyl-roi What's the estimated ROI of our migration
from monolith to microservices?

/archyl-roi Calculate the cost of our current architectural
drift vs the cost of fixing it.

archyl-predict

Anticipa problemas arquitectónicos antes de que ocurran. Usa las tendencias históricas para predecir la deriva, las regresiones de DORA y los puntos críticos de complejidad.

Ejemplos de prompts:

/archyl-predict Which components are most likely to drift
in the next 30 days?

/archyl-predict Based on current trends, will our deployment
frequency regress this quarter? Which services are at risk?

Orquestación

archyl-orchestrate

Coordina varios agentes que trabajan sobre el mismo código base. Gestiona la negociación de contratos de API entre servicios y la resolución de conflictos de dependencias, y se asegura de que los agentes no hagan cambios de arquitectura contradictorios.

Ejemplos de prompts:

/archyl-orchestrate Two agents are modifying services that share
an API contract. Coordinate the changes to avoid conflicts.

/archyl-orchestrate Agent A is adding a new field to the
UserService API. Check if Agent B's PaymentService integration
will break.

Esta skill es especialmente útil en configuraciones multiagente en las que cada agente es responsable de servicios distintos y necesita negociar contratos compartidos sin pisar el trabajo de los demás.

Paquetes de reglas de conformidad

Archyl incluye paquetes de reglas de conformidad predefinidos para patrones de arquitectura habituales: microservicios, orientada a eventos, por capas y más. Estos paquetes de reglas funcionan con todas las skills anteriores para hacer cumplir tu arquitectura automáticamente.

Consulta la guía de reglas de conformidad para conocer los paquetes de reglas disponibles y cómo crear reglas personalizadas.

SDKs

Si quieres integrar Archyl en herramientas propias más allá de los agentes de codificación, hay SDKs disponibles para TypeScript, Python y Go.

Consulta la documentación del servidor MCP para ver los detalles de los SDKs y la referencia de la API.

Cómo funciona

Cada skill proporciona a tu agente de codificación un conocimiento estructurado sobre herramientas MCP concretas de Archyl, incluidos sus parámetros, los valores esperados y las buenas prácticas. Cuando le pides a tu agente que realice una tarea de arquitectura, este:

  1. Identifica qué herramientas MCP invocar según el conocimiento de la skill
  2. Construye los parámetros correctos (IDs de proyecto, tipos de elementos, tipos de relaciones)
  3. Encadena varias llamadas para flujos de trabajo complejos
  4. Devuelve un resumen de lo que se ha creado, modificado o señalado

El agente siempre comienza llamando a list_projects para descubrir los proyectos disponibles y obtener el projectId necesario para las operaciones posteriores.

Referencia del modelo C4

Las skills comprenden los 4 niveles del modelo C4:

Nivel Elemento Ejemplo
1 System "Payment Platform", "Email Service"
2 Container "API Server", "PostgreSQL Database", "React Frontend"
3 Component "AuthService", "PaymentProcessor", "UserRepository"
4 Code "PaymentGateway interface", "processPayment()"

Tipos de relaciones

Al conectar elementos, el agente utiliza el tipo de relación apropiado:

Tipo Caso de uso
uses Dependencia general entre sistemas
calls Llamadas síncronas HTTP/gRPC
sends_to / consumes_from Mensajería asíncrona (colas, eventos)
reads_from / writes_to Acceso a base de datos
implements / extends Herencia a nivel de código

Contribuir

Las skills son de código abierto. Puedes contribuir de las siguientes formas:

  • Corrigiendo nombres de herramientas, parámetros o descripciones
  • Añadiendo cobertura para nuevas funcionalidades de Archyl
  • Mejorando los ejemplos de flujos de trabajo
  • Creando nuevos archivos de skills para otros casos de uso

Consulta la guía de contribución para más detalles.