agentleFS
gavasquesgavasques/titanos-agent-skills/skills/amazon-sp-campaign-launcher/SKILL.md

amazon-sp-campaign-launcher

Skill0 starsChanged 3 months agoMITView on GitHub

Use when an AI agent needs to create Sponsored Products campaigns through Titanos MCP, especially new product launches, AUTO/KW/PAT structures, ASIN/SKU validation, dry-run/write execution, and safe partial recovery.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use quando o usuário pedir:

    line 17
  2. Very specific:

    Use ENABLED apenas se o usuário aprovar explicitamente.

    line 67
  3. Very specific:

    Use start_date explícito em ISO YYYY-MM-DD.

    line 112
  4. Very specific:

    Use idempotency_key única por lote.

    line 226

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Amazon SP Campaign Launcher — Titanos MCP

Objetivo

Criar campanhas Sponsored Products do zero com segurança via Titanos MCP.

Esta skill transforma um pedido como “crie campanhas para estes ASINs” em uma operação controlada: valida produto, monta estrutura, calcula bids, roda dry-run, pede aprovação, cria em ordem e verifica o resultado.

Quando usar

Use quando o usuário pedir:

  • Criar campanha Sponsored Products.
  • Lançar campanhas para um ou mais ASINs/SKUs.
  • Criar estrutura AUTO + keyword + product targeting.
  • Subir campanha de lançamento com budgets e bids.
  • Continuar criação parcial que falhou no meio.

Não use para otimização semanal ou dashboards de desperdício; nesses casos use skills de optimization/harvest/waste.

Inputs mínimos

Antes de escrever qualquer coisa, obtenha:

InputObrigatório?Como obter
connection_idsimlist_ads_connections
profile_idsimlist_ads_profiles
ASIN(s)simusuário ou catálogo
SKU(s) sellersimlisting/inventory Seller
Preçosimlisting/catalog
Estoquerecomendadoinventory
Target ACOSrecomendadousuário ou default conservador
Orçamento diáriosimusuário ou proposta confirmada

Se margem/COGS não estiver disponível, deixe claro que bids são de lançamento conservador, não break-even real.

Validação antes da campanha

Para cada ASIN:

  1. Validar que o produto existe.
  2. Validar que pertence ao seller/anunciante.
  3. Recuperar SKU seller.
  4. Confirmar preço.
  5. Confirmar buyable/listing ativo.
  6. Confirmar estoque suficiente.

Não crie product ads só com ASIN. Em sp_product_ads, envie também sku.

Estrutura padrão recomendada

Para lançamento comum:

CampanhaObjetivoBudget inicialTargeting
`SP<Marca><Produto>AUTODiscovery<YYYYMM>`descobrir termos e ASINs20–30%AUTO
`SP<Marca><Produto>KWCore<YYYYMM>`termos principais40–60%keywords exact/phrase
`SP<Marca><Produto>PATConcorrentes<YYYYMM>`ASINs concorrentes20–30%product targeting

Use ENABLED apenas se o usuário aprovar explicitamente. Caso contrário, crie PAUSED.

Cálculo de bid inicial

Fórmula de CPC máximo:

max_cpc = preço_do_produto × CVR_estimado × target_ACOS

Exemplo para produto de R$299:

CVRTarget ACOS 25%CPC máximo
1.0%25%R$0,75
1.5%25%R$1,12
2.0%25%R$1,50
2.5%25%R$1,87

Regras práticas:

  • AUTO: bid médio conservador.
  • Exact core: maior bid.
  • Phrase: 60–80% do exact.
  • PAT concorrente: menor que exact, salvo concorrente muito validado.
  • Termo/ASIN só é “validado” com 3+ pedidos. 1–2 pedidos = watchlist/teste.

Ordem de criação obrigatória

Nunca crie tudo no escuro em um batch único.

  1. sp_campaigns
  2. Readback com get_campaigns por nome/ID.
  3. sp_ad_groups
  4. Readback com get_ad_groups.
  5. sp_product_ads
  6. Readback com get_product_ads.
  7. sp_keywords e/ou sp_targets.
  8. sp_negative_keywords / sp_campaign_negative_keywords.
  9. Readback final.

Payloads base

1. Campaigns

Use start_date explícito em ISO YYYY-MM-DD.

{
  "resource_type": "sp_campaigns",
  "dry_run": true,
  "resources": [
    {
      "name": "SP | BKZA | Mocho | AUTO | Discovery | 202607",
      "targeting_type": "AUTO",
      "daily_budget": 30,
      "state": "ENABLED",
      "start_date": "2026-07-05"
    }
  ]
}

2. Ad groups

{
  "resource_type": "sp_ad_groups",
  "dry_run": true,
  "resources": [
    {
      "campaign_id": "<campaign_id>",
      "name": "ADG | Produto | Core KW",
      "default_bid": 1.0,
      "state": "ENABLED"
    }
  ]
}

3. Product ads

Inclua sku junto com asin.

{
  "resource_type": "sp_product_ads",
  "dry_run": true,
  "resources": [
    {
      "campaign_id": "<campaign_id>",
      "ad_group_id": "<ad_group_id>",
      "asin": "B0XXXXXXXXX",
      "sku": "SKU123",
      "state": "ENABLED"
    }
  ]
}

4. Keywords

sp_keywords usa payload flat.

{
  "resource_type": "sp_keywords",
  "dry_run": true,
  "resources": [
    {
      "campaign_id": "<campaign_id>",
      "ad_group_id": "<ad_group_id>",
      "keyword_text": "cadeira mocho",
      "match_type": "EXACT",
      "bid": 1.5,
      "state": "ENABLED"
    }
  ]
}

5. Product targets

sp_targets usa expression.

{
  "resource_type": "sp_targets",
  "dry_run": true,
  "resources": [
    {
      "campaign_id": "<campaign_id>",
      "ad_group_id": "<ad_group_id>",
      "expression": [
        { "type": "ASIN_SAME_AS", "value": "B0YYYYYYYY" }
      ],
      "bid": 0.85,
      "state": "ENABLED"
    }
  ]
}

Dry-run e confirmação

Antes de write real:

  1. Execute dry_run: true para cada resource type.
  2. Mostre ao usuário:
    • nomes das campanhas,
    • budgets,
    • estado ENABLED/PAUSED,
    • ASINs/SKUs,
    • total de keywords/targets,
    • impacto máximo diário.
  3. Só execute dry_run: false após aprovação explícita.

Idempotência e lotes

  • Use idempotency_key única por lote.
  • Batch máximo seguro: 5 recursos por chamada.
  • Nomeie chaves por projeto e etapa:
<slug>-<yyyymmdd>-campaigns-1
<slug>-<yyyymmdd>-adgroups-1
<slug>-<yyyymmdd>-productads-1
<slug>-<yyyymmdd>-keywords-1
<slug>-<yyyymmdd>-targets-1

Recovery se falhar no meio

Se qualquer write retornar 400/404/409/502:

  1. Pare.
  2. Faça readback por nomes/IDs exatos.
  3. Registre o que já foi criado.
  4. Não repita o batch inteiro sem saber o estado.
  5. Continue apenas da etapa pendente.

Exemplos de armadilhas reais:

| Erro | Causa | Correção | |---|---|---|---| | campaign 502 | start_date/budget mal normalizados | usar start_date: YYYY-MM-DD e budget diário correto | | merchantSku is empty | product ad sem SKU | enviar sku + asin | | idempotency conflict | mesma chave com payload diferente | usar nova chave e readback antes | | keyword 400/502 | endpoint/payload errado | sp_keywords deve ir para keywords com keyword_text + match_type | | target 404 | ASIN/target inválido ou endpoint/payload errado | validar ASIN concorrente e usar expression |

Status de bugs (MCP 1.42.2 — atualizado 2026-07-06)

✅ update_resources — funcionando (corrigido 2026-07-06)

O payload exige wrapper changes. Campos soltos causam 400.

update_resources sp_campaigns:
  { campaign_id, changes: { daily_budget: 65 } }     → ✅
  { campaign_id, changes: { state: "PAUSED" } }     → ✅

update_resources sp_keywords:
  { keyword_id, changes: { bid: 1.55 } }             → ✅
  { keyword_id, changes: { state: "PAUSED" } }       → ✅

✅ Reports com days — funcionando (corrigido 2026-07-06)

days: 7 retorna status PENDING e processa em background (~45-120s). Também aceita start_date/end_date.

⚠️ ask_ads_report_analyst

  • ✅ funciona sem connection_id/profile_id
  • ❌ falha com scope explícito

✅ list_ads_recommendations — funcionando (corrigido 2026-07-06)

Retorna [] com nota explicativa se Amazon 403 (comum em contas BR). Não é bug — é limitação de permissão.

✅ get_bid_guidance — funcionando (corrigido 2026-07-06)

Campo strategy adicionado com default CONVERSION_OPPORTUNITIES. Pode retornar suggested_bid: null para keywords sem histórico.

❌ DSP

Retorna erro para contas seller. DSP exige perfil agency.

✅ Bugs já corrigidos

BugStatusFix
sp_campaigns write 502✅ corrigidostart_date ISO + budget nested
sp_product_ads write 502✅ corrigidoincluir sku no payload
sp_keywords create 502✅ corrigidorotear para /sp/keywords/list
sp_targets create 400✅ corrigidorotear para /sp/targets
delete_resources sp_keywords schema✅ corrigidoenum atualizado para 1.42.2
get_targets readback KW✅ corrigidoretorna keywords[] + targets[]
update_resources SP 400✅ corrigido 2026-07-06id_field + .passthrough() + wrapper changes
list_ads_recommendations 502✅ corrigido 2026-07-06GET→POST + graceful 403
get_bid_guidance 502✅ corrigido 2026-07-06campo strategy adicionado
Reports com days 502✅ corrigido 2026-07-06agora retorna PENDING
get_targets readback PAT⚠️ pendentetargets[] ainda retorna vazio mesmo com DUPLICATE_VALUE

Readback final obrigatório

Ao terminar, confirme:

  • 3 campanhas existentes com estado e budget.
  • 1 ad group por campanha.
  • product ads para todos os SKUs.
  • keywords criadas na campanha KW.
  • ASIN targets criados na campanha PAT.
  • negativos criados.

Resposta final ideal

Criado:
- Campanhas: X
- Ad groups: X
- Product ads: X
- Keywords: X
- Product targets: X
- Negativos: X
Budget diário máximo: R$X
Estado: ENABLED/PAUSED
Pendências: nenhuma / listar erros reais

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.