Executar

Inicia um site ou aplicativo local e o visualiza em um navegador real. Detecta a stack a partir de package.json, arquivos de configuração ou um index.html simples, escolhe uma porta livre, inicia o servidor de desenvolvimento ou um servidor estático, aguarda até que ele realmente responda, tira uma captura de tela ou o abre no navegador e o para novamente com uma flag. Use quando o usuário pedir para executar, servir, lançar, visualizar, iniciar ou abrir um projeto localmente, verificar uma página no navegador, tirar uma captura de tela de um site, ou quando uma compilação precisa ser vista antes de ser julgada.

O que é Executar?

Esta skill oferece o caminho mais curto entre uma pasta local e uma página renderizada em um navegador real. Ela detecta automaticamente a stack do projeto a partir de arquivos como package.json, index.html ou diretórios de saída de build, inicia o servidor apropriado (dev server ou servidor estático) em uma porta livre, e permite interagir com a página abrindo o navegador, tirando uma captura de tela (via Playwright) ou simplesmente verificando se o servidor responde. A skill é compatível com ferramentas como Node.js/npm, Python http.server, e projetos estáticos, e gerencia todo o ciclo de vida do servidor: inicia, aguarda a resposta HTTP, registra logs e estado em arquivos .run/, e oferece uma flag --stop para encerrar limpa e seguramente o processo, evitando servidores órfãos. É ideal para desenvolvedores que precisam testar rapidamente alterações visuais, verificar rotas ou validar builds antes de julgar o resultado final.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/itsdanylol/claude-sitecraft/tree/HEAD/skills/run

Installed? Explore more Produtividade e Colaboração skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Executar faz?

Um site só está pronto quando é visto em execução. O código-fonte diz o que alguém pretendia; o navegador diz o que uma pessoa realmente obtém. Esta skill é o caminho mais curto entre uma pasta e uma página renderizada.

Execute

node <pasta-da-skill>/scripts/serve.mjs <dir> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
  • --detect imprime o que encontrou e não inicia nada. Faça isso primeiro quando a pasta for desconhecida.
  • --port começa a procurar na porta indicada e pega a próxima porta livre, para que dois projetos possam ser executados ao mesmo tempo.
  • --open abre o navegador padrão.
  • --shot out.png renderiza a página com 1440 pixels de largura, altura total, usando Playwright.
  • --stop mata a árvore de processos a partir de .run/state.json.

Ele escreve .run/state.json (pid, porta, url, comando) e .run/server.log ao lado do projeto. Esses dois arquivos são toda a transferência entre o início e a parada.

O que ele detecta

EncontraExecuta
package.json com dev, start, serve ou previewnpm run <esse script> em uma porta livre, com PORT definida
index.html na raizpython -m http.server nessa pasta
public/index.html, dist/index.html, build/index.htmlum servidor estático enraizado na saída compilada
Um arquivo de configuração mas sem scriptsrelata e para: o projeto precisa de seu próprio comando
go.mod, Cargo.toml, pubspec.yamlrelata e para: use o próprio comando de execução do projeto

Detalhes específicos de frameworks, portas padrão e modos de falha que vale a pena conhecer: references/stacks.md.

Lendo o resultado

O script prova três coisas e nada mais: um processo foi iniciado, uma porta respondeu, uma página foi renderizada. O que ele não pode lhe dizer:

  • se o layout está correto em 375, 768 e 1440 (use sitecraft/scripts/verify.mjs para isso)
  • se o console está limpo (não é capturado aqui; verify.mjs captura)
  • se a página da qual tirou a captura de tela é a página que o usuário queria (verifique a URL em relação à rota que você solicitou)

Portanto, o ciclo é: serve.mjs --shot, olhe a imagem com seus próprios olhos, corrija, tire novamente. Três renderizações é o limite para uma passagem; além disso, o problema é o plano, não o CSS.

Regras

  • Nunca deixe um servidor em execução. Pare-o quando a verificação for concluída, ou diga claramente que ele ainda está ativo e em qual porta. Um servidor de desenvolvimento perdido na máquina do usuário é uma bagunça que ele precisa limpar.
  • Não inicie o que você não pode parar. Se o projeto precisar de Docker, um banco de dados ou uma chave de API paga, diga isso antes de iniciar qualquer coisa.
  • Informe a URL real. localhost:4173, não "o aplicativo". Se a porta mudou porque 4173 estava ocupada, diga a nova.
  • Leia o log antes de adivinhar. Uma falha na inicialização é quase sempre uma dependência ausente, uma variável de ambiente faltando ou uma porta já em uso. .run/server.log tem a resposta, e citar o erro real é melhor que uma teoria.
  • Sem instalações sem avisar. Se node_modules estiver faltando, npm install geralmente é a solução, e também é uma mutação do projeto deles. Faça, depois diga que foi executado, ou pergunte uma vez quando a instalação for grande.
  • Estático sobre framework. Quando uma saída compilada existe e está atualizada, servir dist/ é mais rápido e mais fiel do que o servidor de desenvolvimento.

Quando não vai iniciar

  1. Leia .run/server.log e cite o primeiro erro real, não a última linha.
  2. Dependências ausentes: npm install no projeto, depois tente novamente.
  3. Variável de ambiente ausente: procure por .env.example, nomeie o que é necessário, e pare se um valor for secreto e estiver ausente.
  4. Porta já em uso: o script já avança para a próxima porta livre; uma porta fixa na configuração do framework é a causa habitual quando ainda falha.
  5. Etapa de compilação necessária: execute npm run build primeiro, depois sirva dist/.
  6. Nativo ou containerizado: devolva o comando que o projeto documenta. Nem toda stack é um script.

Lista de verificação

  • Detectou a stack em vez de assumir uma
  • Iniciou e viu uma resposta HTTP real, não apenas um processo gerado
  • Informou a URL e porta exatas
  • Olhou para uma captura de tela, não apenas para o log
  • Verificou se a rota corresponde à página que era esperada
  • Parou, ou disse que ainda está em execução e onde
  • Citou o erro real quando falhou

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Habilidades Relacionadas