Habilidade de Construção de Tema

Seleciona, instala e ativa um tema de bloco Full Site Editing (FSE) do WP.org com base na descrição de site em linguagem natural do usuário. Esta habilidade consulta a API de Temas do WP.org v1.2 para temas FSE, avalia os resultados em relação ao prompt de linguagem natural usando o julgamento contextual do Claude e instala a melhor correspondência. Uma lista de fallback curada fornece uma seleção de tema garantida quando a API retorna resultados ruins ou está indisponível.

Sequenciamento crítico: Esta habilidade é executada APÓS a build-mcp Seção 2 (adaptador MCP ativado, banco de dados reexportado) e ANTES de build-content (a semeadura de conteúdo requer que o tema esteja ativo para descoberta de localização de menu).

Esta habilidade espera que as seguintes variáveis já estejam definidas pelo comando chamador:

BUILD_DIR — caminho absoluto para o diretório de construção (definido por build-scaffold Seção 2)
WP — o prefixo do comando WP-CLI (ex.: wp --path=$BUILD_DIR ou o equivalente Docker, definido por build-scaffold Seção 4)
NL_PROMPT — a string de descrição do site em linguagem natural do usuário
SITE_TITLE — título do site derivado do prompt de linguagem natural (definido pelo comando chamador antes desta habilidade)

Seção 1: Consulta à API de Temas do WP.org

Consulte a API de Temas do WP.org v1.2 para obter o pool de temas de bloco FSE. Use a tag full-site-editing para filtrar — este é o sinal público canônico para temas FSE/de bloco. NÃO combine os parâmetros search e tag: a API ignora tags quando search está presente. Claude avalia a relevância do tema em contexto após buscar o pool.

echo "[Build] Consultando API de Temas do WP.org para pool de temas FSE..."

# PADRÃO ANTI-PADRÃO CRÍTICO: NÃO use ?action=query_themes&request[search]=...&request[tag][]=full-site-editing
# A API ignora tag[] quando search está presente. Use consulta apenas com tag; Claude avalia a relevância em contexto.

FSE_THEMES_FILE="/tmp/fse_themes_$$.json"

curl -s --max-time 10 \
  "https://api.wordpress.org/themes/info/1.2/?action=query_themes&request[tag][]=full-site-editing&request[browse]=popular&request[per_page]=50&request[fields][active_installs]=true&request[fields][rating]=true&request[fields][description]=true&request[fields][tags]=true" \
  -o "$FSE_THEMES_FILE"
CURL_EXIT=$?

# Validar resposta — verificar código de saída, arquivo não vazio e estrutura JSON
API_AVAILABLE=false
if [ $CURL_EXIT -eq 0 ] && [ -s "$FSE_THEMES_FILE" ]; then
  # Contar temas na resposta — necessário pelo menos 3 para Claude avaliar adequadamente
  THEME_COUNT=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(len(d.get('themes', [])))" "$FSE_THEMES_FILE" 2>/dev/null || echo "0")
  if [ "$THEME_COUNT" -ge 3 ]; then
    API_AVAILABLE=true
    echo "[Build] API do WP.org retornou $THEME_COUNT temas FSE para avaliação."
  else
    echo "[Build] API do WP.org retornou menos de 3 temas ($THEME_COUNT). Usando lista de fallback."
  fi
else
  echo "[Build] API do WP.org indisponível — usando lista de temas curada"
fi

Seção 2: Avaliação e Seleção do Tema

Claude lê a resposta JSON da API e avalia cada tema em relação ao NL_PROMPT. Se a API retornou um pool viável, Claude seleciona a melhor correspondência usando relevância, popularidade e classificação. Se a API falhou ou retornou poucos resultados, Claude seleciona da lista de fallback curada com base na categoria do site em NL_PROMPT.

Critérios de pontuação (em ordem de prioridade):

Nome, descrição e relevância das tags para o tipo de site descrito em NL_PROMPT
active_installs — sinal de popularidade (maior = melhor)
rating — sinal de qualidade (maior = melhor)

Temas clássicos nunca são selecionados, mesmo que tivessem pontuação mais alta em outras métricas.

if [ "$API_AVAILABLE" = "true" ]; then
  echo "[Build] Avaliando temas FSE em relação ao prompt: \"$NL_PROMPT\""
  echo "[Build] Lendo temas de: $FSE_THEMES_FILE"

  # Claude lê o JSON dos temas FSE e avalia cada tema:
  # - themes[].name: nome de exibição
  # - themes[].slug: slug de instalação no WP.org
  # - themes[].description: descrição do tema
  # - themes[].tags: tags de recurso/categoria do tema
  # - themes[].active_installs: popularidade (número de instalações ativas)
  # - themes[].rating: classificação de qualidade (escala 0-100)
  #
  # Claude seleciona o tema com a melhor combinação de:
  # (1) relevância para o tipo de site do NL_PROMPT
  # (2) alto active_installs
  # (3) alta rating
  #
  # Comportamento sem correspondência: Se nenhum tema pontuar bem contra o tipo de site do NL_PROMPT,
  # Claude apresenta os 3 principais candidatos ao usuário e pede que ele escolha.
  # Isso interrompe intencionalmente o fluxo autônomo — satisfação > automação.
  #
  # Após a seleção, Claude define:
  THEME_SLUG="<slug selecionado por Claude dos resultados da API>"
  THEME_NAME="<nome de exibição selecionado por Claude dos resultados da API>"

else
  # Lista de fallback curada — mapeia categorias de site para slugs de temas compatíveis com FSE
  # Estes temas são temas de bloco FSE verificados e mantidos no WP.org.
  # Atualize esta lista se um tema for removido do WP.org.
  #
  # Categoria → Mapeamentos de Slug (Claude extrai a categoria do site do NL_PROMPT):
  #
  # portfólio / fotografia / criativo → flavor
  # negócios / corporativo / agência  → flavor
  # blog / revista / notícias          → flavor
  # restaurante / comida / café        → flavor
  # ecommerce / loja / armazém         → flavor
  # padrão (qualquer outro)            → twentytwentyfour
  #
  # twentytwentyfour é o fallback de último recurso garantido (mantido pela equipe principal do WordPress.org).
  #
  # Claude lê o NL_PROMPT, determina a categoria do site e define:
  THEME_SLUG="<slug selecionado por Claude da lista de fallback curada>"
  THEME_NAME="<nome de exibição para o tema curado selecionado>"
fi

echo "[Build] Tema selecionado: $THEME_NAME ($THEME_SLUG)"

Seção 3: Instalação e Ativação do Tema

Instale e ative o tema selecionado usando WP-CLI. Se a instalação falhar, tente candidatos de fallback. Sempre valide a compatibilidade FSE verificando a presença de theme.json após a instalação. Use aviso-e-continue — nunca interrompa a construção por falhas de tema.

echo "[Build] Instalando tema: $THEME_SLUG..."

install_theme() {
  local slug="$1"
  if $WP theme install "$slug" --activate 2>&1; then
    echo "[Build] Tema instalado e ativado: $slug"

    # Validação FSE — verificar presença de theme.json
    # Claude selecionou do pool FSE, então esta é uma confirmação secundária.
    # Falso negativo possível se theme.json estiver em um subdiretório ou com nome diferente.
    if [ -f "$BUILD_DIR/wp-content/themes/$slug/theme.json" ]; then
      echo "[Build] FSE validado: theme.json encontrado."
    else
      echo "[Build] AVISO: theme.json não encontrado — o tema pode não ser compatível com FSE."
      echo "[Build] Prosseguindo — Claude selecionou este tema do pool da tag full-site-editing."
    fi

    # Obter versão do tema
    THEME_VERSION=$($WP theme get "$slug" --field=version 2>/dev/null || \
      grep -m 1 "^Version:" "$BUILD_DIR/wp-content/themes/$slug/style.css" 2>/dev/null | \
      sed 's/Version: //' | tr -d '[:space:]' || \
      echo "desconhecida")

    THEME_INSTALLED=true
    echo "[Build] Tema instalado e ativado: $slug (v$THEME_VERSION)"
    return 0
  else
    echo "[Build] AVISO: Falha na instalação do tema para o slug: $slug"
    THEME_INSTALLED=false
    return 1
  fi
}

# Tentativa 1: Instalar tema selecionado pela API ou curado
if ! install_theme "$THEME_SLUG"; then
  # Tentativa 2: Se o tema selecionado pela API falhou, tentar fallback curado
  if [ "$API_AVAILABLE" = "true" ]; then
    echo "[Build] Tentando tema de fallback curado para a categoria do site..."
    # Claude determina o slug de fallback curado a partir da categoria do site do NL_PROMPT
    # (veja lista curada da Seção 2) e tenta novamente
    FALLBACK_SLUG="twentytwentyfour"  # Claude substitui isso pelo slug específico da categoria, se aplicável
    if ! install_theme "$FALLBACK_SLUG"; then
      # Tentativa 3: Último recurso — twentytwentyfour (mantido pelo WordPress.org)
      if [ "$FALLBACK_SLUG" != "twentytwentyfour" ]; then
        echo "[Build] Tentando fallback de último recurso: twentytwentyfour..."
        if ! install_theme "twentytwentyfour"; then
          # Fallback final — registrar aviso e continuar com o tema padrão do WordPress
          echo "[Build] AVISO: Todas as tentativas de instalação de tema falharam."
          echo "[Build] AVISO: A construção continua com o tema padrão do WordPress."
          THEME_SLUG="default"
          THEME_NAME="WordPress Padrão"
          THEME_VERSION="desconhecida"
          THEME_INSTALLED=false
        fi
      else
        # twentytwentyfour já falhou — continuar com o padrão
        echo "[Build] AVISO: Todas as tentativas de instalação de tema falharam."
        echo "[Build] AVISO: A construção continua com o tema padrão do WordPress."
        THEME_SLUG="default"
        THEME_NAME="WordPress Padrão"
        THEME_VERSION="desconhecida"
        THEME_INSTALLED=false
      fi
    fi
  else
    # Tema curado falhou — tentar twentytwentyfour como último recurso
    if [ "$THEME_SLUG" != "twentytwentyfour" ]; then
      echo "[Build] Tentando fallback de último recurso: twentytwentyfour..."
      if ! install_theme "twentytwentyfour"; then
        echo "[Build] AVISO: Todas as tentativas de instalação de tema falharam."
        echo "[Build] AVISO: A construção continua com o tema padrão do WordPress."
        THEME_SLUG="default"
        THEME_NAME="WordPress Padrão"
        THEME_VERSION="desconhecida"
        THEME_INSTALLED=false
      fi
    else
      echo "[Build] AVISO: Todas as tentativas de instalação de tema falharam."
      echo "[Build] AVISO: A construção continua com o tema padrão do WordPress."
      THEME_SLUG="default"
      THEME_NAME="WordPress Padrão"
      THEME_VERSION="desconhecida"
      THEME_INSTALLED=false
    fi
  fi
fi

# Limpar arquivo de resposta temporário da API
rm -f "$FSE_THEMES_FILE"

Seção 4: Atualização do Título do Site

Atualize o título e a tagline do site WordPress para corresponder ao site descrito em NL_PROMPT. O título do site já foi definido durante a instalação do WP em build-scaffold (--title="$SITE_TITLE"), mas esta etapa permite que a tagline seja definida com uma descrição contextual gerada a partir do prompt de linguagem natural.

echo "[Build] Definindo título e tagline do site..."

# Atualizar título do site (pode já corresponder ao --title do build-scaffold, mas atualizar para confirmar)
$WP option update blogname "$SITE_TITLE" 2>&1

# Claude gera uma tagline breve (uma linha, sem aspas) a partir do NL_PROMPT
# Exemplos:
#   NL_PROMPT: "um site de portfólio para um fotógrafo freelancer"
#   → Tagline: "Capturando momentos que importam"
#
#   NL_PROMPT: "um site de restaurante para um bistrô italiano em Sydney"
#   → Tagline: "Sabores italianos autênticos no coração de Sydney"
#
# Claude define SITE_TAGLINE com a tagline gerada, então:
SITE_TAGLINE="<tagline gerada por Claude a partir do NL_PROMPT>"
$WP option update blogdescription "$SITE_TAGLINE" 2>&1

echo "[Build] Título do site definido: $SITE_TITLE"
echo "[Build] Tagline do site definida: $SITE_TAGLINE"

Notas de Implementação

Posição na pipeline: Esta habilidade é executada na pipeline de construção em linguagem natural estritamente APÓS build-mcp Seção 2 (adaptador MCP ativado, banco de dados reexportado) e ANTES de build-content. O tema deve estar ativo antes da semeadura de conteúdo porque build-content usa $WP menu location list para descobrir as localizações de navegação do tema ativo — isso requer que o tema alvo já esteja instalado e ativo.

Contêiner Docker MySQL: O contêiner Docker MySQL efêmero de build-scaffold Seção 3 ainda deve estar em execução quando esta habilidade for executada. A instalação do tema pelo WP-CLI escreve na tabela de opções do WordPress (slug do tema ativo). A armadilha EXIT definida em build-scaffold Seção 3 permanece ativa durante toda a sessão de construção e é acionada apenas quando o comando completo sai — não entre invocações de habilidades.

Variáveis de saída: As seguintes variáveis são definidas por esta habilidade e consumidas por habilidades downstream (build-content, build-setup):

THEME_SLUG — slug do tema instalado (ex.: twentytwentyfour, flavor)
THEME_NAME — nome de exibição (ex.: Twenty Twenty-Four, Flavor)
THEME_VERSION — string da versão instalada (ex.: 1.3, desconhecida se não detectável)
THEME_INSTALLED — true se a instalação foi bem-sucedida, false se todos os fallbacks falharam

Manutenção da lista de fallback curada: A lista curada mapeia categorias de site para temas de bloco FSE conhecidos no WP.org. Se um slug de tema curado for removido do WP.org (fazendo com que wp theme install falhe com "não encontrado"), atualize esta lista com um substituto compatível com FSE atual. twentytwentyfour é o fallback de último recurso garantido — é mantido pela equipe principal do WordPress.org e não será removido.

Nenhuma personalização pós-instalação (decisão bloqueada): Conforme decisão do usuário capturada em CONTEXT.md, nenhuma substituição de theme.json, temas filhos ou modificações de Estilos Globais são aplicadas após a instalação. O tema é instalado e ativado como está do WP.org. Seu design integrado permanece conforme fornecido.

Confiabilidade da validação FSE: A verificação de theme.json é uma confirmação secundária — Claude já filtrou temas pela tag full-site-editing na consulta à API. Uma mensagem "AVISO: theme.json não encontrado" não indica um erro: o tema pode armazenar theme.json em um local não padrão, ou a tag do WP.org pode ter sido definida corretamente, mas a verificação do caminho do arquivo falhou. A construção continua independentemente.

Referências:

@references/wp-block-themes/SKILL.md — estrutura de tema FSE, esquema theme.json, padrões de bloco de template
@references/wp-wpcli-and-ops/SKILL.md — referência de comando de tema WP-CLI, flag --activate, saída --field

dr-robert-li/cowork-wordpress-expert

O que é cowork-wordpress-expert?

Perguntar na sua IA favorita

Documentação

Habilidade de Construção de Tema

Seção 1: Consulta à API de Temas do WP.org

Seção 2: Avaliação e Seleção do Tema

Seção 3: Instalação e Ativação do Tema

Seção 4: Atualização do Título do Site

Notas de Implementação

Individual skills in this repo

dr-robert-li/cowork-wordpress-expert

Habilidades Relacionadas

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me