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