# Hector Amazon Ads

> Router and shared operating rules for the Hector Amazon Ads skill set. Dispatches to four SME-authored skills — brand ads audit, keyword harvesting, SQP analysis, and search-term negation — and holds the MCP conventions they share (profile resolution, date handling, row caps, filter placement, units, write gates). Load when more than one Hector Amazon skill could apply, or when a request touches Amazon Ads via the Hector MCP but does not match a specific skill's trigger.

- Skill: `hectorai-live/hector-amazon-ads` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hectorai-live/hector-amazon-ads`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hectorai-live/hector-amazon-ads/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: hectorai-live (https://skillmd.com/u/hectorai-live)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hectorai-live/hector-amazon-ads

---


# Hector Amazon Ads

Four SME-authored skills for running Hector's Amazon Ads methodology through the
Hector MCP connector. Each is self-contained with its own triggers, blocking
preconditions, self-check, and versioning. This file routes between them and
holds what they have in common.

## Routing

| Skill | Fires on | Deliverable | Writes? |
|-------|----------|-------------|---------|
| `hector-brand-ads-audit` | "run an ads audit for X", "brand audit", "advertising audit" + a named account | 9-slide HTML deck (5 pillars) | No |
| `hector-keyword-harvesting` | "harvest keywords", "what keywords should I add", "keyword gap analysis" | Grouped candidate tables → optional keyword adds | **Yes** — `bulk_add_keywords` after preview + confirm |
| `hector-sqp-analysis` | "run SQP analysis", "search query performance report" + a named account | 6-tab HTML dashboard + 5-sheet XLSX | No |
| `hector-search-term-negation` | "run search term negation", "negate bleeding search terms" | Negations applied + change-log CSV | **Yes** — negatives after preview + CONFIRM |

### Boundaries the skills enforce themselves

Each skill's description defines what it does **not** fire on. Respect those —
they were drawn deliberately:

- A single-pillar request ("just show me the bleeders") is an atomic query, not
  the audit skill.
- "Show me my top search terms" is a performance report, not harvesting.
- A single-metric SQP lookup is answered directly, not with the full analysis.
- Running the audit does **not** trigger negation. Negation is its own request,
  with its own fresh pull and its own CONFIRM.

When two could apply, prefer the narrower one, and say which you picked.

## Shared MCP conventions

These hold across all four skills. Where a skill states something more specific,
the skill wins.

### Profile resolution — never guess

Always `find_profile_by_name` (or `get_amazon_profiles`). One match in the named
country → confirm in one line. Multiple → list with profile_id and currency, let
the user pick, never auto-pick. Zero → surface and stop.

### Dates

- The audit and negation skills take an explicit date range in precursors;
  default last 60 days.
- Harvesting defaults to `last_30_days` with auto-escalation to `last_60_days`,
  and runs `hector-mcp-date-resolution` first.
- **SQP is weekly and Saturday-aligned** with a ~3-day lag. Compute the window
  locally; never pass `today`/`yesterday` as `end_date`; never pass `week_range`
  and `start_date`/`end_date` in the same call.
- Reporting data is complete only through yesterday.

### Server-side filtering and row caps

Push filters to the server. Two filter surfaces exist and they are not
interchangeable:

- `metric_filters` — numeric thresholds (`{field, operator, value}`), operators
  limited to `greater_than` / `less_than` / `equal`.
- `master_search_filters` — the advanced escape hatch for shapes the flat
  params cannot express.
- Flat params (`campaign_names`, `status_types`, `budget_state`,
  `advertised_asin`, `harvesting`) beat both when they cover the case.

`analytics_*` list tools return a lean **5-row** preview by default and ignore
`limit` unless `explicit_limit: true` is set — and that flag is only legitimate
when the user named an actual row count. `summary.total_count` reports the full
matched size regardless of how many rows come back. When
`pagination.next_action` is `ASK_USER_BEFORE_FETCHING_MORE`, ask; never
auto-paginate.

### Units — the traps that produce silently wrong output

| Field | Rule |
|-------|------|
| ACOS | Whole-number percent. `30` = 30%. A fraction between 0 and 1 is rejected by the schema on purpose — do not convert it. |
| ROAS | Ratio. `5` = 5×, not 500%. |
| Bid percentage | Whole number. `0.20` means 0.2%, not 20%. |
| CPC | Historical cost-per-click, **never** a bid. Bids come from `get_suggested_bids`. |
| Currency | The profile's currency (`response_meta.currency`). Never assume USD or INR. |

### Context discipline

Both HTML-deliverable skills enforce a temp-file pattern: any MCP response over
~30 rows is written to disk and processed with Python; only aggregates enter
chat. Raw rows never get transcribed twice. Context exhaustion is the primary
failure mode on multi-pillar runs — treat these rules as load-bearing, not
stylistic.

### Writes

Two skills write. Both gate the same way:

1. Present a preview — summary plus a top-10 table
2. Wait for **explicit** confirmation (negation requires the literal word
   `CONFIRM`; "yes", "ok", "go" are treated as CANCEL)
3. Execute
4. Write the audit trail — a change-log CSV for negation; the reported outcome
   for harvesting

Never write on inferred consent, and never chain a second write off an
unverified first one.

## Environment dependencies

These skills were authored for a Claude environment with a filesystem and file
presentation:

- `/home/claude/…` scratch directories for temp files
- `/mnt/user-data/outputs/` for deliverables
- `present_files` to surface the output to the user
- Python with `openpyxl` and `pandas` for the XLSX/HTML generators

If any of those are unavailable in the host you are running in, say so before
starting rather than half-completing a run.

## Skills

- `hector-brand-ads-audit` (v1.1) — 5-pillar audit deck
- `hector-keyword-harvesting` (v2) — harvest candidates + add flow
- `hector-sqp-analysis` (v1.2) — 6-tab SQP dashboard + workbook
- `hector-search-term-negation` (v1) — bleeding negation with CONFIRM gate