Creating a Google Ads SKILL.MD for Claude

What is a SKILL.MD file for Claude?

Claude, Anthropic’s large language model, can load structured markdown files at the start of a conversation or project to establish persistent context. A SKILL.MD file is one such file, designed to encode domain-specific knowledge, API schemas, workflow logic, and guardrails so the model behaves like a specialist rather than a generalist. Think of it as a combination of a system prompt, a reference manual, and a set of callable pseudo-functions, all written in markdown that Claude parses before responding to any user query.

The concept borrows from how developers use README.md or CONTRIBUTING.md files in code repositories: a single, version-controlled document that everyone (or in this case, the model) reads first. Where a README orients a human contributor, a SKILL.MD orients Claude toward a specific professional domain. For Google Ads management, that means encoding campaign structures, GAQL query patterns, API version constraints, bidding strategy logic, and reporting schemas so that Claude can generate usable code, interpret performance data, and flag problems without the user re-explaining fundamentals every session.

I’ve found that the difference between a well-structured SKILL.MD and a loose collection of prompts is roughly the difference between handing someone a procedures manual and shouting instructions across a room. The model retains the file’s context throughout the session, which means you can reference campaign types, field names, or reporting dimensions without restating them. For PPC specialists who interact with Claude daily, this eliminates a surprising amount of friction.

Why use a dedicated skill for Google Ads?

Google has shifted the Ads API to a monthly release cadence since v23 launched on January 28, 2026, with v23.1 following on February 25, v23.2 on March 25, and v24 arriving April 22. [2] Each release introduces new resources, deprecates old ones, and occasionally removes fields entirely (CallAd and CallAdInfo were stripped from v23, for instance, and any mutation referencing them now fails). [11] A general-purpose LLM that was trained months ago has no awareness of these changes unless you supply that awareness explicitly.

A dedicated SKILL.MD file solves this by acting as a living reference that you update whenever Google ships a new version. It pins Claude to the correct API version (e.g., version=”v24″ in the Python client library), lists available resources and their required fields, and specifies which features are allowlisted versus generally available. Without this, Claude will happily generate code against deprecated endpoints or omit newly required fields like business_name on VideoResponsiveAdInfo, which became mandatory in v24. [11]

There’s also a practical argument around consistency. If three people on a PPC team each prompt Claude differently, they’ll get three different code styles, three different GAQL query structures, and three different assumptions about campaign hierarchies. A shared SKILL.MD file standardizes the model’s output across the team, which matters when that output feeds directly into production scripts or automated reporting pipelines.

Core components of a Google Ads skill file

A useful Google Ads SKILL.MD file isn’t a dump of the entire API reference. It’s a curated subset of the information Claude needs to handle the tasks your team actually performs, structured so the model can retrieve relevant sections efficiently. From my experience building these files, five sections form the backbone.

The first section should declare the active API version and its constraints. Right now that means specifying v24 as the target, noting that the Python client loads with GoogleAdsClient.load_from_storage(version=”v24″), and listing breaking changes from prior versions. [1] You should explicitly state that Campaign.video_brand_safety_suitability has moved to the Customer level in v24, because Claude will otherwise place it at the campaign level based on older training data. [11]

The second section covers campaign type schemas. For each campaign type your team uses (Search, PMax, Shopping, Demand Gen), define the required and optional fields, valid bidding strategies, and any type-specific constraints. For PMax and Search campaigns that use AI Max, this is where you encode Campaign.text_guidelines, the v23.1 addition that supports up to 25 term_exclusions and 40 messaging_restrictions for controlling AI-generated ad copy. [2] These limits are easy to exceed if Claude doesn’t know they exist.

The third section defines GAQL query templates. Rather than letting Claude compose queries from scratch each time (which introduces syntax errors and inefficient field selection), pre-define parameterized templates for your most common reporting needs. A frequency analysis template, for example, should already include metrics.unique_users_two_plus through metrics.unique_users_ten_plus, the fields added in v23.1. [2]

The fourth section specifies mutation patterns and guardrails. This is where you define which operations Claude should generate code for (creating campaigns, updating bids, adding ad groups) and which it should refuse or flag for human review. If your team uses the official Google Ads MCP server, note its read-only limitation here: it exposes list_accessible_customers and GAQL search tools but cannot modify bids, pause campaigns, or create assets. [2] Mutations stay in the REST API, and Claude should generate those as reviewable code snippets rather than attempting direct execution.

The fifth section is an error handling reference. Include common error codes and their resolutions, particularly newer ones like MAX_INCENTIVES_REDEEMED and ACCOUNT_TOO_OLD from the March 2026 update. [11] When Claude encounters these in a user’s error log, it can diagnose the problem immediately instead of guessing.

Example for generating a new search campaign

Here’s where the SKILL.MD file earns its keep. Suppose a PPC specialist asks Claude to scaffold a new Search campaign with AI Max enabled. Without the skill file, Claude might produce code that omits text_guidelines entirely, or worse, references the deprecated CallAd format. With a properly structured SKILL.MD, the model knows to include text guidelines by default and to apply the team’s standard exclusions.

A practical SKILL.MD entry for this workflow would look something like the following (simplified for illustration):

## Search Campaign Creation (AI Max)

### Required fields
- campaign.name
- campaign.advertising_channel_type: SEARCH
- campaign.bidding_strategy_type: TARGET_CPA | MAXIMIZE_CONVERSIONS
- campaign.text_guidelines.term_exclusions: [load from brand_exclusions.json, max 25]
- campaign.text_guidelines.messaging_restrictions: [load from messaging_rules.json, max 40]

### Default behavior
- Always apply text_guidelines from team config
- Set campaign status to PAUSED on creation
- Generate ad_group with at least 3 responsive search ads
- Pin version="v24" in client initialization

### Guardrails
- Never set campaign status to ENABLED without human confirmation
- Flag if term_exclusions count exceeds 20 (approaching limit)
- Require budget confirmation before campaign.create mutation

When Claude reads this section, it generates Python code that initializes the client at v24, creates the campaign in PAUSED state, loads term exclusions from the team’s configuration file, and applies messaging restrictions. The guardrail about never enabling a campaign without confirmation is particularly important: it prevents an overeager automation from pushing a draft campaign live. I’ve seen this happen with less constrained setups, and it’s the kind of mistake that erodes trust in AI-assisted workflows fast.

The text_guidelines mutation itself follows the pattern documented for v23.1, using FieldMask to update only the relevant nested fields. [2] By encoding this pattern in the SKILL.MD, you ensure Claude applies it consistently rather than reinventing the approach each session.

How to define reporting and analysis functions

Reporting is where most PPC teams will get the fastest return from a SKILL.MD file, because it’s the task they perform most frequently and the one where Claude’s ability to compose GAQL queries saves the most time. The skill file should contain parameterized query templates that Claude fills in based on the user’s request, along with instructions for how to interpret and present the results.

For e-commerce accounts, v24’s CartDataSalesView resource is a significant addition. It allows segmenting conversion metrics by the product actually sold (using segments like product_sold_brand), not just the product clicked. [1] Your SKILL.MD should include a template for this view paired with the non-biddable all_ metrics (such as all_cost_of_goods_sold_micros) that v24 introduced for calculating average cart size and revenue per transaction. [11] Without the template, Claude won’t know these fields exist and will fall back to older, less granular reporting patterns.

Frequency reporting is another area that benefits from pre-defined logic. The unique_users_X metrics from v23.1 let you measure how many users saw an ad two, three, five, or ten-plus times. [2] A useful SKILL.MD entry would define a GAQL template like SELECT campaign.id, metrics.unique_users_two_plus FROM campaign WHERE segments.date DURING LAST_7_DAYS and instruct Claude to calculate the ratio of unique_users_ten_plus to total unique users as a frequency saturation indicator. Whether you set the alert threshold at 30% or some other number depends on your vertical and campaign goals, but encoding the calculation logic in the skill file means Claude performs it automatically whenever a user asks about frequency.

One thing I’d caution against: don’t try to make the SKILL.MD file handle data visualization. Claude can generate tables and suggest chart types, but the actual rendering belongs in your BI tool or a downstream script. The skill file should focus on getting the right data out of the API in the right shape, not on presentation.

Best practices for skill file maintenance

A SKILL.MD file that isn’t updated becomes a liability. Given Google’s monthly release cadence, you need a maintenance rhythm that keeps the file current without turning it into a full-time job. The most practical approach I’ve found is to tie updates to Google’s release schedule: when a new API version drops, review the release notes and update three things in the skill file.

First, update the pinned version number and any client initialization examples. This sounds trivial, but it’s the change most likely to cause silent failures if missed, because Claude will generate code against the old version and the user won’t notice until they hit a deprecation error. Second, add any new resources, fields, or metrics that are relevant to your team’s workflows. When v24 shipped, that meant adding CartDataSalesView, the all_ cost metrics, and the retail filter criterion type for Shopping campaigns. [11] Third, remove or flag deprecated items. If a field has been removed (as CallAd was in v23), mark it clearly so Claude doesn’t reference it. [11]

Version control the file in Git alongside your other automation code. This gives you a changelog, makes it easy to roll back if an update introduces problems, and lets team members propose changes through pull requests. Treat the SKILL.MD with the same rigor you’d apply to a shared library: changes should be reviewed, tested (by running a few representative prompts against the updated file), and documented.

Keep the file under 8,000 tokens if possible. Claude’s context window is large, but a bloated skill file competes with the user’s actual queries and data for attention. Be selective about what you include. If your team never runs Demand Gen campaigns, don’t encode Demand Gen schemas. If you only use the Python client library, don’t include examples for Java, Ruby, and PHP. The goal is density of relevant information, not completeness for its own sake.

How this changes daily PPC specialist workflows

The honest assessment is that a well-maintained SKILL.MD file doesn’t replace a PPC specialist’s judgment, but it compresses the time between “I need to check something” and “I have an answer I can act on.” Querying campaign performance, scaffolding new campaigns, diagnosing API errors, and generating reporting code are all tasks where Claude with a good skill file operates faster than a human working from documentation alone. The specialist’s role shifts from writing boilerplate code and composing GAQL queries toward reviewing Claude’s output, making strategic decisions, and handling the edge cases the skill file doesn’t cover.

There’s a real tension here, though. The official Google Ads MCP server is read-only, which means Claude can pull data but can’t execute changes. [2] Every mutation Claude generates still requires a human to review and run it. Some teams will see this as a safety feature; others will see it as a bottleneck. In my view, it’s the right constraint for now, especially given how quickly the API is changing. A campaign accidentally set to ENABLED with the wrong bidding strategy can burn through budget in minutes, and no SKILL.MD file is a substitute for a human checking the numbers before hitting execute.

What’s worth watching is how this pattern scales. If your SKILL.MD encodes text_guidelines logic correctly, Claude can enforce brand safety rules on AI-generated ad copy across every campaign your team creates, something that’s tedious and error-prone when done manually across dozens of PMax campaigns. [2] As Google continues to push AI Max and autonomous ad generation, having programmatic guardrails that an LLM applies consistently becomes less of a convenience and more of a requirement. The teams that build these skill files now will have a structural advantage when the API’s monthly releases start compounding in complexity, because their tooling will already be designed to absorb change rather than break under it.

Warsaw Streamer Łatwogang Breaks Guinness World Record for Charity Fundraising

How to Get Started in Digital Marketing

What Is llms.txt and Why It Matters for Your Content

What to Expect at Google Marketing Live 2026

Warsaw Streamer Łatwogang Breaks Guinness World Record for Charity Fundraising

What to Expect at Google Marketing Live 2026