goromal/agent-skills

Use ao fazer ou implantar alterações na configuração do NixOS ou em qualquer pacote/módulo do anixpkgs. Abrange o fluxo de trabalho editar-implantar-testar e pegadas comuns.

O que é agent-skills?

Esta skill é essencial para agentes de IA que precisam modificar e implantar configurações do NixOS ou pacotes/módulos do repositório `anixpkgs`. Ela define um fluxo de trabalho claro de três etapas: editar o módulo ou script relevante, preparar novos arquivos com `git add` para garantir que sejam copiados pelo `git-cc` durante a implantação, e implantar via API `anix-upgrade-ui` (recomendado) ou CLI como fallback. A skill documenta detalhes cruciais, como a necessidade do campo `"local": true` para que as alterações em módulos do NixOS tenham efeito, e explica como evitar problemas comuns: módulos devem ser importados no local correto, novas opções precisam ser declaradas em `opts.nix` e atribuídas em `pc-base.nix`, e servidores MCP requerem reexecução do script `claude-setup`. Além disso, fornece uma referência completa da API para implantação remota, incluindo o uso de hashes de commit em vez de branches para evitar cache do CDN, e instruções para monitorar execuções via SSE e logs. Suportada por máquinas NixOS rodando `anix-upgrade-ui`, a skill permite edição, teste e implantação eficientes, seja localmente ou em máquinas remotas.

Funciona com✓Claude Code~Codex CLI~Cursor

npx skills add https://github.com/goromal/agent-skills/tree/HEAD/skills/anixpkgs-deploy

Documentação

Esta máquina executa NixOS; toda a configuração do sistema está no repositório anixpkgs, clonado em ~/sources/anixpkgs (canônico) e possivelmente em outro caminho (ex.: /data/andrew/dev/claude/sources/anixpkgs). As árvores atuais são implantadas por meio de sua configuração flake; anix-upgrade mantém o caminho baseado em canais para árvores mais antigas.

Fluxo de trabalho

Edite o módulo Nix ou script Python/shell relevante em pkgs/.
Prepare novos arquivos — git-cc (usado por anix-upgrade) copia apenas arquivos rastreados (git ls-files). Primeiro, execute git add nos novos arquivos, caso contrário eles estarão silenciosamente ausentes na compilação.

Implante via API local do anix-upgrade-ui (recomendado), com streaming até a conclusão:

upgrade_host="$(hostname).local"
curl -si "http://${upgrade_host}/anix-upgrade/api/v1/run" -X POST \
  -H 'Content-Type: application/json' \
  -d '{"source": "/caminho/para/anixpkgs", "local": true}'
# 202 → {"run_id": "<uuid>", "started": true};  409 → já em execução
curl -N "http://${upgrade_host}/anix-upgrade/api/v1/stream/<run_id>"
# termina com [UPGRADE BEM-SUCEDIDO] ou [UPGRADE FALHOU (código N)], depois [FIM]

Use o nome de host .local da máquina, não localhost: o nginx expõe esta rota apenas no host virtual específico da máquina. Alternativa via CLI (apenas se a API estiver inacessível): anix-upgrade --local -s /caminho/para/anixpkgs.

Teste o resultado nesta máquina antes de confirmar (commitar).

"local": true é obrigatório sempre que a alteração tocar em um pacote de serviço ou módulo do NixOS — sem ele, o anix-upgrade deixa dependencies.nix com local-build = false, então os padrões cfg.package do módulo resolvem para o binário da tag publicada e a alteração silenciosamente não tem efeito.

Pegadas importantes

Módulos do NixOS devem ser importados no local correto (ex.: lista de importações do pc-base.nix) — adicionar um arquivo não é suficiente.
Novas opções devem ser declaradas em pkgs/nixos/components/opts.nix e atribuídas em pc-base.nix antes de serem usadas em componentes como base-dev-pkgs.nix.
Servidores MCP são registrados por usuário via claude mcp add -s user ...; o script claude-setup (em base-dev-pkgs.nix) cuida disso e deve ser reexecutado após adicionar um servidor.

Implantando em outras máquinas / Referência da API

A mesma API é executada em toda máquina que hospeda anix-upgrade-ui: http://<hostname>.local/anix-upgrade/api/v1/ (sem autenticação). Campos do corpo de run (todos opcionais): version, commit, branch, source (caminho local), local, boot — mesma semântica das flags do anix-upgrade. Use -si para que os cabeçalhos de resposta sejam exibidos (alguns proxies removem corpos JSON com -s).

Para uma máquina remota, primeiro faça o push e passe commit (um hash completo), não branch — tarballs de branch são armazenados em cache no CDN e podem estar desatualizados por minutos mesmo com --tarball-ttl 0; um hash de commit usa fetchGit baseado em conteúdo e ignora o CDN:

curl -si -X POST http://<hostname>.local/anix-upgrade/api/v1/run \
  -H 'Content-Type: application/json' \
  -d "{\"commit\": \"$(git rev-parse HEAD)\", \"local\": true}"

Monitore uma execução (o run_id retorna 404 assim que uma execução mais nova inicia, então obtenha os logs antes de acionar novamente):

curl -s  .../api/v1/status/<run_id> | jq .   # status: running (em execução)|success (sucesso)|failed (falha)
curl -N  .../api/v1/stream/<run_id>          # SSE: reproduz os últimos 512 KB, depois ao vivo
curl -o upgrade.log .../api/v1/log/<run_id>  # log completo

As execuções aparecem na interface web em http://<hostname>.local/anix-upgrade/ com um selo via API; apenas uma execução por máquina por vez (API e interface manual se bloqueiam mutuamente).