Cómo sincronizar tus agentes de IA en todas tus máquinas (dotfiles + symlinks)

Si usas varios agentes de IA —Claude Code, Codex, OpenCode, Kimi, Qwen Code— seguro ya invertiste tiempo en configurarlos: skills, comandos propios, hooks, servidores MCP. El problema aparece cuando cambias de máquina: una laptop con Mac, un escritorio con Windows, un servidor Linux... y toda esa configuración se queda en una sola.

La buena noticia es que este problema existe desde mucho antes que los agentes de IA, y Linux lo resolvió hace décadas con dos ideas muy simples: dotfiles y symlinks. En esta guía te explico cómo aplicarlas para que lo que configures en una máquina se refleje automáticamente en todas las demás.

Contenido

  1. Todo agente de IA tiene archivos de configuración
  2. Dónde vive la configuración: home o .config
  3. Qué es una carpeta dotfiles
  4. Scripts de instalación para Linux, Mac y Windows
  5. Symlinks: la pieza clave para que todo se mantenga sincronizado
  6. Herramientas que lo hacen por ti: chezmoi, GNU Stow, yadm, Dotbot y Nix
  7. Repositorios públicos vs privados con GitHub CLI
  8. Resumen

Todo agente de IA tiene archivos de configuración

No importa qué herramienta uses: Claude Code, Codex, OpenCode, Kimi, Qwen Code o cualquiera que salga mañana. Todas guardan su configuración en archivos dentro de una carpeta especial en tu directorio de usuario (el home).

Por ejemplo, Claude Code utiliza la carpeta ~/.claude, donde puedes alojar tus skills, comandos, plugins, hooks, subagentes y el archivo CLAUDE.md global. Cada agente tiene la suya:

Agente Carpeta de configuración Archivo principal
Claude Code ~/.claude/ settings.json, CLAUDE.md, skills/
Codex (OpenAI) ~/.codex/ config.toml
OpenCode ~/.config/opencode/ opencode.json, skills/
Qwen Code ~/.qwen/ settings.json
Kimi CLI ~/.kimi/ —

Si entras a tu carpeta de usuario y muestras los archivos ocultos, vas a encontrar varias de estas carpetas. En mi caso tengo .codex, .claude, .railway, .supabase y muchas más porque pruebo muchas herramientas, pero lo normal es que tengas unas 10 o 12 de tus programas más comunes.

Dónde vive la configuración: home o .config

Hay un detalle importante: no todos los programas crean su carpeta directamente en el home. Algunos, como OpenCode, siguen el estándar XDG y guardan todo dentro de ~/.config/. Ahí dentro puedes encontrar ~/.config/opencode, ~/.config/stripe, ~/.config/kilocode, etc.

En resumen, solo hay dos lugares donde buscar:

  • Directamente en el home: ~/.claude, ~/.codex, ~/.qwen
  • Dentro de .config: ~/.config/opencode, ~/.config/nvim, ~/.config/alacritty

Cuando aparezca una herramienta nueva, busca "<herramienta> config" en su documentación y casi siempre te llevará a uno de estos dos patrones.

La tilde ~ significa home

En la documentación vas a ver rutas como ~/.claude/settings.json. La tilde ~ es un atajo de Linux y macOS para tu carpeta de usuario (/home/usuario o /Users/usuario). En Windows equivale a C:\Users\tu-usuario. De hecho, Claude Code documenta que en Windows ~/.claude se resuelve a %USERPROFILE%\.claude.

Qué es una carpeta dotfiles

Los dotfiles son simplemente archivos y carpetas de configuración cuyo nombre empieza con un punto (.bashrc, .gitconfig, .claude). La práctica, muy común en Linux desde hace años, consiste en crear una carpeta llamada dotfiles que contenga solo las partes que quieres versionar de cada programa, y subirla a Git.

Por ejemplo, en mi repositorio público de dotfiles (github.com/fazt/dotfiles) guardo configuraciones de:

  • Claude Code: solo la carpeta skills/
  • Terminales: Alacritty y WezTerm
  • OBS: mi configuración de captura de pantalla
  • Neovim: plugins y keymaps
  • Otros programas de terminal que uso a diario

En el caso de Claude Code no copio toda la carpeta ~/.claude (ahí hay sesiones, caché y datos temporales), solo los skills que son comunes a todos mis proyectos. Algunos ejemplos de los que uso:

  • Un skill para hacer commits y subir versiones automáticamente
  • Un skill de preguntas que obliga al agente a hacerme muchas preguntas antes de construir algo
  • Mi estilo de desarrollo (qué base de datos uso, qué diseño, que no use Server Actions, etc.)
  • Un skill para obtener transcripciones de videos

Cualquiera puede clonar el repo, copiar los skills a su propia carpeta ~/.claude/skills y tenerlos funcionando de inmediato.

💡 A futuro es muy probable que Claude Code, Codex y el resto permitan importar la configuración desde tu cuenta. Pero si usas varias herramientas a la vez, el enfoque de dotfiles sigue siendo la solución más genérica y no depende de ningún proveedor.

Scripts de instalación para Linux, Mac y Windows

Copiar la carpeta skills a mano funciona la primera vez, pero si vas a estar añadiendo y modificando skills constantemente, terminas repitiendo el mismo trabajo. Por eso mi repositorio incluye dos scripts:

  • install.sh para Linux y macOS
  • install.ps1 (PowerShell) para Windows

Ambos hacen lo mismo con distinta sintaxis: copian (o mejor dicho, enlazan) la carpeta skills hacia ~/.claude/skills y también hacia ~/.agents/skills.

¿Por qué también .agents? Claude Code solo lee ~/.claude/skills, pero otros agentes como OpenCode buscan skills en varias rutas: ~/.config/opencode/skills/, ~/.claude/skills/ y ~/.agents/skills/. La carpeta .agents se está convirtiendo en una convención compartida entre herramientas, así que enlazar ahí hace que los mismos skills estén disponibles en Cursor, VS Code, OpenCode y similares.

Y no hace falta escribir estos scripts a mano: puedes pedirle a Codex o a Claude Code que los genere por ti.

Symlinks: la pieza clave para que todo se mantenga sincronizado

Aquí viene la pregunta obvia: "Si copio los skills a ~/.claude/skills y luego los modifico ahí, mi carpeta dotfiles queda desactualizada". Tendrías que sincronizar en dos direcciones.

La solución es el symlink (enlace simbólico). En vez de copiar, creas un acceso directo a nivel de sistema de archivos. La carpeta original dentro de dotfiles es la fuente de verdad, y ~/.claude/skills simplemente apunta a ella. Modifica en cualquiera de los dos lados y el cambio se refleja en ambos, porque en realidad es el mismo archivo.

Linux y macOS

# ln -s <origen> <destino>
ln -s ~/dotfiles/claude/skills ~/.claude/skills
ln -s ~/dotfiles/claude/skills ~/.agents/skills

Windows (PowerShell como administrador o con modo desarrollador activado)

New-Item -ItemType SymbolicLink -Path "$HOME\.claude\skills" -Target "$HOME\dotfiles\claude\skills"
New-Item -ItemType SymbolicLink -Path "$HOME\.agents\skills" -Target "$HOME\dotfiles\claude\skills"

Con esto el flujo completo queda así:

  1. Creas un skill nuevo en cualquier máquina (dentro de dotfiles).
  2. Haces git push.
  3. En la otra máquina ejecutas git pull (o le dices al agente "actualiza mi repo de dotfiles").
  4. Como las carpetas están enlazadas, Claude Code, OpenCode y el resto ya ven el skill nuevo.

Esto aplica a cualquier programa con carpetas .algo, no solo agentes de IA: Neovim, tmux, OpenClaw, Aider, tu terminal, etc.

Herramientas que lo hacen por ti

Lo anterior es la forma manual. Si no quieres mantener tus propios scripts, existen gestores de dotfiles que se encargan de crear los symlinks, manejar diferencias entre sistemas operativos y hasta cifrar secretos. Todos comparten la misma idea base; cambian en complejidad y funciones.

chezmoi

Probablemente el más popular y completo. Se distribuye como un único binario sin dependencias, funciona en Linux, macOS y Windows, y usa una sola rama como fuente de verdad con plantillas para las diferencias entre máquinas. Flujo típico:

chezmoi init https://github.com/fazt/dotfiles.git   # o tu propio repo
chezmoi apply      # aplica la configuración
chezmoi update     # trae cambios del repo y los aplica

Su tabla comparativa es un buen punto de partida para ver el resto de opciones.

GNU Stow (GitHub)

Minimalista y parte del proyecto GNU, lo que atrae a quienes priorizan la licencia libre. Es un "symlink farm manager": organizas tu repo en paquetes y stow claude crea los enlaces en tu home. No tiene plantillas ni cifrado; hace una sola cosa y la hace bien.

yadm

Yet Another Dotfiles Manager. Es básicamente un wrapper sobre Git (yadm init, yadm clone, yadm commit), pero añade archivos alternativos por sistema operativo y cifrado de archivos sensibles como llaves o tokens, con yadm encrypt / yadm decrypt.

Dotbot

Herramienta ligera para hacer bootstrap de dotfiles en un solo paso. Defines los enlaces en un archivo YAML/JSON y se instala como submódulo de tu repo, así que soporta repos dentro de otros repos.

Nix Home Manager y NixOS

Home Manager lleva la idea un paso más allá: describes tu entorno de usuario en un archivo de configuración declarativo (lenguaje Nix) y no solo gestiona archivos, sino también los paquetes instalados. Y si quieres el extremo, NixOS es un sistema operativo completo donde toda tu máquina es un dotfile: programas, dependencias y servicios definidos en un archivo. Instalas NixOS en una máquina nueva, le pasas tu configuración y queda idéntica. Esto es lo que se conoce como sistema operativo declarativo.

¿Cuál elegir?

Herramienta Symlinks Plantillas por SO Cifrado Gestiona paquetes Windows
Scripts propios ✅ manual ❌ ❌ ✅
chezmoi copia (no symlink) ✅ ✅ ❌ ✅
GNU Stow ✅ ❌ ❌ ❌ ⚠️ (vía WSL/MSYS)
yadm no (Git directo) ✅ ✅ ❌ ⚠️
Dotbot ✅ ❌ ❌ ❌ ✅
Home Manager ✅ ✅ (Nix) ⚠️ (con extras) ✅ ❌

Si trabajas en Windows, Mac y Linux a la vez, chezmoi o tus propios scripts suelen ser el camino más cómodo. Si solo usas Linux/Mac y quieres simplicidad, GNU Stow.

Repositorios públicos vs privados con GitHub CLI

Compartir tus dotfiles en un repo público es útil para que otros aprovechen tus skills. Pero si tienes configuraciones con programas propios, rutas internas o llaves, no tienen por qué ser públicas.

Con GitHub CLI puedes autenticarte en cualquier máquina nueva y clonar repos privados sin configurar SSH:

gh auth login
gh repo clone tu-usuario/dotfiles-private ~/dotfiles-private

Lo que yo hago es mantener dos repositorios: uno público con los skills y configuraciones genéricas, y uno privado con lo sensible. Según la máquina instalo uno u otro: en un servidor de desarrollo basta el público; en una máquina donde corre un asistente de IA personal instalo también el privado. Tú puedes tener solo uno privado si prefieres; la idea es la misma.

Resumen

  • Todo agente de IA guarda su configuración en una carpeta .algo en tu home (~/.claude, ~/.codex, ~/.qwen) o dentro de ~/.config (~/.config/opencode).
  • Una carpeta dotfiles versionada en Git te permite llevar esas configuraciones a cualquier máquina.
  • Los symlinks (ln -s en Linux/Mac, New-Item -ItemType SymbolicLink en Windows) hacen que la carpeta del repo y la carpeta del agente sean la misma, así nunca se desincronizan.
  • Enlaza también a ~/.agents/skills para que tus skills funcionen en OpenCode, Cursor y otros agentes.
  • Si no quieres mantener scripts, usa chezmoi, GNU Stow, yadm, Dotbot o Home Manager.
  • Con GitHub CLI puedes combinar un repo público con uno privado.

La clave del video es entender qué son los dotfiles y usar symlinks para que las carpetas donde instalas tus configuraciones se mantengan siempre actualizadas. Una vez lo tienes, añadir una máquina nueva es cuestión de clonar un repo y correr un script.

Enlaces útiles

Patrocinador del video: Brevo, plataforma para centralizar email marketing, automatizaciones, SMS, WhatsApp y CRM en un solo lugar. Con el código FAZT50 obtienes 50 % de descuento los primeros 3 meses en los planes Starter y Standard (solo usuarios nuevos).

Si tienes dudas o sugerencias para un próximo video, déjalas en los comentarios. Y si necesitas ayuda con tu setup, en fazt.dev puedes reservar una asesoría personalizada.