cachyos-hyprland

name	cachyos-hyprland
description	Use this skill for any task on the user's CachyOS + Hyprland desktop environment. Trigger when the user mentions: CachyOS, Hyprland, Wayland, hyprctl, hyprland.lua, ~/.config/hypr, pacman, paru, AUR, the Hypr ecosystem (hyprlock, hypridle, hyprpaper, hyprpicker, hyprcursor, hyprlauncher, hyprsunset, hyprpolkitagent, xdg-desktop-portal-hyprland), waybar, wofi, rofi, mako, dunst, kitty, foot, or any desktop customization on this Linux setup. Routes to specialized satellite skills and provides shared context (Hyprland 0.55+ with Lua syntax, CachyOS rolling release, recently installed pristine system, Spanish-speaking user).
compatibility	opencode
metadata	{"audience":"end-user","scope":"routing","language":"es"}

cachyos-hyprland (skill principal)

Hub de enrutamiento y contexto compartido para el entorno de escritorio del usuario: CachyOS rolling release + Hyprland 0.55+ con sintaxis Lua.

Quick context

• Sistema: CachyOS (Arch-based, rolling release), recién instalado, pristine.
• Compositor: Hyprland 0.55+ (Wayland). Sintaxis de config: Lua, no .conf.
• Archivo principal: ~/.config/hypr/hyprland.lua.
• Ecosistema oficial Hypr (hyprlock, hypridle, hyprpaper, …) sigue usando hyprlang/INI (.conf). Solo Hyprland core migró a Lua.
• Idioma de trabajo del usuario: español. Las respuestas al usuario van en español.
• Lema operativo: "make no mistakes" — confirma sintaxis y comandos contra los docs locales o la wiki antes de proponer cambios.

When to use this skill

• Cualquier consulta sobre el entorno: configuración, debugging, customización, instalación de apps, troubleshooting.
• Como "primer responder": este skill establece el contexto y enruta a satélites específicos.

When NOT to use

• Tareas fuera del entorno Linux del usuario (macOS host, otras distros, dev unrelated).
• Consultas sobre Excel, navegación web casual, etc. — no son del dominio.

Skills satélite y routing

Tarea del usuario	Satélite a consultar	Archivo de referencia principal
Editar hyprland.lua (binds, monitors, animations, rules, layouts)	hyprland-config	references/example-hyprland.lua, references/docs-wiki/basics/*.md
Migrar config viejo .conf a Lua	hyprland-config	references/migration-table.md
Lockscreen, idle, wallpapers, lanzador (hypr*)	hypr-ecosystem	references/docs-wiki/<componente>.md
Waybar, wofi/rofi, mako/dunst, kitty/foot, screenshots	wayland-utilities	references/docs-third-party/<utility>.md
Instalar paquete, cambiar kernel, snapper, repos	cachyos-system	references/docs-cachyos/<page>.md
Recompensa: combinaciones (e.g., "que SUPER+L abra hyprlock")	hyprland-config + hypr-ecosystem	el bind va en hyprland.lua; la app es ecosistema

Cuando el usuario hace una consulta, identifica el dominio y consulta el satélite correspondiente para detalles técnicos. Este skill principal no duplica contenido — apunta.

Shared environment facts (canonical paths)

~/.config/hypr/hyprland.lua         # Hyprland core (Lua)
~/.config/hypr/hyprlock.conf        # lock screen (hyprlang)
~/.config/hypr/hypridle.conf        # idle daemon (hyprlang)
~/.config/hypr/hyprpaper.conf       # wallpapers (hyprlang)
~/.config/hypr/hyprsunset.conf      # color temperature
~/.config/hypr/hyprlauncher.conf    # launcher
~/.config/waybar/config.jsonc       # waybar (JSON-with-comments)
~/.config/waybar/style.css          # waybar CSS
~/.config/wofi/config               # wofi
~/.config/wofi/style.css
~/.config/mako/config               # mako notifications
~/.config/kitty/kitty.conf          # kitty terminal
~/.local/share/hyprland/hyprland.log   # log de Hyprland

Hyprland 0.55+ Lua syntax cheat sheet

Para que la IA siempre escriba sintaxis válida; ejemplo mínimo:

-- ~/.config/hypr/hyprland.lua
hl.monitor({ output = "", mode = "preferred", position = "auto", scale = "auto" })

hl.config({
    general    = { gaps_in = 5, gaps_out = 10, border_size = 2, layout = "dwindle" },
    decoration = { rounding = 8, blur = { enabled = true, size = 3, passes = 1 } },
    input      = { kb_layout = "es", follow_mouse = 1 },
    animations = { enabled = true },
})

hl.env("XCURSOR_SIZE", "24")

local mod = "SUPER"
hl.bind(mod .. " + Q",     hl.dsp.exec_cmd("kitty"))
hl.bind(mod .. " + C",     hl.dsp.window.close())
hl.bind(mod .. " + V",     hl.dsp.window.float({ action = "toggle" }))
hl.bind(mod .. " + left",  hl.dsp.focus({ direction = "left" }))
for i = 1, 10 do
    local k = i % 10
    hl.bind(mod .. " + " .. k,         hl.dsp.focus({ workspace = i }))
    hl.bind(mod .. " + SHIFT + " .. k, hl.dsp.window.move({ workspace = i }))
end

hl.on("hyprland.start", function()
    hl.exec_cmd("waybar")
    hl.exec_cmd("hyprpaper")
end)

hl.window_rule({ match = { class = "pavucontrol" }, float = true })

Reglas absolutas:

• Nunca uses sintaxis bind = SUPER, Q, exec, kitty (eso es hyprlang, eliminado en 0.55+).
• Nunca crees archivos hyprland.conf para Hyprland core. Sí .conf para los del ecosistema (hyprlock, hypridle, …).
• Nunca asumas que algo "funciona igual que antes"; valida contra references/docs-wiki/ del skill correspondiente o vía python3 ~/.config/opencode/skills/hyprland-config/scripts/search_hyprland_docs.py <término>.

Verification commands (el usuario los corre en CachyOS)

hyprctl version                                # confirmar 0.55+
hyprctl monitors                               # listar monitores activos
hyprctl reload                                 # recargar config sin reiniciar
hyprctl clients                                # listar ventanas abiertas
hyprctl getoption general:gaps_in              # leer valor actual

pacman -Q | grep -E '^(hyprland|hypr|waybar|wofi|mako|kitty)'
systemctl --user status hypridle hyprpolkitagent hyprpaper
ls -la ~/.config/hypr/

Output guidelines

• Idioma: siempre responder al usuario en español, técnico pero claro.
• Cambios destructivos: antes de sobreescribir un archivo del usuario, muestra el diff o ofrece backup (cp file file.bak).
• Citas: cuando propongas un cambio, enlaza al doc local relevante (e.g., references/docs-wiki/basics/binds.md) para que el usuario lo pueda verificar.
• No instalar a ciegas: para paru -S o pacman -S, indica qué hace el paquete y verifica que existe (pacman -Ss <nombre> o consultar AUR).
• Skeptic, no agreeable: si el usuario propone algo que rompe Wayland/Hyprland (e.g., flags X11 o sintaxis hyprlang antigua), corrígelo explicando por qué.
• Modular: si una respuesta requiere varios componentes, dejar claro qué archivo edita cada cambio.

Update workflow

Cuando wiki.hypr.land o wiki.cachyos.org publican cambios, refrescar docs locales:

python3 ~/.config/opencode/skills/hyprland-config/scripts/search_hyprland_docs.py --update
python3 ~/.config/opencode/skills/hypr-ecosystem/scripts/search_hyprland_docs.py --update
python3 ~/.config/opencode/skills/wayland-utilities/scripts/search_hyprland_docs.py --update
python3 ~/.config/opencode/skills/cachyos-system/scripts/search_hyprland_docs.py --update

Cada uno re-descarga desde su fuente vía r.jina.ai y valida tamaño mínimo. También se puede actualizar una sola sección: --update binds.