# Yelp

> Search Yelp businesses and reviews, compare local options, and audit listing quality with official APIs, public pages, and safe action boundaries.

- Skill: `dvcrn/yelp` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add dvcrn/yelp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/yelp/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/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`