gaql-reference — Claude Code skill for GAQL: features and setup
This skill helps draft Google Ads GAQL queries and understand their resources, fields, and filters. Use it when building a report query or checking its structure.
npx skills add cognyai/claude-code-marketing-skills --skill gaql-reference -a claude-codeWhat gaql-reference does
The skill covers GAQL query structure, including selected fields, the resource being queried, filters, sorting, row limits, and parameters. Its reference includes resources for campaigns, ad groups, search terms, geographic performance, and change records. Ask for a query pattern on a specific subject, such as search-term reporting or Quality Score analysis.
With Cogny MCP tools connected, the skill can submit a Google Ads query and look up API documentation. The reference still works without that connection, but it cannot run queries. Microsoft Ads uses a separate reporting tool rather than GAQL, so Google Ads query syntax does not apply there.
What it helps with
- draft a GAQL report for triggered search queries
- choose a resource for geographic performance reporting
- filter campaigns by status and date range
- check a query's structure before running it
- find a query pattern for auditing account changes
Example prompts for the agent
- Write a GAQL query for a Google Ads search-term report covering the last 30 days.
- Show me a query pattern for Quality Score analysis.
- Which resource should I use for a geographic performance report?
How to install gaql-reference
1Skills CLI (Vercel)
npx skills add cognyai/claude-code-marketing-skills --skill gaql-reference -a claude-code2Manually: put the files in place
~/.claude/skills/gaql-reference/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gaql-reference/
1Skills CLI (Vercel)
npx skills add cognyai/claude-code-marketing-skills --skill gaql-reference -a codex2Manually: put the files in place
.agents/skills/gaql-reference/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add cognyai/claude-code-marketing-skills --skill gaql-reference -a cursor2Manually: put the files in place
.cursor/skills/gaql-reference/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install cognyai/claude-code-marketing-skills gaql-reference2Manually: put the files in place
.github/skills/gaql-reference/SKILL.md1Skills CLI (Vercel)
npx skills add cognyai/claude-code-marketing-skills --skill gaql-reference -a gemini-cli2Platform CLI
gemini skills install https://github.com/cognyai/claude-code-marketing-skills --path skills/gaql-referenceManually: put the files in place
.devin/skills/gaql-reference/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add cognyai/claude-code-marketing-skills --skill gaql-reference -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about gaql-reference
How do I install gaql-reference in Claude Code?
Run npx skills add cognyai/claude-code-marketing-skills --skill gaql-reference -a claude-code. The skill file is at ~/.claude/skills/gaql-reference/SKILL.md.
What does gaql-reference do?
It helps you compose and understand Google Ads GAQL queries, with guidance on resources, fields, filters, and report patterns.
Can gaql-reference run Google Ads queries?
Yes, when Cogny MCP tools are connected and a Google Ads account is accessible. Without that connection, it provides query guidance but does not execute queries.
