Skip to content

AgriciDaniel/claude-ads / ads

Operate professional paid advertising across Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, Apple, Amazon, Reddit, Pinterest, Snapchat, and X. Use for account intake, source-grounded audits, strategy, budget and measurement planning, creative production, experiments, reporting, monitoring, and explicitly approved campaign changes. Also trigger on PPC, paid social, retail media, attribution, tracking, landing pages, cross-platform conversion totals, negative keywords or search terms, beta-feature scoring, stale platform claims, API-token or credential setup, campaign deletion, and safe Claude Ads installation or uninstall.

FileKindSize
SKILL.mdskill md19.4 KB
agents/openai.yamlconfig205 B
references/additional-platforms.mdmarkdown3.1 KB
references/amazon-audit.mdmarkdown3.8 KB
references/apple-audit.mdmarkdown4.4 KB
references/automation-tier-classifier.mdmarkdown3.4 KB
references/benchmarks.mdmarkdown4.4 KB
references/bidding-strategies.mdmarkdown4.9 KB
references/budget-allocation.mdmarkdown4.2 KB
references/compliance-requirements.mdmarkdown6.2 KB
references/compliance.mdmarkdown5.0 KB
references/conversion-tracking.mdmarkdown6.9 KB
references/copy-frameworks.mdmarkdown4.1 KB
references/creative-source-registry.mdmarkdown2.0 KB
references/gaql-notes.mdmarkdown7.5 KB
references/google-audit.mdmarkdown26.1 KB
references/google-creative-specs.mdmarkdown2.2 KB
references/image-providers.mdmarkdown5.0 KB
references/linkedin-audit.mdmarkdown11.8 KB
references/linkedin-creative-specs.mdmarkdown1.8 KB
references/mcp-integration.mdmarkdown6.5 KB
references/meta-ai-stack.mdmarkdown4.9 KB
references/meta-audit.mdmarkdown17.8 KB
references/meta-creative-specs.mdmarkdown1.9 KB
references/microsoft-audit.mdmarkdown10.4 KB
references/microsoft-creative-specs.mdmarkdown1.8 KB
references/pinterest-audit.mdmarkdown4.2 KB
references/platform-specs.mdmarkdown5.2 KB
references/prompt-patterns.mdmarkdown3.4 KB
references/reddit-audit.mdmarkdown4.7 KB
references/scoring-system.mdmarkdown5.8 KB
references/snapchat-audit.mdmarkdown4.1 KB
references/status-contract.mdmarkdown773 B
references/thinking-framework.mdmarkdown13.7 KB
references/tiktok-audit.mdmarkdown11.4 KB
references/tiktok-creative-specs.mdmarkdown2.0 KB
references/voice-to-style.mdmarkdown4.0 KB
references/x-audit.mdmarkdown3.3 KB
references/youtube-audit.mdmarkdown4.5 KB
references/youtube-creative-specs.mdmarkdown2.0 KB

references/thinking-framework.md

View on GitHub
# The 10-Principle Thinking Framework

The shared cognitive discipline that runs underneath every claude-ads command.
Load this file at the start of any audit, plan, or creative-output task. It
is not a checklist or a phase model — it is a mindset gate. The framework is
what separates a number-crunching report from a strategic deliverable.

The principles cluster in five pairs: two **OBSERVE** modes (looking out and
looking in), one **LISTEN** mode (active receptivity), one **THINK** mode
(critical processing), two **CONNECT** modes (lateral insight and system
orchestration), one **FEEL** mode (emotional intelligence), one **ACCEPT**
mode (intellectual humility), one **CREATE** mode (generative output), and
one **GROW** mode (the iterative loop that closes the cycle).

When in doubt, ask: *which principle am I in right now, and which one am I
skipping?* The skipped principle is usually where the work is weakest.

---

## 1. OBSERVE — External Input

**Definition.** Thinking begins with data collection. Look at the environment,
analyze the landscape, and spot patterns and inefficiencies *without rushing
to solve them*. Read the raw inputs of the situation.

**In ads work.**
- Export the actual account data — search-term reports, GAQL queries, ad
  library screenshots, MMP dashboards — before forming any hypothesis.
- Capture the SERP and the competitor ad surface. What does the user see
  before they click your client's ad?
- Pull the landing page exactly as the ad audience pulls it (mobile, paid
  source, fresh session). Don't audit a homepage when the ad goes to a PDP.

**Anti-pattern.** Diagnosing the problem from memory or from a generic
checklist before opening the account. Recommending Smart Bidding without
checking conversion volume. Critiquing a creative without seeing the safe
zone overlay.

**Example trigger.** First step of every `/ads audit`, `/ads competitor`,
`/ads dna`. The Context Intake section in `ads/SKILL.md` enforces this gate.

---

## 2. OBSERVE — Internal Metacognition

**Definition.** Observe yourself. Audit how you are thinking. Are you
operating on assumptions? Do you have a bias in this analysis?
Clarity requires stepping back and inspecting your own mental models.

**In ads work.**
- Notice when you are applying B2B-SaaS heuristics to a local plumber, or
  e-commerce ROAS targets to a brand-awareness campaign.
- Notice when you are penalizing an account because it doesn't match *your*
  preferred structure (SKAG vs broad-match, manual vs Smart Bidding).
- Notice when you are anchoring on the first KPI you saw and ignoring the
  funnel beneath it.

**Anti-pattern.** Confidence in a recommendation that has not been stress-
tested against a counter-hypothesis. "This campaign should be paused" with
no acknowledgment that the campaign might be load-bearing in attribution
that isn't visible to you yet.

**Example trigger.** Before finalizing the prioritized action plan in any
audit. Before recommending a structural change (rebuild vs optimize).

---

## 3. LISTEN — Active Receptivity

**Definition.** Shut down the ego and absorb external feedback. Pay attention
to user intent, community discussions, and the subtle signals in the noise
that tell you what people *actually* need rather than what you think they
need.

**In ads work.**
- Read the campaign brief verbatim. What did the client actually say their
  goal is, in their words? Don't translate "more leads" into "lower CPL"
  without checking that's what they meant.
- Listen to platform-side guidance (Google blog, Meta engineering, Microsoft
  Advertising blog, Apple WWDC sessions) before recommending a feature.
- Listen to the community: PPC subreddits, advertiser Slack groups, agency
  practitioners reporting real-world results that diverge from vendor claims.

**Anti-pattern.** Telling a brand-awareness advertiser to optimize for ROAS
because that is what most audits recommend. Citing a vendor's official
performance lift without sanity-checking against independent advertiser data.

**Example trigger.** `/ads create` and `/ads dna` — these commands are
fundamentally about listening (to the client and to the brand respectively).
Also: the Context Intake step at the start of every audit.

---

## 4. THINK — Critical Processing

**Definition.** Once you have the inputs, break the problem down to first
principles. Structure the logic, map the workflows, evaluate the constraints,
and synthesize the raw data into a coherent strategy.

**In ads work.**
- Compute unit economics by hand. Don't trust platform-attributed ROAS —
  derive CAC, LTV:CAC, payback period, and MER from raw data. See
  `references/budget-allocation.md` for the math.
- Build the funnel: impression → click → landing → micro-conversion →
  primary conversion → revenue → repeat. Where does the leak live?
- Evaluate constraints from current eligibility, account history, conversion lag,
  data volume, economics, and official documentation. Platform examples and
  practitioner ratios are hypotheses, not universal budget or volume floors.

**Anti-pattern.** Copying a "best practice" without checking whether the
account meets the prerequisites. Trusting platform attribution as ground truth
when the MMP, server-side, and platform numbers materially disagree without first
reconciling definitions, windows, identity, consent, deduplication, currency, and
timezone.

**Example trigger.** `/ads math`, `/ads budget`, `/ads test`. Also the
scoring and prioritization step of every audit.

---

## 5. CONNECT — Associative / Lateral Thinking

**Definition.** Great insight lives at intersections. Take two seemingly
unrelated concepts and link them to form a novel observation. The "aha"
moment of finding the hidden relationship between distinct variables.

**In ads work.**
- A creative-similarity pattern may explain delivery only after account evidence
  separates concept, audience, placement, bid, budget, and learning effects.
- Search automation and feed-based inventory can change the role of keywords, but
  current query evidence and campaign controls decide whether match types remain
  material for this account.
- App attribution, consent signals, browser and server events, and analytics form a
  measurement system. A recommendation in one layer must be coherent with the
  others and with the applicable geography and consent state.

**Anti-pattern.** Siloed platform audits that miss the cross-platform
leverage. Recommending Meta creative diversity changes without noticing the
same principle may apply to another platform after its delivery evidence is checked.

**Example trigger.** `/ads plan`, `/ads competitor`, the synthesis step of
`/ads audit` after sub-agents return.

---

## 6. CONNECT — System Orchestration

**Definition.** Move from isolated idea to integrated system. How do
individual thoughts, tools, and agents plug into one another to create a
seamless, functioning whole? The principle of building the wiring.

**In ads work.**
- The creative pipeline IS a connected system:
  `/ads dna` → `/ads create` → `/ads generate` → `/ads photoshoot`. Each
  output feeds the next. Don't run them in isolation.
- The tracking pipeline is a system: browser signals, server events, consent,
  analytics, app attribution, and business outcomes. A recommendation in
  `/ads tracking` must be coherent with `/ads attribution`.
- Bounded workers in `/ads audit` are orchestrated, not parallel-only. Their
  schema-valid findings return to one conductor and the deterministic engine;
  failed required workers make the result partial rather than disappearing.

**Anti-pattern.** Recommending fixes that conflict with each other.
"Increase budget" and "pause this campaign" in the same audit
without acknowledging the trade-off. Asking the user to run six sub-skills
manually instead of orchestrating them.

**Example trigger.** Every full audit (`/ads audit`). Every multi-step
deliverable (`/ads plan` → `/ads create` → `/ads generate`).

---

## 7. FEEL — Emotional Intelligence & Intuition

**Definition.** Pure logic is brittle without empathy. Factor in the human
element: user experience, emotional resonance of messaging, hard-earned
intuition when the data is ambiguous.

**In ads work.**
- Read the ad copy emotionally. Does the headline make a user feel something
  *they want to feel*? See `references/copy-frameworks.md` for the six
  proven emotional frameworks.
- Look at the landing page as a first-time visitor would. Where is the
  curiosity? Where is the resolution? Is the CTA at the right moment?
- Use informed intuition to propose creative hypotheses when data is ambiguous,
  then label and test them. A spec-compliant ad can still be a weak hypothesis;
  keep qualitative resonance separate from deterministic platform-health scoring.
- Brand voice mapping: `references/voice-to-style.md` translates emotional
  attributes into concrete visual choices.

**Anti-pattern.** A scoring rubric that rewards "spec compliance" and
penalizes nothing about emotional flatness. A creative review that lists
safe-zone metrics but never asks whether the ad makes anyone feel anything.

**Example trigger.** `/ads creative`, `/ads landing`, `/ads create`,
`/ads generate`, `/ads photoshoot`.

---

## 8. ACCEPT — Intellectual Humility

**Definition.** No plan survives first contact with reality. Embrace
constraints, acknowledge when a hypothesis failed, recognize when the
market wants something different than what you built. Let go of sunk costs
to pivot efficiently.

**In ads work.**
- If a campaign misses its owner-approved economics after conversion lag and a
  sufficient decision window, accept the evidence and compare pause, redesign,
  reallocation, or continued learning. A fixed CPA multiple or attempt count is
  not a universal stop rule and never authorizes an account mutation.
- If an audit recommendation was implemented and didn't move the needle in
  the measurement window, accept it and move on — don't double down.
- If a client's stated goal doesn't match their data signal (says "leads"
  but only revenue events are tracked), name the gap rather than
  rationalizing it.

**Anti-pattern.** Defending a "best practice" recommendation when the
account's history shows it has failed twice. Continuing to optimize a dying
campaign because pausing feels like admitting defeat.

**Example trigger.** `/ads budget` (kill rules), the prioritized action
plan at the end of `/ads audit`, post-test review after `/ads test`.

---

## 9. CREATE — Generative Output

**Definition.** Analysis paralysis is the enemy of progress. At some point
you stop strategizing and start producing. Move from consumption to action:
write the code, draft the content, ship the deliverable.

**In ads work.**
- Ship the audit report. Don't produce a 50-page analysis with no concrete
  recommendations or owner per action item.
- Write the actual ad copy, not a copy brief about a copy brief.
- Generate the ad assets through `/ads generate` — don't stop at the
  conceptual stage.
- Render requested formats from the canonical JSON bundle. Run the current report
  and release validation commands documented in the repository, then inspect the
  output before delivery. Do not name a script or format that is absent.

**Anti-pattern.** Endless "more analysis needed" loops. A campaign brief
that hedges every concept and forces the next collaborator to make every
hard decision.

**Example trigger.** `/ads create`, `/ads generate`, `/ads photoshoot`,
`/ads report`. Also the final synthesis step of any audit.

---

## 10. GROW — The Iterative Loop

**Definition.** Thinking is not a straight line; it is a feedback loop.
Take what you built (CREATE), see how it performs in reality, and use
those lessons to upgrade your skills and expand your capacity for the next
cycle.

**In ads work.**
- Every audit recommendation has a measurement plan attached. If you can't
  measure whether it worked, you can't grow from it.
- A/B test design in `/ads test`: hypothesis → significance → duration →
  result → next hypothesis. The loop is the point.
- Re-audit after a decision-appropriate observation window. Compare against the
  baseline captured in the prior audit and account for conversion lag, seasonality,
  experiment duration, and material intervening changes.
- Carry forward what worked and what didn't into the next campaign brief.
  `brand-profile.json` should evolve, not stay frozen.

**Anti-pattern.** One-shot audits with no follow-up. Recommendations
without measurement criteria. Treating each campaign as if the lessons from
the last one don't apply.

**Example trigger.** Closing step of every major deliverable. Built into
`/ads test`, and into the re-audit cycle that `/ads audit` implicitly
invites.

---

## Workflow map

Which principle dominates at each step of the canonical workflow:

| Stage | Dominant principles | Why |
|---|---|---|
| Context Intake (start of every command) | OBSERVE (External), LISTEN | Read the account, read the brief |
| `/ads dna <url>` | OBSERVE, LISTEN | Brand listening made concrete |
| `/ads audit` — data collection | OBSERVE, OBSERVE-Internal | Pull data; check your own biases |
| `/ads audit` — analysis | THINK, CONNECT-Lateral | First-principles math; cross-platform synthesis |
| `/ads audit` — synthesis & scoring | CONNECT-System, ACCEPT | Wire findings together; accept uncertainty and failed hypotheses |
| `/ads plan` | THINK, CONNECT-Lateral, FEEL | Strategy = math + insight + empathy |
| `/ads create` | LISTEN, FEEL, CREATE | Hear the brand; feel the audience; ship the brief |
| `/ads generate` / `/ads photoshoot` | FEEL, CREATE | Produce with emotional intent |
| `/ads report` | CREATE | Render the deliverable; close the loop |
| Post-deliverable | GROW | Measure, learn, set up the next cycle |

If a stage you are in does not have its dominant principle engaged, you are
producing weaker work than you could. Slow down and find which principle is
missing.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall