agentleFS
lucaspaesbrazil-lablucaspaesbrazil-lab/agencia-digital-showcase/.claude/skills/performance-optimizer/SKILL.md

performance-optimizer

Skill0 starsChanged 4 months agoMITView on GitHub

Monitoramento contínuo e régua de otimização de mídia paga, com estado entre execuções — sabe o que já foi sinalizado/decidido no ciclo anterior. Use para ciclos recorrentes de acompanhamento ("monitora minha conta", "roda o ciclo de otimização", "o que mudou desde o último check", disparo agendado de performance) — diferente de ads-analyst, que é auditoria pontual sem memória de execução.

17 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use observability-engineer, security-auditor and 5 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • xfstudioSkill

    observability-engineer

    Build production-ready monitoring, logging, and tracing systems.

    Also in 3 projects that use this

  • nahisahoSkill

    security-auditor

    security-auditor skill

    Also in 5 projects that use this

  • lodetomasiSkill

    database-optimizer

    Database performance optimization: N+1 detection, query analysis, indexing, and ORM tuning

    Also in 3 projects that use this

  • AutumnsGroveSkill

    api-designer

    Design and document RESTful and GraphQL APIs with OpenAPI/Swagger specifications, authentication patterns, versioning strategies, and best practices. Use for: (1) Creating API specifications, (2) Designing REST endpoints, (3) GraphQL schema design, (4) API authentication and authorization, (5) API versioning strategies, (6) Documentation generation

    Also in 3 projects that use this

  • GoogleSkill

    code-reviewer

    Also in 5 projects that use this

  • xenitV1Skill

    clean-code

    Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments

    Also in 3 projects that use this

The file

Files
SKILL.md

Performance Optimizer — Monitoramento Contínuo e Régua de Otimização

Roda ciclos recorrentes de acompanhamento de mídia paga para um cliente específico, comparando cada ciclo com o anterior. Ao contrário de ads-analyst (snapshot isolado a cada chamada), esta skill tem memória: sabe o que já foi sinalizado, o que já foi proposto e ainda aguarda decisão, e o que já foi executado — seja pelo usuário via MCP, seja por uma automação externa (ex: Make.com).

Quando usar esta skill

Ativar quando o usuário:

  • Pedir para "monitorar", "acompanhar" ou "rodar o ciclo de otimização" de uma conta
  • Disparar /performance-check [cliente]
  • For um disparo agendado (rotina schedule / /loop) configurado para acompanhamento contínuo
  • Perguntar "o que mudou desde o último check" ou "tem alguma pendência de aprovação"

Não usar para uma auditoria pontual sem necessidade de comparar com histórico — nesse caso use ads-analyst ou campaign-audit.

ETAPA 1 — Carregar estado anterior

Antes de puxar qualquer dado novo, leia o que já existe para este cliente:

1. clients/[caminho]/performance/thresholds.md  → overrides de régua (se existir;
   se não existir, usar defaults de .claude/rules/optimization-thresholds.md)
2. clients/[caminho]/performance/monitoring-log.md → últimas entradas

Extraia do log:

  • Achados ainda abertos e há quantos ciclos consecutivos aparecem
  • Propostas de ação (PROP-YYYY-MM-DD-NNN) ainda sem decisão do usuário
  • Ações que o log marca como executadas por automação externa (ex: um cenário do Make.com que já ajusta budget sozinho) — não devem ser re-propostas

Se monitoring-log.md não existir ainda, este é o ciclo 1 — não há histórico para comparar, todos os achados serão NOVO.

ETAPA 2 — Contexto obrigatório

Confirme (só o que não estiver resolvido por $ARGUMENTS ou já presente no profile.md):

1. Qual cliente / conta?
2. Qual plataforma? (Meta Ads é o caso principal desta skill hoje)
3. Qual período? (default: últimos 7 dias + série diária dos últimos 14 dias,
   para suportar o gate de "zero conversões por N dias")

Regra obrigatória para disparo agendado/não interativo: se $ARGUMENTS já resolve cliente e existe clients/[caminho]/profile.md, NÃO pergunte nada — prossiga direto. Uma rotina agendada não tem humano para responder.

Carregue clients/[caminho]/profile.md (contas ativas, KPIs acordados, benchmarks).

ETAPA 3 — Verificar conexão MCP

Igual a ads-analyst ETAPA 2:

Windsor.ai: get_current_user → confirmar usuário autenticado
Meta Ads: ads_get_ad_accounts → confirmar acesso às contas do cliente

ETAPA 4 — Extrair dados

Meta Ads: ads_get_ad_entities(account_id, entity_type="CAMPAIGN"|"ADSET")
Meta Ads: ads_insights_performance_trend(account_id, date_range) → tendência 14d
Meta Ads: ads_insights_anomaly_signal(account_id)

Sempre incluir effective_status (e status) nos campos — uma campanha/adset pode ter gasto na janela mas estar PAUSED agora. Nunca inferir "ativa" pelo gasto do período: separe o que está ACTIVE (acionável) do que já foi pausado (histórico). Sinalize também entidades ACTIVE com zero entrega (budget alocado mas sem impressões/gasto) — pode ser bloqueio de conta/segurança, não é resolvível via MCP.

Sempre deixar explícito no relatório: o período exato analisado (datas), a conta, e o nível de consolidação (campanha / conjunto / anúncio). Puxar o nível onde mora a decisão de budget: campanha quando o budget é por campanha (CBO), adset quando é por adset. Sempre puxar período atual (7d) + série diária (14d) e o período anterior equivalente para variação %, conforme .claude/rules/mcp-data-guide.md.

ETAPA 5 — Aplicar régua de otimização

Consulte .claude/rules/optimization-thresholds.md (defaults) e clients/[caminho]/performance/thresholds.md (overrides, se existir — sempre prevalece sobre o default).

Para cada campanha/adset ativo:

  1. Verifique o gate de amostra mínima (spend/conversões) — se não atingido, classifique como "amostra insuficiente" e não gere proposta de ajuste de budget.
  2. Calcule a razão métrica-atual / benchmark do cliente.
  3. Classifique na banda correspondente (tabela da rule).
  4. Verifique o protocolo de zero-conversão (pausa) se aplicável.

ETAPA 6 — Diffing contra ciclo anterior

Para cada achado da Etapa 5, cruze com o estado carregado na Etapa 1 e marque:

StatusCritério
NOVONão existia no ciclo anterior
RECORRENTE (N ciclos)Já apareceu em ciclo(s) anterior(es), ainda sem decisão
RESOLVIDOExistia no ciclo anterior, não existe mais (métrica voltou à banda 🟢/🟡)
JÁ PROPOSTO — aguardando decisãoJá tem PROP-... aberta, sem resposta do usuário
JÁ EXECUTADO POR AUTOMAÇÃO EXTERNAO valor atual de budget/status já reflete uma mudança feita fora desta skill (ex: Make.com) — comparar ads_get_ad_entities atual com o valor esperado antes de propor

Regra: um achado só vira proposta de ação nova (Etapa 8) quando atinge RECORRENTE com pelo menos 2 ciclos consecutivos — a menos que thresholds.md do cliente diga o contrário, ou que seja um caso de segurança crítica (ex: pixel quebrado, conversões zeradas com gasto alto) que analysis-frameworks.md §3 já trata como 🔴 imediato.

ETAPA 7 — Relatório de monitoramento

Formato enxuto — foco no delta, não repita a tabela inteira se nada relevante mudou:

## Monitoramento — [Cliente] | Meta Ads | [Período] | Ciclo N
*Gerado em: [data/hora] | Moeda: [moeda] | Fonte: Meta Ads MCP*

### Resumo do ciclo
[2-3 linhas: o que mudou desde o último ciclo, quantas propostas pendentes de decisão]

### Achados

| Campanha/Adset | Métrica | Atual | Benchmark | Banda | Status do ciclo | Ciclos consecutivos |
|---|---|---|---|---|---|---|
| ... | ... | ... | ... | 🟢🟡🔴 | NOVO/RECORRENTE/... | N |

### Diagnóstico (P0/P1/P2)
[conforme output-standards.md — só itens que atingiram o critério de proposta na Etapa 6]

### Fila de decisões pendentes
[Lista de PROP-... ainda sem resposta do usuário, de ciclos anteriores]

ETAPA 8 — Oferta de execução

Para cada achado que atingiu o critério de proposta (Etapa 6):

Proposta [PROP-YYYY-MM-DD-NNN]:
→ [Descrição exata: ex: "Aumentar budget diário do adset X de R$50 para R$70 (+40%)"]
→ Motivo: [banda/métrica que disparou a proposta]
→ Ciclos consecutivos nesta banda: [N]

Confirma? (sim / não / ajustar)

Se este ciclo foi disparado por rotina agendada/não interativa: PARE AQUI. Registre as propostas no log (Etapa 9) como JÁ PROPOSTO — aguardando decisão e não prossiga para execução. Só execute quando o usuário responder "sim" na mesma conversa, seguindo o protocolo de escrita de .claude/rules/mcp-data-guide.md (confirmar valor exato, executar, ler de volta o estado, logar).

ETAPA 9 — Registro de estado

Sempre, a cada ciclo (mesmo sem achados novos), acrescente uma entrada em clients/[caminho]/performance/monitoring-log.md:

## Ciclo N — [data/hora]
Período analisado: [X a Y]
Achados: [resumo ou "nenhum achado relevante"]
Propostas geradas: [lista de PROP-... ou "nenhuma"]
Decisões do usuário neste ciclo: [PROP-... → sim/não/ajustado, ou "—"]

Só quando uma ação foi de fato executada via MCP com confirmação humana, também acrescente uma linha em clients/[caminho]/profile.md → "Histórico de ações executadas" (mesmo formato que ads-analyst já usa).

Se monitoring-log.md ultrapassar ~500 linhas, arquive o conteúdo mais antigo em clients/[caminho]/performance/monitoring-log-archive/YYYY-MM.md, mantendo no arquivo principal só os últimos ciclos.

Regras de segurança

Herda as 4 regras de ads-analyst:

  • NUNCA pausar campanha sem verificar tendência dos últimos 3 dias
  • NUNCA ajustar budget sem confirmar o novo valor explicitamente com o usuário
  • SEMPRE pedir confirmação antes de qualquer ação de escrita
  • NUNCA assumir que a conta do usuário é a mesma de sessões anteriores

E adiciona, específicas do ciclo contínuo:

  • Um achado só vira proposta de ação após persistir ≥ 2 ciclos consecutivos (evita reagir a ruído de 1 dia isolado) — configurável em thresholds.md do cliente.
  • Disparo agendado/não supervisionado nunca executa ação de escrita MCP — para na Etapa 8 e aguarda o próximo turno interativo com o usuário presente.
  • Nunca re-propor uma ação já marcada JÁ EXECUTADO POR AUTOMAÇÃO EXTERNA no estado carregado na Etapa 1.
  • Nunca propor variação de budget > 50% num único ciclo; nunca propor alta de budget em 2 ciclos consecutivos sem antes reconfirmar a métrica pós-mudança do ciclo anterior.

Diferença em relação a ads-analyst

ads-analystperformance-optimizer
UsoAuditoria/análise pontual sob demandaCiclo recorrente de acompanhamento
Memória entre execuçõesNão (só lê profile.md como contexto estático)Sim (performance/monitoring-log.md)
Repete alertas já vistos?N/A (não sabe o que já viu)Não — faz diffing e evita repetir
Pode rodar sem humano presente?Não é o caso de usoSim (modo agendado), mas nunca executa escrita sozinha
Rastreia resultado de decisões passadas?NãoSim, via ID de proposta (PROP-...)

Troubleshooting

ProblemaSolução
performance/ não existe ainda para o clienteTrate como ciclo 1: crie monitoring-log.md na Etapa 9, todos os achados são NOVO
thresholds.md do cliente não existeUse os defaults de .claude/rules/optimization-thresholds.md sem criar o arquivo (só criar quando houver override real)
Dúvida se uma mudança de budget veio de automação externa ou do usuárioCompare o valor lido via ads_get_ad_entities com o valor esperado pelo histórico; se não bater e não há PROP-... correspondente aprovada, assuma automação externa e sinalize, não reverta sozinho
monitoring-log.md muito grandeArquivar ciclos antigos em monitoring-log-archive/YYYY-MM.md (ver Etapa 9)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.