菜单
Listing optimisation, review response strategy, Google Posts, local pack ranking factors, NAP consistency, and category selection for Google Business Profile. Use when optimising GBP listings, managing reviews, or improving local search visibility.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
The engineering navigation layer for Synthex — holds the mission, the current course, the rules of the ship, and routes work to the right existing specialist. Load at the START of any planning, prioritisation, "what's next", roadmap, scope, or new-feature decision. NEVER let work drift off the critical path or add capabilities the ship already carries (see dependency-discipline). NEVER claim done without the verification gate. NEVER merge to production or change prod data without a human gate. ALWAYS trace a task to the NorthStar, the live Linear epic, and an existing system before writing code.
Authenticated browser automation for Synthex — drive real Chrome to log in, screenshot, and audit dashboard/integration surfaces. Use for live visual verification, "audit the dashboard", "check what's connected", or closing the verification gate on /dashboard/* routes. Two backends: the Playwright MCP server (interactive, in-session tools) and the committed CLI scripts (scripts/browser/*.mjs, reliable + headless). RUNS WHERE THE BROWSER + NETWORK + AUTH EXIST — i.e. a local machine, not a network-restricted sandbox.
Synthex API testing enforcer. NEVER mock the database in integration tests — use real Supabase. NEVER skip the 401 (unauthenticated) or 403 (wrong org) test cases. NEVER use pnpm. ALWAYS structure tests as: 401 → 403 → 400 → 200/201 happy path. Activate on ANY request to write API tests, validate endpoints, add test coverage, or check test quality.
Synthex database operations enforcer. NEVER use prisma db push for schema changes — use migrate diff + db execute. NEVER add non-nullable columns without defaults. NEVER write Prisma queries without organizationId scope. ALWAYS use backward-compatible migrations and validate with prisma validate first. Activate on ANY request to change schema, write a query, create a migration, add a model, or modify database operations.
Synthex design system enforcer. NEVER use Inter as a heading font, purple (#8B5CF6) gradients on white, or generic glassmorphism without Synthex tokens. ALWAYS use Space Grotesk headings, #f97316 brand orange, #0f172a slate background, and the Synthex glass token set. Activate on ANY request involving UI, components, styling, layout, visual design, colour, typography, spacing, shadows, animations, or anything a user will see on screen.
Synthex security posture enforcer. NEVER apply generic OWASP checklists without grounding in Synthex's specific threat model. NEVER suggest any auth system other than Supabase. ALWAYS audit: SSRF via validateExternalUrl, JWT tier elevation via resolveVerifiedTier, CORS via CORS_ORIGIN exact-match, org-scope bypass in Prisma. Activate on ANY request to harden security, audit vulnerabilities, review auth patterns, check for injection risks, or assess an attack surface.
| name | google-business-profile |
| description | Listing optimisation, review response strategy, Google Posts, local pack ranking factors, NAP consistency, and category selection for Google Business Profile. Use when optimising GBP listings, managing reviews, or improving local search visibility. |
| metadata | {"author":"synthex","version":"1.0","engine":"synthex-ai-agency","type":"reference-skill","triggers":["google business","GBP","google maps","local listing","business reviews","google posts","local pack","NAP consistency","business categories"]} |
| context | fork |
SYNTHEX connects to Google Business Profile via OAuth to manage locations, reviews, posts, insights, and photos. This skill documents how to optimise GBP listings for maximum local search visibility and how to use Synthex infrastructure to maintain listing health.
| Layer | File | Exports |
|---|---|---|
| Service | lib/google/business-profile.ts | listLocations, getLocationDetails, updateLocation, getReviews, replyToReview, deleteReviewReply, createPost, listPosts, getInsights, listPhotos, getCategories, starRatingToNumber |
| Auth | lib/google/google-auth.ts | getOAuthAccessToken |
| Hook (SWR) | hooks/useGBPLocations.ts | useGBPLocations — returns locations, primaryLocation, syncLocations, refresh |
| Hook (SWR) | hooks/useGBPReviews.ts | useGBPReviews({ locationId?, page?, limit?, rating?, unreplied? }) — returns reviews, pagination, refresh |
| Hook (SWR) | hooks/useGBPInsights.ts | useGBPInsights(locationId?, days?) — returns totals, totalReviews, averageRating, trend |
| Cron (5 AM UTC) | app/api/cron/gbp-monitor/route.ts | Snapshots GBP metrics, fetches new reviews, generates AI reply suggestions (STORED only, NEVER auto-sent) |
| Models | Prisma: GBPLocation, GBPReview (with aiSuggestion field), GBPSnapshot | Per-org location records, review history, daily metric snapshots |
API Routes (8):
| Route | Method | Purpose |
|---|---|---|
/api/google-business/locations | GET | List connected locations |
/api/google-business/locations | POST | Sync locations from Google |
/api/google-business/locations/[locationId] | GET/PATCH | Get or update a specific location |
/api/google-business/reviews | GET | List reviews (with filters) |
/api/google-business/reviews/[reviewId]/reply | POST | Send a reply to a review |
/api/google-business/reviews/[reviewId]/auto-reply | POST | Generate AI reply suggestion |
/api/google-business/posts | GET/POST | List or create Google Posts |
/api/google-business/photos | GET | List location photos |
/api/google-business/insights | GET | Get performance insights |
Run through this 12-point checklist for every connected GBP location:
getCategories('query', 'AU') to searchwebsiteUri fieldregularHours; accurate and current| Rating | Response Window | Priority |
|---|---|---|
| 1-2 stars | Within 24 hours | Critical — damage control |
| 3 stars | Within 48 hours | High — shows you care about improvement |
| 4-5 stars | Within 72 hours | Standard — builds relationship |
Matches the gbp-monitor cron's AI reply suggestion logic:
| Rating | Tone | Approach |
|---|---|---|
| 4-5 stars | Warm, grateful | Thank specifically, mention what they enjoyed, invite return |
| 3 stars | Appreciative, constructive | Acknowledge feedback, mention specific improvements, offer to make it right |
| 1-2 stars | Empathetic, professional | Apologise sincerely, take responsibility, offer offline resolution |
gbp-monitor cron fetches new reviews daily at 5 AM UTCGBPReview.aiSuggestionPOST /api/google-business/reviews/[reviewId]/reply| Type | Expiry | Best For |
|---|---|---|
| What's New | 7 days | Regular updates, news, tips |
| Event | After event date | Workshops, sales, open days |
| Offer | After end date | Promotions, discounts |
createPost(connectionId, locationName, post) using the GBPPost interfaceHow well your listing matches the search query:
How close your business is to the searcher:
How well-known and trusted your business is:
GBPSnapshot: searchViews, mapsViews, websiteClicks, phoneClicks, directionClicksNeed to select categories?
|
+--> Search available categories
| getCategories('your service', 'AU')
|
+--> Select primary category
| Rule: most specific match to your core service
| "Plumber" not "Home Services"
| "Thai Restaurant" not "Restaurant"
|
+--> Select additional categories (3-5)
| Cover secondary services only
| Do not add aspirational categories
| Max 9 additional categories allowed
|
+--> Verify against competitors
Check what categories top-ranking local competitors use
Missing a common category = missed relevance signal
NAP = Name, Address, Phone. Must be identical across all online presence.
GBPLocation.address is the canonical NAP record. All citations must match exactly.
[Business Name]
[Suite/Unit X, ]123 Street Name
Suburb STATE POSTCODE
Australia
Phone: (0X) XXXX XXXX or 04XX XXX XXX
| Type | Count | Purpose |
|---|---|---|
| Logo | 1 | Brand recognition in search |
| Cover | 1 | First impression in listing |
| Interior | 3+ | Show the space customers will experience |
| Exterior | 3+ | Help customers find the location |
| Team | 3+ | Build trust and personal connection |
| Products/Services | 3+ | Showcase what you offer |
listPhotos(connectionId, locationName) to audit current photo inventoryuseGBPInsights(locationId, days) returns totals and 30-day trend data.
| Metric | What It Measures | Good Benchmark |
|---|---|---|
| searchViews | Discovery via Google Search | Trending up month-over-month |
| mapsViews | Discovery via Google Maps | Higher than searchViews for local businesses |
| websiteClicks | Click-throughs to website | >5% of total views for service businesses |
| phoneClicks | Direct phone calls | Conversion signal — track against revenue |
| directionClicks | Navigation requests | Strongest intent signal for physical locations |
Conversion Rate = (websiteClicks + phoneClicks + directionClicks) / (searchViews + mapsViews) * 100
Target: >5% for service businesses, >8% for retail/hospitality
Use the trend array from useGBPInsights to plot 30-day performance.
Correlate changes with:
google-updates-sentinel skill)Reference skill: This is a read-only architecture guide — it documents existing systems and does not generate creative or code output. No capability uplift block is needed.
Adopted from the senior-skill standard so every artefact this connector produces is checked against the locked foundation before it lands.
Reads at every invocation (never cached — re-read each run):
.claude/memory/ceo-foundation.md — GBP compliance (Q3.2.3), universal taboos, verification gates for ranking claims..claude/memory/verification-gates.md — gate state for any claim referenced.Output gate: every client-facing artefact this connector produces routes through brand-voice-enforce before the CEO batched-review queue. A REJECT blocks the artefact until the quoted offending string is fixed.
Evidence standard: every quantitative or factual claim carries exactly one tag — [VERIFIED] / [INFERENCE] / [UNCONFIRMED]. Untagged = defect (.claude/rules/fabel-evidence-standard.md). Never state a projected result as fact.
Spec: see spec.md in this skill directory.