A portable Agent Skill for Google Business Profile (GBP) optimization — getting a local business to rank in Google Maps and the local pack, and to be surfaced by the AI answer layer (AI Overviews, AI Mode, Gemini, Ask Maps, ChatGPT, Perplexity). Tuned for Turkish businesses, fully usable globally.
The skill is a folder with a SKILL.md (YAML frontmatter: name + description) plus references/, scripts/, and assets/. That folder format is a cross-vendor convention, so this one skill installs into Claude Code, the Claude API, claude.ai, OpenCode, Codex, and other compatible agents. It's the local sibling to modern-seo (which covers website/AI-search strategy).
Most "local SEO" skills are flat checklists that quietly rot as Google changes. This one is built to be best-in-class on the dimensions competitors miss:
- Primary-source-grounded & adversarially fact-checked. Every "Google says X" is traceable to
support.google.com/developers.google.com/blog.google. Claims were verified — and where the SEO community guesses, it's labeled as such. It catches recent changes others repeat wrongly (the July 2025 ranking-doc rewrite, the 2024 removal of GBP chat/call history/website builder, the 2025 Q&A sunset, Ask Maps in 2026, the June 2026 Gemini↔Business-Profile integration). - A hard compliance gate. Every recommendation is checked against Google's Guidelines for representing your business — because a suspension destroys visibility faster than any missing keyword.
- Real GEO / AI-search coverage for local. How GBP feeds Google AI surfaces, and how ChatGPT (Bing web index + Foursquare) and Perplexity (its own index) surface local businesses.
- A genuine Turkey playbook. Turkish categories, directories, address/phone formats, diacritic handling, holiday hours, and the KVKK + İYS (Law 6563) legal layer on review requests.
- Measurement-first + a freshness gate. A weighted audit scorer, grid-rank guidance, the GBP Performance report, and a
policy-registry.jsonthat flags volatile facts to re-verify before asserting. - Hardened on real-world use. Sharpened after being run on an actual Istanbul service-area business (the "rank everywhere," rename-decision, and live-profile-editing guidance all came from that).
gbp-optimize/
├── SKILL.md # workflow + the compliance gate + scenario routing
├── references/
│ ├── ranking-factors.md # the 3 factors, July 2025 rewrite, AI compression, justifications
│ ├── profile-setup.md # claiming, verification, every field, SAB, rename framework, live-editing ops
│ ├── categories.md # primary/secondary, competitor research, TR taxonomy cheat-sheet
│ ├── reviews.md # acquisition, replies, policy (gating/incentives/off-premises)
│ ├── content-media.md # Posts, Products, Services, photos/video
│ ├── citations-nap.md # NAP rules, aggregators, global + Turkish directories
│ ├── ai-search-local.md # AI Overviews / Gemini / Ask Maps / ChatGPT / Perplexity
│ ├── spam-suspension.md # triggers, reinstatement, reporting competitors
│ ├── measurement.md # Performance report, grid rank, UTM, KPIs
│ ├── website-schema.md # LocalBusiness JSON-LD, the Maps-link→sameAs recipe, location pages
│ ├── multi-location-agencies.md # chains, bulk verification, roles, the GBP API
│ ├── turkey.md # the full Turkey playbook
│ └── policy-registry.json # volatile facts + last_verified dates (re-verify when stale)
├── scripts/
│ ├── gbp_audit.py # weighted scorer -> prioritized, risk-first action plan
│ └── localbusiness_schema.py # generate/lint LocalBusiness JSON-LD (Turkey-aware, alternateName)
├── assets/
│ ├── review-request-templates.md # compliant asks + replies (EN + TR)
│ ├── gbp-post-templates.md # Google Post templates (EN + TR)
│ ├── audit-report-template.md # manual audit output structure
│ └── business-context-template.md # persisted audit artifact (resume next session)
├── evals/evals.json
├── LICENSE
└── README.md
In any skill-aware agent, just describe the goal — e.g. "my salon in Kadıköy isn't showing up on Google Maps, help me rank," "audit my GBP," "my profile got suspended," or "how do I show up when people ask ChatGPT for the best dentist near me?" — and the skill triggers.
Run the audit scorer directly:
python scripts/gbp_audit.py --template > answers.json # fill from the live profile
python scripts/gbp_audit.py answers.json -o audit.md # weighted score + action planGenerate matching LocalBusiness schema for the website:
python scripts/localbusiness_schema.py --template > biz.json # fill in
python scripts/localbusiness_schema.py biz.json # JSON-LD <script> blockBoth scripts are stdlib-only (no dependencies).
Because this repo is a standard skill (a SKILL.md at the root), the open skills CLI installs it into whatever agents you have:
npx skills add KyaniteHQ/gbp-optimizeIt auto-detects installed agents — Claude Code, Cursor, Codex, OpenCode, Gemini CLI, GitHub Copilot, Windsurf, and others — and copies the whole skill folder. Requires Node ≥ 18.
npx skills add KyaniteHQ/gbp-optimize -g # global (all projects)
npx skills add KyaniteHQ/gbp-optimize -a claude-code # a specific agent only
npx skills update gbp-optimize # update later
npx skills remove gbp-optimize # uninstall/plugin marketplace add KyaniteHQ/agent-skills
/plugin install gbp-optimize@kyanite-skills
Run /skills to confirm it loaded. Update later with /plugin marketplace update.
OpenCode reads ~/.claude/skills natively, so cloning into the Claude personal skills directory covers both:
git clone https://github.com/KyaniteHQ/gbp-optimize.git ~/.claude/skills/gbp-optimizeFor a project-scoped install (committed to a repo, shared with a team), put it at .claude/skills/gbp-optimize/ instead.
git clone https://github.com/KyaniteHQ/gbp-optimize.git ~/.agents/skills/gbp-optimizeDownload this repo as a .zip, then upload it under Settings → Features (Custom Skills; requires a plan with code execution enabled). The folder inside the zip must contain SKILL.md at its root.
Drop the folder into whatever directory your agent scans for skills. It's self-contained — no build step, no dependencies.
npx skillsinstalls:npx skills update gbp-optimize.- Marketplace installs:
/plugin marketplace updatein Claude Code. - Manual clones:
git -C ~/.claude/skills/gbp-optimize pull.
| Tool | Check |
|---|---|
| Claude Code | /skills, or ask "what skills are available?" |
| OpenCode | Ask "what skills are available?" |
| Codex | The skill appears in available skills; invoke via its name |
| claude.ai | Listed under Settings → Features |
The version lives in .claude-plugin/plugin.json and is mirrored by a matching git tag (e.g. v1.1.0). The KyaniteHQ/agent-skills marketplace references this repo via an unpinned github source, so it tracks main and always offers the latest released version.
To cut a release: bump version in plugin.json, update the "What changed" note in SKILL.md, commit, then tag (git tag -a vX.Y.Z -m "…" && git push origin vX.Y.Z).
GBP changes often. Before asserting a volatile fact (a feature, a limit, a policy, a form name), check references/policy-registry.json; if an entry's last_verified is older than its stale_after_days, re-verify it against the cited primary source and update the date. Last full review: 2026-06.
Grounded in Google's primary documentation — Improve your local ranking (answer/7091), Guidelines for representing your business (answer/3038177), and the verification, review-policy, suspension, and AI-optimization guides — plus high-trust local-SEO sources (Sterling Sky, BrightLocal, Whitespark, Search Engine Land/Roundtable) clearly labeled as community observation. Full source lists live in SKILL.md and each reference file.
MIT © KyaniteHQ.
Disclaimer. This skill is an independent tool and is not affiliated with, endorsed by, or sponsored by Google. "Google", "Google Maps", "Google Business Profile", "Google My Business", and "Gemini" are trademarks of Google LLC, used here nominatively to describe the product this skill helps optimize. Guidance is best-effort and not legal advice — for KVKK/İYS or other legal questions, consult a qualified professional.