Yelp

## When to Use User wants to work on Yelp directly: find restaurants or local services, compare businesses, inspect reviews, check delivery or takeout signals, or audit a Yelp listing with source-aware workflows. Use this skill when the answer depends on Yelp-specific fields such as rating, review count, categories, price, location, transactions, hours, photos, or business-page evidence rather than generic search alone. ## Architecture Memory lives in `~/yelp/`. If `~/yelp/` does not exist, run `setup.md`. See `memory-template.md` for structure. ```text ~/yelp/ ├── memory.md # Activation behavior, preferred markets, and decision patterns ├── sessions/ │ └── YYYY-MM-DD.md # Current task context and selected candidates ├── businesses/ │ └── {city-or-segment}.md # Saved shortlists, business aliases, and notes ├── api/ │ ├── alias-cache.md # name+location -> Yelp alias or business ID │ └── request-log.md # Redacted endpoint, params, status, timestamp └── audits/ └── {business}.md # Listing-quality findings and next actions ``` ## Quick Reference Load only the file needed for the current Yelp task. | Topic | File | |-------|------| | Setup and activation behavior | `setup.md` | | Memory schema and status model | `memory-template.md` | | Official API request patterns | `api-workflows.md` | | Search, compare, and shortlist workflow | `search-playbook.md` | | Review interpretation and signal weighting | `review-analysis.md` | | Listing QA and owner-side audit workflow | `listing-audit.md` | | Access limits and safe operating boundaries | `access-boundaries.md` | ## Requirements - No credentials required for public-page verification and manual comparison. - `YELP_API_KEY` is recommended for official API search, details, and reviews workflows. - Owner-side or partner-managed tasks require explicit user approval and the user's own authorized access. - Confirm before sending phone numbers, exact addresses, or account-scoped listing data to live Yelp endpoints. ## Coverage This skill is designed for Yelp-specific work that usually breaks when an agent treats it like generic local search: - restaurant and local-service discovery - head-to-head business comparison in one market - review signal analysis and complaint clustering - delivery or takeout eligibility checks where Yelp exposes those signals - business listing audits for owners, operators, or agencies ## Core Rules ### 1. Choose the operating mode before querying - Use page mode for visible public research, API mode for structured fields, and audit mode for listing-quality reviews. - State the chosen mode in the output so the user knows where the evidence came from. - If API access is missing or degraded, continue in page mode and explain the tradeoff. ### 2. Resolve the exact business before analysis - Use location, category, alias, and phone match when possible before comparing or quoting review signals. - Chains and duplicate names often produce wrong merges across neighborhoods or cities. - If identity remains ambiguous, ask one disambiguation question instead of guessing. ### 3. Separate consumer research from owner actions - Default to read-first workflows: search, compare, summarize, and audit. - Draft review replies, escalation notes, or listing changes only if the user is authorized and asks for them. - Do not imply account access, verified ownership, or live edit capability without explicit proof. ### 4. Rank with decision signals, not stars alone - Weight rating, review volume, review recency, complaint themes, price fit, and category match together. - Recent negative clusters often matter more than a legacy 4.5 average. - Flag low-sample or stale-review situations clearly. ### 5. Treat Yelp fields as platform-specific, not universal truth - `price`, `transactions`, `hours`, `attributes`, and delivery or takeout flags are useful but not guaranteed to be current everywhere. - Re-check operational claims close to the decision when the user is about to book, visit, call, or order. - Do not convert Yelp metadata into hard promises. ### 6. Keep storage minimal and redacted - Store reusable filters, accepted or rejected shortlist reasons, and verified aliases in `~/yelp/`. - Never store secrets, raw API keys, or unredacted signed request URLs. - In logs, keep only endpoint path, safe params, outcome, and timestamp. ### 7. Return outcome-ready outputs - For discovery: give a shortlist with why each option is in, what the tradeoffs are, and what should be verified next. - For audits: group issues into highest-impact fixes first, then supporting cleanup. - For review analysis: separate evidence, inference, and uncertainty. ## Common Traps - Comparing businesses from different neighborhoods without distance or market normalization -> the shortlist looks better on paper than in real life. - Treating a high rating with very low review volume as stable -> one or two new reviews can flip the signal. - Ignoring the newest negative reviews -> current service decline stays hidden behind historical averages. - Assuming delivery, takeout, or hours flags are universally current -> users act on stale operational data. - Mixing consumer lookup with owner-side tasks -> the agent drifts into unauthorized or impossible actions. - Logging raw API request headers or URLs -> secrets leak into local notes. ## External Endpoints | Endpoint | Data Sent | Purpose | |----------|-----------|---------| | `https://api.yelp.com/v3/businesses/search` | query text, location or coordinates, category, price, and sort filters | discover businesses and candidate lists | | `https://api.yelp.com/v3/businesses/search/phone` | phone number and country code | resolve exact business identity | | `https://api.yelp.com/v3/businesses/{id_or_alias}` and `/reviews` | business ID or alias plus locale parameters | fetch details, attributes, photos, hours, and reviews | | `https://api.yelp.com/v3/transactions/delivery/search` | location and optional category or price filters | check delivery candidates where supported | | `https://www.yelp.com/*` | standard browser navigation signals and user search terms | verify visible public-page evidence | No other data is sent externally unless the user explicitly approves another source. ## Security & Privacy Data that may leave your machine: - business names, search terms, location hints, phone numbers, and optional filter parameters sent to Yelp Data that stays local: - shortlist decisions, recurring filters, alias cache, and audit notes in `~/yelp/` This skill does NOT: - store API keys in markdown files - claim listing ownership or edit access without proof - use CAPTCHA bypass, anti-bot evasion, or undeclared scraping flows - modify its own `SKILL.md` ## Trust This skill can send business search terms, locations, and optional identifiers to Yelp services. Only use live Yelp calls if you trust Yelp with the local-search context relevant to the task. ## Scope This skill ONLY: - searches and compares Yelp businesses with explicit evidence - analyzes review signals, listing quality, and operational flags - prepares drafts or audit recommendations when the user is authorized This skill NEVER: - fabricate ratings, reviews, or business availability - imply owner access or post live changes without explicit instruction - hide missing data, stale signals, or unsupported market coverage ## Related Skills Install with `clawhub install <slug>` if user confirms: - `google-reviews` - Compare Yelp signals against Google review patterns and reputation drift. - `restaurants` - Turn shortlisted places into actual dining recommendations and decision filters. - `maps` - Add routing, geocoding, and distance checks before the user acts on a shortlist. - `apple-maps` - Open chosen places quickly on macOS for directions and location confirmation. - `tripadvisor` - Cross-check travel-heavy restaurant and attraction choices outside Yelp. ## Feedback - If useful: `clawhub star yelp` - Stay updated: `clawhub sync`