Primeros pasos con Sharkly en 10 minutos

Empezar a usar Sharkly lleva unos diez minutos: conecta una Computadora, crea un Agente y asígnale una Tarea pequeña. Sharkly es un sistema de gestión del trabajo para Personas y Agentes. Convierte herramientas de programación con IA como Claude Code y Codex en compañeros de equipo asignables dentro de un sistema de tareas compartido, para que la ejecución deje de desaparecer en terminales privadas. Esta es la primera puesta en marcha completa:

1. Inicia sesión y crea (o únete a) una Organización con un Espacio activo.
2. Conecta una Computadora mediante Sharkly Desktop o la CLI de Sharkly.
3. Confirma que al menos un Runtime, como Claude Code, aparezca como disponible.
4. Crea un Agente con un rol acotado e instrucciones claras.
5. Escribe una Tarea pequeña y bien delimitada, y asígnala al Agente.
6. Revisa el resultado en la Tarea y responde con un comentario de seguimiento.

El resto de esta guía recorre cada paso en orden, explica los cuatro conceptos que hay detrás y muestra qué comprobar cuando termina la primera ejecución. Al final tendrás un ciclo de trabajo que podrás ampliar hacia ejecuciones en paralelo, Skills compartidos y Sprints.

Por qué importan los primeros diez minutos con Sharkly

La mayoría de los equipos ya usan agentes de programación con IA. El problema es dónde ocurre ese trabajo: en la terminal de una sola persona, invisible para todos los demás. Alguien pega un ticket de Jira en una ventana de chat, ejecuta un agente, vuelve a pegar el diff y el razonamiento detrás del cambio no queda registrado en ninguna parte. Multiplica eso por cinco desarrolladores y tres herramientas de agentes distintas, y obtendrás resultados sin registros.

Sharkly aborda esto desde el lado del equipo. No es otro agente de programación. El planteamiento oficial es tajante respecto al límite: Sharkly no sustituye a Claude Code, Codex ni otras herramientas de ejecución. Añade la capa compartida de tareas, contexto, control y revisión alrededor de las herramientas que tu equipo ya usa. Esas herramientas se encargan de la ejecución; Sharkly gestiona la asignación, las Computadoras conectadas, el contexto de las tareas, el progreso, los bloqueos, los resultados y la revisión humana en todas ellas.

Por eso los primeros diez minutos están estructurados así. No estás instalando una IA nueva. Estás conectando la IA que ya tienes a un sistema de registro compartido, para que cada ejecución mantenga visibles el contexto, el progreso, los bloqueos, los resultados y la revisión humana desde la solicitud hasta la entrega. Si prefieres empezar por el posicionamiento general, lee ¿Qué es Sharkly? y vuelve después; esta guía se mantiene en lo práctico.

Los cuatro conceptos detrás de cualquier configuración de Sharkly

Cuatro sustantivos sostienen todo el modelo. Si los tienes claros, nada de lo que venga después te confundirá.

Una Tarea es la unidad principal de trabajo en Sharkly. Registra el objetivo y la descripción, el estado, la prioridad, las etiquetas, la persona responsable, el Agente o Crew asignado a ejecutarla, los comentarios, los archivos adjuntos y el estado y la traza completos de la ejecución.

Un Agente es una configuración de trabajo guardada, no un prompt puntual. La configuración cuidadosa de una persona (instrucciones, repositorios vinculados, entorno, tiempos de espera) pasa a ser reutilizable en todo el Espacio cuando se comparte el Agente.

Una Computadora aporta el host de ejecución. Un pequeño servicio local la conecta a Sharkly, detecta las herramientas de agentes instaladas, recibe trabajo, prepara el directorio de la tarea, inicia el Runtime seleccionado y transmite el progreso de vuelta. El servicio local inicia la conexión hacia fuera, por lo que una configuración típica no necesita ningún puerto de entrada.

Esta separación de responsabilidades es el diseño: el Agente define cómo debe abordarse el trabajo, la Computadora aporta el host y los recursos locales, el Runtime ejecuta la sesión y la Tarea sigue siendo el registro compartido para el equipo. Tu código y tus credenciales permanecen en máquinas que tú controlas.

Lo que necesitas antes de empezar

La lista de requisitos previos es corta:

• una cuenta de Sharkly y una Organización;
• al menos un Espacio activo;
• un ordenador capaz de ejecutar Sharkly Desktop o el servicio local;
• un Runtime compatible instalado y autenticado en esa máquina, como Claude Code, Codex o Gemini CLI;
• acceso a Git en esa máquina si tu primera Tarea toca un repositorio privado.

Dos aclaraciones sobre el lado de los modelos. Primero, trae tu propia suscripción: el uso de modelos sigue gestionándose a través de las suscripciones o claves de API configuradas en esas herramientas, y tu cuota depende de los planes y cuentas que conecte tu equipo. Segundo, el Agente sigue el modelo predeterminado del Runtime. No ofrece un selector de modelo; cambias de modelo en la configuración del propio Runtime, no en el Agente.

Puedes organizar Tareas sin una Computadora conectada. Sin embargo, un Agente no puede ejecutar trabajo hasta que haya un Runtime apto en línea, así que conectar uno es el paso uno por algo.

Si tu Organización aún no tiene ningún Espacio activo, Sharkly te guiará para crear uno. Elige una categoría de trabajo para generar tipos de tarea sensatos: el desarrollo de software empieza con Requisito, Error, Tarea e Historia de usuario. El primer Espacio es público para la Organización de forma predeterminada, y puedes restringir el acceso más adelante.

Paso 1: Conecta una Computadora

Abre Ajustes, luego Computadoras y elige Conectar Computadora. Hay dos caminos que cubren a casi todo el mundo:

• Sharkly Desktop para un ordenador personal compatible. Instálalo, inicia sesión y él registrará la máquina e iniciará el servicio local por ti.
• La CLI de Sharkly más el servicio local para un host remoto o una máquina Linux. Genera un token de instalación de un solo uso en el diálogo de conexión y ejecuta el comando generado en la máquina de destino:

sharkly computer register --install-token sit_9f2ka7x1mrq8

El token de instalación es efímero y de un solo uso. No lo incluyas en una imagen reutilizable, un script, una Tarea ni un comentario. Además, tiene una única función muy concreta: un token de instalación registra una Computadora y no crea un inicio de sesión humano en la CLI. Los tokens de acceso personal (empiezan por shk_) se encargan de eso por separado.

Espera a que la Computadora aparezca como conectada y luego revisa su página de detalle. Cada Runtime detectado informa de un estado de capacidad: Disponible, Necesita configuración, No instalado o No compatible. Esta distinción te ahorra la confusión inicial más habitual. Que una Computadora esté en línea solo significa que su servicio local está enviando señales de actividad. No significa que el Runtime que has seleccionado pueda ejecutar una Tarea. Si más adelante una ejecución no arranca, comprueba el estado de capacidad del Runtime antes de ponerte a diagnosticar la conexión.

También puedes verificarlo desde la terminal:

sharkly computer list
sharkly computer show cmp_4c81d2
sharkly computer ping cmp_4c81d2 rt_claude_code

La documentación de Computadoras cubre en profundidad los diagnósticos, los Runtimes personalizados, la visibilidad y los ajustes de limpieza.

Paso 2: Crea tu primer Agente

Abre Agentes y selecciona Nuevo Agente. Resiste la tentación de construir un asistente que lo haga todo. Empieza con un rol acotado, porque una descripción enfocada indica a las Personas qué pueden asignarle, mientras que las instrucciones le dicen al Agente cómo trabajar.

Una buena primera configuración sería así:

• Nombre: Lector de código
• Descripción: Lee un repositorio, explica la implementación actual e informa de riesgos sin modificar archivos.
• Visibilidad: Personal, o el Espacio donde se usará el Agente
• Computadora y Runtime: la conexión que verificaste en el paso 1

En cuanto a las instrucciones, vale la pena copiar casi literalmente el ejemplo del Quickstart:

Lee la Tarea completa y los comentarios relevantes antes de actuar. Limita el alcance a lo solicitado. Para la primera Tarea, no edites archivos. Informa de lo que inspeccionaste, de las pruebas que respaldan cada conclusión y de todo lo que siga siendo incierto.

Fíjate en lo que cubren las instrucciones: el alcance, cómo inspeccionar antes de actuar y el formato del informe. Ese es el nivel de abstracción correcto. Pon el comportamiento estable en las instrucciones del Agente, los requisitos específicos de cada Tarea en la descripción de la Tarea, y los procedimientos reutilizables que comparten varios Agentes en un Skill. Mantener esas tres capas separadas es lo que hace que un Agente sea reutilizable en lugar de frágil.

Paso 3: Añade un repositorio o directorio de trabajo

Si tu Agente va a leer código, necesita código que leer. Dos opciones:

• Vincular un repositorio Git al Agente (o confiar en los repositorios configurados para el Espacio de la Tarea). Las ejecuciones respaldadas por repositorio pueden preparar un git worktree nuevo para cada Tarea, que es lo que hace posible más adelante una ejecución en paralelo segura.
• Configurar un directorio local específico en una Computadora local. Las ejecuciones reutilizan el código, las dependencias, las cachés y las herramientas que ya están ahí en lugar de preparar una copia nueva.

La regla de decisión: usa directorios temporales respaldados por worktree para la mayor parte del trabajo con repositorios y siempre que varias Tareas puedan modificar el mismo código en paralelo. Usa un directorio específico cuando una ejecución necesite un entorno que sea caro de reconstruir, y recuerda que un directorio específico atiende a una sola ejecución a la vez. Hemos publicado una explicación completa sobre cómo los worktrees evitan que los agentes en paralelo se pisen entre sí si quieres conocer los detalles técnicos.

Paso 4: Escribe una Tarea que un Agente pueda ejecutar

Crea una Tarea en el mismo Espacio. El ejemplo del Quickstart es deliberadamente aburrido, y de eso se trata:

Título: Revisar la ruta de error de autenticación

Descripción: Lee la implementación actual de autenticación e identifica tres casos de fallo visibles para el usuario. No modifiques archivos. Para cada caso, cita el archivo o componente correspondiente y explica el comportamiento esperado. Termina con cualquier pregunta que deba responderse antes de implementar.

Esta Tarea tiene las tres propiedades que toda buena primera Tarea necesita. Tiene un límite claro (leer, no editar). Produce un resultado revisable (tres casos con pruebas). Y es de bajo riesgo, así que puedes evaluar el criterio del Agente sin poner en peligro tu base de código. Si tu repositorio no tiene código de autenticación, cambia el tema por cualquier área pequeña que sí exista, como la carga de configuración o un componente de estado vacío.

Asignar trabajo a software de esta forma se siente distinto a escribir un prompt, y así debe ser. Un prompt es una conversación; una Tarea es un contrato con un resultado revisable. Cuando este ciclo funcione, la misma forma escala a tickets reales: nuestro tutorial sobre asignar un ticket de Jira a un agente de IA muestra la versión de producción.

Paso 5: Asigna la Tarea y observa la ejecución

Abre el control de Asignado de la Tarea y elige tu Agente. Las Personas, los Agentes y los Crews pueden ser Asignados; al seleccionar un Agente, este pasa a ser el asignado para la ejecución.

Una regla de estado determina cuándo empieza la ejecución. Una Tarea asignada a un Agente no inicia una ejecución mientras permanece en Backlog. El Backlog es un área de espera donde se prepara el trabajo. Mueve la Tarea a un estado listo para trabajar (sin empezar o iniciado) y Sharkly pondrá la ejecución en cola cuando la Computadora y el Runtime estén listos. Los estados Completado, Cancelado y Duplicado nunca inician una primera ejecución.

Mientras avanza la ejecución, la Tarea muestra su estado de ejecución: en cola, despachada, en ejecución y, después, completada, fallida o cancelada. Una ejecución respaldada por repositorio puede tardar un momento en extraer el código y preparar antes su directorio aislado. Tienes tres vistas:

• Chat para el intercambio tipo comentarios con el Agente;
• Actividad para ver los comentarios y los cambios de la Tarea en una sola línea temporal;
• Ejecuciones para el historial de ejecuciones y la traza completa: llamadas a herramientas, eventos del Runtime, origen del disparo y detalles de los fallos.

El estado de la ejecución y el estado de la Tarea están relacionados, pero son distintos. Una ejecución puede estar En ejecución mientras el estado de la Tarea sigue diciendo En curso, porque uno describe el avance de la ejecución y el otro la posición en el flujo de trabajo.

Paso 6: Revisa el resultado como un revisor, no como un espectador

La respuesta final del Agente vuelve a la Tarea como un comentario vinculado a su traza de ejecución. Aquí es donde empieza el lado humano del contrato: los Agentes investigan, ejecutan, prueban e informan. Las Personas marcan la dirección, conceden autoridad y aceptan el resultado.

Comprueba que el Agente:

• haya inspeccionado el código o el material de origen previsto;
• se haya mantenido dentro del límite de no editar;
• haya aportado pruebas para cada conclusión;
• haya registrado la incertidumbre en lugar de suponer;
• haya dejado en la Tarea un resultado sobre el que un compañero pueda actuar.

Si necesita otra pasada, responde con un comentario concreto. Un comentario apto en una Tarea aún asignada a ese Agente inicia una ejecución de seguimiento, y los comentarios rápidos se agrupan para que no se creen ejecuciones pendientes duplicadas. Si el Agente necesita tu opinión o tu revisión, esa solicitud puede aparecer en tu Bandeja de entrada, que separa los elementos que requieren tu respuesta de las novedades de menor prioridad.

Cuando el resultado se sostiene, marca la Tarea como completada. Eso cierra el primer ciclo que sigue la lista de comprobación de la configuración: Computadora conectada, Agente creado, repositorio listo, Tarea creada, asignada y completada.

Después del primer ciclo: cinco formas de ampliar la configuración

La primera ejecución demuestra que la fontanería funciona. Los siguientes movimientos añaden una dimensión cada uno.

¿Cómo ejecutar más de una Tarea a la vez?

Aumenta la concurrencia de forma deliberada. Con directorios temporales, la concurrencia predeterminada es la mitad del límite de la Computadora; cada Tarea recibe un worktree aislado para que las ejecuciones en paralelo no choquen. Vigila la CPU, la memoria y la capacidad de tu proveedor de modelos antes de subir los límites, y lee cómo los equipos ejecutan varias sesiones de Claude Code en paralelo para ver la comparación con configuraciones caseras.

¿Cuándo conviene usar el Chat de Agentes en lugar de una Tarea?

Sharkly mantiene dos superficies a propósito. Usa el Chat para explorar, planificar o investigar con un Agente antes de que el trabajo necesite seguimiento. Usa una Tarea cuando el trabajo necesite responsabilidad, estado, historial de ejecución o revisión. Si ves que un Chat produce algo sobre lo que el equipo debe actuar, promociónalo a una Tarea para que el resultado quede registrado.

¿Cuándo necesitas un Crew?

Un Crew es un grupo reutilizable de Personas y Agentes coordinado por un Agente líder. Para trabajos pequeños y bien definidos, asigna la Tarea directamente a un Agente y mantén las piezas móviles en cero. Usa un Crew cuando el líder necesite interpretar un objetivo, involucrar a miembros especialistas y reunir sus resultados en una única Tarea.

¿Cuándo es mejor un Skill que editar las instrucciones?

Cuando varios Agentes necesitan el mismo procedimiento (una lista de comprobación para revisiones, un patrón de migración, un formato de informe), conviértelo en un Skill y vincúlalo donde haga falta. El oficio de un desarrollador se convierte en infraestructura para toda la organización en lugar de quedarse en un prompt privado.

¿Y el resto del equipo?

Todo lo anterior funciona en solitario. El beneficio se multiplica cuando las Tareas viven en Espacios compartidos, los Sprints agrupan el trabajo en ciclos y los compañeros revisan la producción de los Agentes en las mismas vistas que ya usan para el trabajo humano. La capa de proyectos de Sharkly (Espacios, Proyectos, Sprints, vistas kanban y de lista) es lo bastante estándar como para que nadie necesite formación adicional.

Cuándo Sharkly no es la herramienta adecuada (por ahora)

Un límite honesto te ahorra tiempo. Si eres un único desarrollador ejecutando un solo agente en un solo repositorio, puede que hoy con una terminal y una rama te baste. La capa de coordinación se gana su lugar cuando las ejecuciones se multiplican: más de un agente, más de una persona que necesita ver los resultados, o trabajo que requiere revisión antes de fusionarse.

La misma lógica se aplica a las herramientas que hayas construido tú mismo. Las sesiones de tmux y los scripts de worktree caseros funcionan de verdad; los equipos los dejan atrás cuando las partes invisibles (quién ejecutó qué, adónde fue a parar el diff, quién lo aprobó) empiezan a costar más de lo que ahorran los scripts. Y si tu equipo vive de principio a fin dentro del ecosistema de un único proveedor, evalúa primero la orquestación propia de ese proveedor. El argumento de Sharkly es más fuerte cuando mezclas herramientas, máquinas y personas, porque se mantiene neutral con las tres. Encontrarás más contexto sobre la categoría en ¿Qué es la programación agéntica? si estás trazando el mapa del sector.

Lo que no cambia en ninguno de estos casos: conserva las herramientas que tu equipo ya usa. La vía de adopción de Sharkly consiste en añadir una capa visible y revisable alrededor de ellas, no en sustituir el flujo de trabajo que hay debajo.

Tres primeras ejecuciones que funcionan en la práctica

El equipo de plataforma prudente. Un ingeniero de DevEx conecta una Computadora Linux compartida, crea un Agente Lector de código de solo lectura y deja que sus compañeros asignen Tareas de investigación durante una semana. Nadie concede acceso de escritura hasta que los informes demuestren ser fiables. La adopción se extiende porque las trazas de ejecución hacen que el criterio del Agente sea inspeccionable.

El desarrollador en solitario que escala. Un desarrollador conecta un portátil, crea dos Agentes (uno para implementar y otro para revisar) y empieza a encauzar errores pequeños mediante Tareas en lugar de prompts improvisados. La ganancia inmediata no es la velocidad, sino que cada corrección tiene ahora una descripción, un diff, una traza y un registro de lo que se comprobó.

El equipo centrado en Jira. Un responsable de ingeniería mantiene Jira como fuente de verdad de la planificación y conecta Sharkly para que los tickets se conviertan en Tareas ejecutables. Los desarrolladores dejan de copiar y pegar el contexto de los tickets en las terminales. Los resultados, los bloqueos y las solicitudes de revisión vuelven a la Tarea, donde el responsable puede verlos.

Tus próximos diez minutos

El flujo de trabajo más pequeño y útil de Sharkly es deliberadamente pequeño: conecta una Computadora, crea un Agente y asigna una Tarea de bajo riesgo. Todas las capacidades avanzadas (worktrees en paralelo, Crews, Skills, Automatizaciones, Sprints) se construyen sobre ese ciclo sin modificarlo.

Así que pon el ciclo en marcha. Conecta una Computadora, crea un Agente y asígnale algo aburrido. Revisa el resultado como revisarías el primer PR de un compañero nuevo: con atención, un límite claro y una pregunta de seguimiento. Después decide, según las pruebas, qué conceder a continuación. El Quickstart de la documentación refleja estos pasos con capturas de pantalla actualizadas para cuando quieras empezar.

Preguntas frecuentes

¿Qué agentes de programación funcionan con Sharkly?

Sharkly detecta las herramientas de agentes compatibles instaladas en una Computadora conectada y las informa como un Runtime cada una. Claude Code, Codex, Gemini CLI y OpenCode están entre las herramientas mencionadas en la documentación oficial. La página de detalle de la Computadora muestra el conjunto admitido actualmente para tu máquina, con un enlace a la guía de instalación de cada Runtime, y puedes añadir un Runtime ACP personalizado si una herramienta no se detecta automáticamente.

¿Sharkly sustituye a Claude Code o Codex?

No. Sharkly no sustituye a Claude Code, Codex ni otras herramientas de ejecución. Esas herramientas realizan la sesión del agente propiamente dicha en tu Computadora. Sharkly añade la capa compartida a su alrededor: asignación a nivel de equipo, contexto de la tarea, progreso, resultados y revisión humana. Sigues usando las herramientas de agentes y las cuentas que ya tienes.

¿Cuánto cuesta Sharkly?

El modelo de Sharkly es traer tu propia suscripción: el uso de modelos se gestiona a través de las suscripciones o claves de API configuradas en tus herramientas de agentes, y tu cuota depende de los planes que conecte tu equipo. Para conocer los planes actuales del producto, consulta sharkly.ai directamente, ya que este artículo no hace seguimiento de los precios.

¿Mi código y mis credenciales pasan por los servidores de Sharkly?

La ejecución ocurre en las Computadoras que conectas: tu portátil, tus servidores o tus contenedores. La Computadora aporta el sistema operativo, los archivos, las credenciales y las herramientas, y el servicio local transmite el progreso y los resultados de vuelta a la Tarea. Los repositorios se obtienen con el acceso a Git configurado en esa Computadora.

¿Por qué mi Agente no inicia una ejecución?

Comprueba tres causas habituales en orden. Primera, puede que la Tarea esté en Backlog; las Tareas asignadas esperan ahí hasta que se mueven a un estado listo para trabajar. Segunda, puede que el Runtime no sea utilizable; una Computadora en línea solo confirma que llegan señales de actividad, así que abre el detalle de la Computadora y revisa el estado de capacidad del Runtime. Tercera, puede que la capacidad esté al máximo; un Agente en línea puede seguir poniendo trabajo en cola cuando se alcanzan los límites de concurrencia o de directorios.

¿Pueden dos Agentes trabajar en el mismo repositorio a la vez?

Sí, con directorios de trabajo temporales. Cada Tarea recibe un directorio aislado, y las ejecuciones respaldadas por repositorio preparan un git worktree independiente por ejecución, lo que reduce las interferencias entre Tareas concurrentes. Los directorios específicos son lo contrario: una ruta configurada atiende a una ejecución a la vez.

¿Puedo ejecutar Agentes de Sharkly en un servidor remoto?

Sí. Instala la CLI de Sharkly y el servicio local en el host remoto y luego regístralo con un token de instalación de un solo uso desde la página de Computadoras. El servicio local se conecta hacia fuera con Sharkly, así que una configuración típica no necesita ningún puerto de entrada. Las Computadoras remotas van bien para capacidad compartida del equipo; los portátiles, para experimentar en solitario.

¿Cuál debería ser mi primera Tarea?

Algo de solo lectura, con un límite claro y un resultado revisable. La documentación sugiere revisar una ruta de error de autenticación e informar de tres casos de fallo visibles para el usuario con pruebas, sin editar archivos. Cualquier área pequeña y real de tu base de código sirve. Evita primeras Tareas vagas como «mejorar el código»; no puedes revisar lo que no has delimitado.