Merge pull request #173 from aicodingstack/codex/seo

fix(seo): improve crawlability and install marketing skills

Author: ericyangpan

.agents/skills/ad-account-auditor/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: ad-account-auditor
+slug: aaron-ad-account-auditor
+displayName: "Ad Account Auditor · 付费广告账户审计"
+summary: "付费广告账户审计/ROAS评分"
+description: 'Use when auditing a paid ad account for incremental contribution, wasted spend, or measurement integrity before scaling; runs a typed 20-item ROAS profile with verified vetoes and a SHIP/FIX/BLOCK/UNDECIDED gate on own exported data. Not for campaign structure design — use campaign-architect; not for creative production — use ad-creative-builder. 付费广告账户审计/ROAS评分'
+version: "19.0.0"
+license: Apache-2.0
+compatibility: "Claude Code and compatible agent-skill hosts"
+homepage: "https://github.com/aaron-he-zhu/aaron-marketing-skills"
+when_to_use: "Use when checking whether a paid account or portfolio is safe to launch or scale. Requires normalized own-data outcomes, attribution windows, currency, conversion lag, and business constraints."
+argument-hint: "<campaign + outcome exports> <currency/window/lag> [profile]"
+allowed-tools: WebFetch
+class: auditor
+metadata: {"author": "aaron-he-zhu", "version": "19.0.0", "discipline": "ad", "phase": "activate", "geo-relevance": "medium", "hermes": {"tags": ["marketing", "ad", "activate"], "category": "ad"}, "openclaw": {"emoji": "🎯", "homepage": "https://github.com/aaron-he-zhu/aaron-marketing-skills"}}
+---
+
+# Ad Account Auditor
+
+Audit one paid-media account or portfolio for incremental contribution and operating quality under declared constraints. Platform-reported ROAS is one input, never the objective or truth set by itself.
+
+## When This Must Trigger
+
+- Before launching, materially increasing spend, or changing a risky bid/targeting strategy.
+- When tracking, attribution inflation, unsafe placements, claims, or wasted spend are in doubt.
+- When the user requests a ROAS/RQS account audit from their exports.
+
+## Quick Start
+
+```text
+Audit this USD account for direct response using 7-day click, 3-day lag, and $120 CAC ceiling.
+Run the incremental-profit profile against the holdout and order-ID exports.
+```
+
+## Skill Contract
+
+**Reads:** one normalized account/portfolio evidence set. **Writes:** only a permissioned v3 artifact. **Done when:** required context and all 20 states are explicit, vetoes use verified evidence, and scorer output is reported without executing spend changes.
+
+This skill judges. `conversion-signal-qa`, `attribution-reconciler`, `campaign-architect`, `ad-creative-builder`, and `budget-pacing-monitor` build/fix the inputs. Never enable campaigns, change bids, upload audiences, or scale budgets without separate explicit approval.
+
+## Data Sources
+
+| Need | Preferred evidence |
+|---|---|
+| Delivery/spend | Campaign, query, placement, audience, and change-history exports |
+| Outcome truth | Deduplicated order/lead IDs from ecommerce, analytics, or CRM |
+| Economics | Currency, margin/contribution, CAC/payback constraint |
+| Attribution | Platform + own-data timestamps/IDs, normalized windows and lag |
+| Safety/claims | Placement report, rendered ad/landing, approved claim/disclosure state from [offer-claims-registry](../../../protocol/offer-claims-registry/SKILL.md) (the paid claims SSOT) |
+| Incrementality | Holdout/geo split/causal test, otherwise explicitly labeled proxy |
+
+## Instructions
+
+### Runtime and Setup
+
+Read `../../../references/auditor-runbook.md`, `scoring-semantics.md`, `roas-benchmark.md`, and the ROAS catalog entry. Standalone installs use bundled immutable `references/auditor-runtime.md`; never fetch mutable `main`. Before deterministic calls, follow [`runtime-invocation.md`](../../../references/runtime-invocation.md), resolve `AARON_SKILLS_ROOT="${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || true)}"`, and require the scorer, validator, and typed catalogs. If unavailable, return `score_state: NOT_SCORED` / `score_confidence: not_scored` with no gate verdict or persistent artifact.
+
+Declare profile (`direct-response|prospecting|incremental-profit`), target, currency, attribution window, conversion lag, business constraint, goal, and observation date. If any required context is missing, return `NEEDS_INPUT/UNDECIDED`.
+
+### Evidence and Scoring
+
+1. Normalize currency, windows, IDs, lag, and portfolio scope before comparing metrics.
+2. Score all 20 `R1..S5` criteria from the benchmark with source/date/type/confidence.
+3. Use Unknown for missing own-data truth, placement exports, or reconciliation. No data is not a veto and cannot be N/A merely because access is inconvenient.
+4. Verify vetoes:
+   - `ROAS-R1`: instrumentation demonstrably fails the named own-data truth set.
+   - `ROAS-R2`: material double-counting/inflation is demonstrated.
+   - `ROAS-O1`: material claim/disclosure failure against the `offer-claims-registry` approved state.
+   - `ROAS-O2`: applicable platform/restricted-category violation.
+   - `ROAS-A1`: placement evidence demonstrates a material safety breach.
+5. Run the typed scorer. Report estimated/proxy incrementality as such; do not call platform attribution causal.
+
+## §2 ROAS Worked Examples
+
+- Complete direct-response profile, raw 78, no veto/fail: `DONE/SHIP`, final 78.
+- Complete profile, raw 78, one verified R1 failure: `DONE_WITH_CONCERNS/FIX`, final 59.
+- Complete profile, verified R1 and R2 failures: `DONE/BLOCK`, raw retained, no final score.
+- Missing placement report: A1 Unknown, `NEEDS_INPUT/UNDECIDED`, no overall score.
+
+## §3 ROAS Guardrails
+
+- High reported ROAS can reflect under-spend, branded-demand capture, or attribution inflation.
+- Learning-phase disruption is an S2 finding, not an automatic veto.
+- ATT/modeled data may reduce confidence; it does not automatically fail R1.
+- Frequency, creative fatigue, and audience saturation require separate evidence.
+- Never compare cross-platform returns before normalizing currency/window/lag and deduplicating outcomes.
+
+## §5 ROAS Translation
+
+Lead with business impact and evidence. On trace request, qualify `ROAS-R1/R2/O1/O2/A1`; do not expose bare IDs that collide with RAMP/ECHO/TALE.
+
+## Report and Verdict
+
+Begin with the auditor-runbook's exact typed conversation header. Never replace `status`, `verdict`, or `score_state` with prose; list each explicitly missing qualified item as ``ID: `unknown``` before findings.
+
+Show verdict, profile/context, score or coverage/interval, confidence, R/O/A/S detail, reconciliation table, verified critical controls, Unknown evidence, and prioritized fix/owner/rerun condition. The scorer owns status/verdict and the 59 ceiling.
+
+## Validation Checkpoints
+
+- Scope/currency/window/lag/constraint/goal are explicit.
+- Own-data outcome truth is separated from platform self-report.
+- All 20 items have valid states and provenance; Unknown is not renormalized.
+- Veto failures are positively verified.
+- No spend/account mutation occurred without separate approval.
+
+## Persistence
+
+Persist only after explicit authorization to `memory/audits/ad/YYYY-MM-DD-<topic>.md`. Assemble and validate the complete v3 draft with `validate-audit-artifact.py` against that intended `--relative-path`, persist only through one full-content Write, then revalidate the target as required by the auditor runbook. Edit/shell/MCP mutations of the reserved sink are unsupported. Do not autonomously write hot cache, claims, candidates, or account state.
+
+## Reference Materials
+
+- [ROAS benchmark](../../../references/roas-benchmark.md)
+- [Measurement protocol](../../../references/measurement-protocol.md)
+- [Auditor runbook](../../../references/auditor-runbook.md)
+- [Scoring semantics](../../../references/scoring-semantics.md)
+
+## Next Best Skill
+
+- **Tracking:** [conversion-signal-qa](../conversion-signal-qa/SKILL.md)
+- **Claims/disclosures:** [offer-claims-registry](../../../protocol/offer-claims-registry/SKILL.md) — the approved claim/disclosure state behind `ROAS-O1`
+- **Attribution:** [attribution-reconciler](../../scale/attribution-reconciler/SKILL.md)
+- **Structure/audience:** [campaign-architect](../../research/campaign-architect/SKILL.md)
+- **Pacing:** [budget-pacing-monitor](../../scale/budget-pacing-monitor/SKILL.md)

.agents/skills/ad-account-auditor/references/auditor-runtime.md

@@ -0,0 +1,225 @@
+<!-- GENERATED FILE: run `python3 scripts/generate-auditor-runtime.py --write`; do not edit. -->
+
+# Standalone Auditor Runtime
+
+- **Runtime version:** 3.0.0
+- **Catalog version:** 19.0.0
+- **Framework:** ROAS
+- **Auditor:** ad-account-auditor
+- **Source digest:** `sha256:feab7466c35ec4300764147dc87dc7a94f05314831b63e94ba19d33e0417f6e0`
+
+This immutable bundle is the fail-closed standalone fallback for this auditor. It contains the exact typed framework slice needed to collect observations without inventing rules. Repository/plugin installs use the root policy, schemas, and deterministic scorer. A standalone one-folder install must not fetch mutable sources, compute a score, claim a gate verdict, or persist an audit artifact.
+
+## Typed Framework Snapshot
+
+```json
+{
+  "catalog_version": "19.0.0",
+  "frameworks": {
+    "ROAS": {
+      "construct": "incremental paid-media contribution and operating quality under declared business constraints",
+      "dimensions": {
+        "A": {
+          "id_width": 1,
+          "item_count": 5,
+          "item_prefix": "A",
+          "name": "Audience"
+        },
+        "O": {
+          "id_width": 1,
+          "item_count": 5,
+          "item_prefix": "O",
+          "name": "Offer"
+        },
+        "R": {
+          "id_width": 1,
+          "item_count": 5,
+          "item_prefix": "R",
+          "name": "Return"
+        },
+        "S": {
+          "id_width": 1,
+          "item_count": 5,
+          "item_prefix": "S",
+          "name": "Spend Efficiency"
+        }
+      },
+      "item_definitions": {
+        "A1": "brand and placement safety verified from the placement evidence",
+        "A2": "targeting and query/audience intent fit",
+        "A3": "negative keywords, exclusions, and suppression controls are maintained",
+        "A4": "campaign/account structure supports the declared objective without avoidable overlap",
+        "A5": "reach, overlap, and audience saturation are measured",
+        "O1": "claims and required disclosures are substantiated",
+        "O2": "platform policy and restricted-category requirements are satisfied",
+        "O3": "offer economics, eligibility, terms, and availability are explicit",
+        "O4": "ad-to-landing message and intent match",
+        "O5": "creative hook, format, accessibility, and fatigue state fit the placement",
+        "R1": "conversion instrumentation verified against an own-data truth set",
+        "R2": "cross-platform attribution deduplicated and windows/currency normalized",
+        "R3": "incremental contribution or profit measured against the declared target/control",
+        "R4": "CAC/CPA and payback satisfy the declared business constraint",
+        "R5": "marginal return is read after conversion lag with uncertainty stated",
+        "S1": "budget pacing stays within the declared plan and constraints",
+        "S2": "bid strategy and learning-state changes are governed",
+        "S3": "marginal CPC/CPM/CTR/CVR efficiency is compared on a normalized window",
+        "S4": "frequency and creative decay are separated from audience saturation",
+        "S5": "paid/organic and cross-campaign cannibalization are assessed"
+      },
+      "item_policies": {
+        "A1": {
+          "unknown_policy": "needs-input",
+          "veto": true
+        },
+        "O1": {
+          "veto": true
+        },
+        "O2": {
+          "veto": true
+        },
+        "R1": {
+          "unknown_policy": "needs-input",
+          "veto": true
+        },
+        "R2": {
+          "unknown_policy": "needs-input",
+          "veto": true
+        }
+      },
+      "profiles": {
+        "direct-response": {
+          "context_equals": {
+            "goal": "direct-response"
+          },
+          "dimensions": {
+            "A": 0.15,
+            "O": 0.2,
+            "R": 0.4,
+            "S": 0.25
+          }
+        },
+        "incremental-profit": {
+          "context_equals": {
+            "goal": "incremental-profit"
+          },
+          "dimensions": {
+            "A": 0.1,
+            "O": 0.15,
+            "R": 0.5,
+            "S": 0.25
+          }
+        },
+        "prospecting": {
+          "context_equals": {
+            "goal": "prospecting"
+          },
+          "dimensions": {
+            "A": 0.3,
+            "O": 0.3,
+            "R": 0.15,
+            "S": 0.25
+          }
+        }
+      },
+      "required_context": [
+        "currency",
+        "window",
+        "conversion_lag",
+        "business_constraint",
+        "goal"
+      ],
+      "source": "references/roas-benchmark.md",
+      "unit_of_analysis": "one account/campaign portfolio, currency, attribution window, and observation period",
+      "veto_items": [
+        "R1",
+        "R2",
+        "O1",
+        "O2",
+        "A1"
+      ]
+    }
+  },
+  "semantics": {
+    "bands": [
+      {
+        "maximum": 100,
+        "minimum": 90,
+        "name": "Excellent"
+      },
+      {
+        "maximum": 89,
+        "minimum": 75,
+        "name": "Good"
+      },
+      {
+        "maximum": 74,
+        "minimum": 60,
+        "name": "Medium"
+      },
+      {
+        "maximum": 59,
+        "minimum": 40,
+        "name": "Low"
+      },
+      {
+        "maximum": 39,
+        "minimum": 0,
+        "name": "Poor"
+      }
+    ],
+    "confidence_factors": {
+      "high": 1.0,
+      "low": 0.5,
+      "medium": 0.75
+    },
+    "evidence_types": {
+      "calculated": 0.8,
+      "estimated": 0.5,
+      "measured": 1.0,
+      "proxy": 0.4,
+      "user-provided": 0.8
+    },
+    "external_validity": "advisory-until-outcome-calibrated",
+    "item_points": {
+      "fail": 0,
+      "partial": 5,
+      "pass": 10
+    },
+    "missingness": {
+      "missing": "treated as unknown, never as partial or fail",
+      "na": "genuinely inapplicable under an item policy; requires a reason and is excluded",
+      "unknown": "applicable but not observed; prevents a comparable total score"
+    },
+    "multi_veto": {
+      "emit_final_score": false,
+      "minimum": 2,
+      "verdict": "BLOCK"
+    },
+    "required_coverage": 100,
+    "rounding": "floor",
+    "score_states": [
+      "pass",
+      "partial",
+      "fail",
+      "unknown",
+      "na"
+    ],
+    "veto_ceiling": 59
+  }
+}
+```
+
+## Standalone Execution Policy
+
+1. Select exactly one declared profile from the typed snapshot and record it with the catalog version and source digest above.
+2. Collect one state per applicable item using the run-schema vocabulary: `pass`, `partial`, `fail`, `na`, or `unknown` — the same states the root scorer replays later. Every non-unknown state needs evidence; never convert missing evidence into a pass.
+3. Record veto observations by their qualified framework item IDs, but do not calculate dimension, raw, capped, or final scores without the root deterministic scorer.
+4. Return `status: NEEDS_INPUT` or `status: BLOCKED` with `verdict: UNDECIDED`, `score_state: NOT_SCORED`, and `score_confidence: not_scored`. Clearly identify the unavailable root runtime as the reason.
+5. Do not write under `memory/audits/`, mutate registries, or claim a publish/ship decision. Offer the observation set for later execution in a full plugin or repository install.
+6. Do not search parent directories, accept an unverified runtime root, download repository files, or hand-calculate a substitute score.
+
+The source digest binds this compact fallback to the authoritative runbook, scoring semantics, framework benchmark, run schema, and artifact schema without copying those maintenance sources into every standalone bundle.
+
+---
+
+End of generated standalone runtime.