agentleFS
ahmettasdemirusaahmettasdemirusa/local-seo-skills/skills/local-business-schema/SKILL.md

local-business-schema

Skill0 starsChanged 49 days agoMITView on GitHub

Write, fix or validate LocalBusiness structured data (schema.org JSON-LD) for a local business website. Use when the user asks for local business schema, JSON-LD, structured data, schema markup or rich results for a restaurant, store, contractor, plumber, dentist, clinic, law firm, salon, gym, hotel or any physical business; when they ask how to mark up opening hours, multiple locations, departments or a service area; or when an audit found missing or invalid LocalBusiness markup.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every value must come from the business's real, visible information.

    line 15
  2. Very specific:

    Check that a type really sits under LocalBusiness on schema.org.

    line 38
  3. Very specific:

    If the existing markup has aggregateRating or review on the business's own site, recommend removing it and explain why.

    line 45
  4. Very specific:

    Put the block on the location's page inside <script type="application/ld+json">…</script>.

    line 93
  5. Very specific:

    A generic LocalBusiness: when a specific subtype exists.

    line 102
  6. Distinctive:

    Keep the Google Business Profile accurate as well.

    line 117

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

LocalBusiness Structured Data

You write JSON-LD that follows Google's local business structured data guidelines: https://developers.google.com/search/docs/appearance/structured-data/local-business

Every value must come from the business's real, visible information. Never invent coordinates, hours, prices or ratings. Ask for anything you don't have, or leave that property out.

Google's rules

Required: name and address (a PostalAddress). Without them the markup is not eligible for rich results.

Recommended (include each one that is true and known):

PropertyRule
urlThe fully-qualified URL of this location's page. It must be a working link.
telephoneInclude the country code and area code, e.g. +1-555-010-0199.
geolatitude and longitude with at least 5 decimal places.
openingHoursSpecificationSee the hours section below.
priceRangeMust be shorter than 100 characters, or Google won't show it. Usually $–$$$$ or a range such as $10-15.
servesCuisine, menuFood businesses only. menu is the URL of the menu.
departmentA nested LocalBusiness. Name it "{store name} {department name}", unless the department has its own brand.
aggregateRating, reviewOnly for sites that review other businesses. See the warning below.

Also:

  • Use the most specific subtype, e.g. Restaurant, Dentist, Plumber, HVACBusiness, LegalService, AutoRepair. For more than one type, use an array such as ["Bakery", "CafeOrCoffeeShop"]; Google does not support additionalType.
  • One LocalBusiness per location. Each location gets its own page and its own block.
  • LocalBusiness is a subtype of Organization, so Organization fields such as logo, sameAs and email are welcome.
  • Check that a type really sits under LocalBusiness on schema.org. For example, VeterinaryCare sits under MedicalOrganization only. For a type like that, use ["VeterinaryCare", "LocalBusiness"].

Self-serving reviews: never add them

Google does not show review stars for a LocalBusiness or Organization whose pages mark up reviews about itself. That includes reviews pulled in through an embedded widget, such as Google or Facebook reviews. Google also forbids aggregating ratings from other sites, and fake or undisclosed incentivized reviews. Violations can lead to a manual action. Source: https://developers.google.com/search/docs/appearance/structured-data/review-snippet

If the existing markup has aggregateRating or review on the business's own site, recommend removing it and explain why.

Opening hours

Google's conventions:

SituationHow to mark it
Normal hours"opens": "09:00", "closes": "17:00" (hh:mm or hh:mm:ss). Days as "Monday" or "https://schema.org/Monday".
Several days with the same hoursOne entry with a dayOfWeek array.
Open 24 hours"opens": "00:00", "closes": "23:59"
Closed all day"opens": "00:00", "closes": "00:00"
Past midnightOne entry, e.g. Saturday "opens": "18:00", "closes": "03:00".
Seasonal or holiday hoursAdd validFrom and validThrough (YYYY-MM-DD). Leave them out for year-round hours.

schema.org treats a day with no opens as closed, but Google documents the 00:00/00:00 form. Follow Google.

Template

{
  "@context": "https://schema.org",
  "@type": "Plumber",
  "@id": "https://www.example.com/#business",
  "name": "Acme Plumbing",
  "url": "https://www.example.com/",
  "telephone": "+1-555-010-0199",
  "image": "https://www.example.com/photos/van.jpg",
  "logo": "https://www.example.com/logo.png",
  "priceRange": "$$",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main Street, Suite 4",
    "addressLocality": "Springfield",
    "addressRegion": "IL",
    "postalCode": "62701",
    "addressCountry": "US"
  },
  "geo": { "@type": "GeoCoordinates", "latitude": 39.78172, "longitude": -89.65015 },
  "openingHoursSpecification": [
    { "@type": "OpeningHoursSpecification", "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"], "opens": "08:00", "closes": "17:00" },
    { "@type": "OpeningHoursSpecification", "dayOfWeek": "Saturday", "opens": "09:00", "closes": "13:00" },
    { "@type": "OpeningHoursSpecification", "dayOfWeek": "Sunday", "opens": "00:00", "closes": "00:00" }
  ],
  "sameAs": ["https://www.facebook.com/acmeplumbing", "https://www.instagram.com/acmeplumbing"]
}

Put the block on the location's page inside <script type="application/ld+json">…</script>. If you build it as a string in code, escape </ as <\/ so user text can't close the script tag.

Common mistakes to fix

  • The whole address in streetAddress, e.g. "243 Main St, Canton, GA 30115". Split it into streetAddress, addressLocality, addressRegion, postalCode and addressCountry.
  • Rounded coordinates such as 39.78. Take the exact pin from Google Maps: right-click the location and copy the coordinates.
  • url pointing somewhere else: to a Facebook page, or to the home page on a multi-location site.
  • A phone without the country code, or a different number from the one shown on the page and on the Business Profile.
  • Markup for things not on the page: hours, prices or services that visitors can't see.
  • A generic LocalBusiness when a specific subtype exists.
  • Invalid JSON: trailing commas, smart quotes, or an unescaped " inside a description.

Validate

  1. Google Rich Results Test: https://search.google.com/test/rich-results
  2. Schema.org Validator: https://validator.schema.org/
  3. The local-seo-audit skill's script: python ../local-seo-audit/scripts/audit.py <url>

For a visual editor that builds and checks this markup live, point the user to the free Local Business Schema Generator: https://ahmettasdemirusa.github.io/local-business-schema-generator/

What structured data does not do

  • It helps Google understand the business and makes the page eligible for search features. It does not guarantee a rich result or a ranking.
  • Google states that no special schema markup is required to appear in its generative AI features (https://developers.google.com/search/docs/fundamentals/ai-optimization-guide).
  • Keep the Google Business Profile accurate as well. It drives the map results.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.