How to Build a Local SEO Website With Claude Code and Astro

# Resource 1: Site Architecture + Silo Prompt

**Where to run it:** Claude Code, with the DataForSEO MCP connected.
**What it does:** Turns your business + services + service areas into a keyword-validated
site architecture, a visual silo map (Mermaid), and a build-ready CSV.

---

## How to use
1. Fill in the four inputs in the `<inputs>` block below.
2. Paste the whole prompt into Claude Code.
3. Claude pulls search volume + difficulty from DataForSEO, then outputs the silo map and CSV.
4. Save the CSV. It becomes the source of truth for the Astro build later.

---

## The prompt (copy everything below)

```
You are a local SEO site architect. Build a keyword-validated website architecture for a
local service business, then output a silo map and a CSV the developer will use to generate
pages.

<inputs>
business_type: {business_type}            # e.g. "plumbing company"
brand_name: {brand_name}                  # e.g. "BlueLine Plumbing"
primary_location: {primary_location}      # e.g. "Austin, TX"
service_areas: {service_areas}            # e.g. ["Round Rock", "Cedar Park", "Pflugerville", "Georgetown"]
services: {services}                      # e.g. ["water heater repair", "drain cleaning", "leak detection", "repiping", "emergency plumbing"]
</inputs>

STEP 1 - KEYWORD VALIDATION (DataForSEO)
For every service and for every service-area combination, use the DataForSEO MCP to fetch:
- monthly search volume
- keyword difficulty
Query both the bare service ("water heater repair") and the localized variants
("water heater repair {primary_location}", "water heater repair {each service_area}").
Also classify each keyword's intent as transactional or informational.
If a service has effectively no transactional search demand, flag it but still keep its
service page (it supports entity completeness and internal linking).

STEP 2 - APPLY THE HIERARCHY
Build exactly this structure. Do not invent extra silos.
- Homepage (targets "{business_type} {primary_location}")
- Services hub  (parent)  ->  one dedicated child page per service
- Service Areas hub (parent)  ->  one dedicated child page per service_area
- Standard pages: About, Contact
- Note (do not build): an informational/blog silo is a recommended next step. List 5
  example blog titles at the end, but do not add them to the CSV.

Internal linking rules:
- Every service page links up to the Services hub and across to the 2-3 most relevant area pages.
- Every area page links up to the Service Areas hub and across to every service page.
- The homepage links to both hubs.

STEP 3 - OUTPUT A (Mermaid silo map)
Output a Mermaid `graph TD` diagram showing Homepage -> hubs -> child pages, so the silo is
visible at a glance. Keep labels to page titles.

STEP 4 - OUTPUT B (CSV)
Output a CSV inside a code block with EXACTLY these columns:
page_title,target_keyword,search_volume,difficulty,slug,page_type,parent,intent,purpose,internal_links

Where:
- page_type is one of: homepage | hub | service | area | standard
- parent is the slug of the parent page (blank for homepage)
- slug is lowercase, hyphenated, no leading slash (e.g. services/water-heater-repair)
- internal_links is a pipe-separated list of slugs this page should link to
- purpose is one sentence on what the page is for and who it serves

STEP 5 - SUMMARY
End with: total page count, a transactional-vs-informational split, and the 5 example blog
titles for the future informational silo.
```

---

## Notes
- This resource is industry-agnostic. Swap the `<inputs>` and it works for roofers,
  electricians, med spas, etc.
- The 40-50% area-page content differentiation rule is enforced later, at content
  generation time, using Resource 4. This prompt only sets the structure.
- Keep the CSV column order exact. The Astro content-collection step depends on it.

# Resource 2: Website Style-Guide Prompt

**Where to run it:** Claude (or Claude Design as context).
**What it does:** Produces a complete brand style guide you paste into Claude Design so the
homepage comes out premium and on-brand, not generic AI slop.

---

## How to use
1. Fill the inputs. If you have a Dribbble or competitor reference, describe it or paste a
   screenshot.
2. Run the prompt. Save the output as `style-guide.md`.
3. Paste that style guide into Claude Design before you ask it to build the homepage.

---

## The prompt (copy everything below)

```
You are a senior brand and web designer. Create a production-ready style guide for a local
service business website. The result must read as premium and trustworthy, never templated
or "AI-generated".

<inputs>
business_type: {business_type}
brand_name: {brand_name}
brand_personality: {brand_personality}   # e.g. "established, dependable, modern, not corporate"
primary_color_hint: {primary_color_hint} # optional, e.g. "deep blue" or "leave open"
reference: {reference}                    # optional: describe the Dribbble/competitor look or attach a screenshot
audience: {audience}                      # e.g. "homeowners 30-65 needing fast, trustworthy service"
</inputs>

Produce the style guide with these sections:

1. BRAND ESSENCE
   - One-line positioning and 3 adjectives that govern every visual choice.

2. COLOR PALETTE
   - Primary, secondary, accent, plus neutral scale (background, surface, border, text).
   - Give HEX values and a one-line usage rule for each.
   - Ensure text/background pairs meet WCAG AA contrast. State the ratios.

3. TYPOGRAPHY
   - Heading font + body font (use widely available Google Fonts).
   - Type scale (h1-h6, body, small) in rem, with line-heights and weights.

4. LAYOUT & SPACING
   - Spacing scale, max content width, grid approach, border-radius and shadow tokens.

5. COMPONENT STYLING
   - Buttons (primary/secondary/states), cards, nav, forms, the hero, trust bar, footer.
   - Describe look and behavior in enough detail to rebuild without guessing.

6. IMAGERY DIRECTION
   - The visual treatment for photos and any illustration. (This must align with the image
     style guide from Resource 3.)

7. VOICE & TONE
   - 3 do's and 3 don'ts for headline and body copy, with one rewritten example.

8. ACCESSIBILITY
   - Contrast, focus states, tap target sizes, motion-reduction note.

Output as clean markdown ready to paste into Claude Design as design context.
```

---

## Notes
- Keep the chosen fonts to common Google Fonts so they survive the Astro build.
- Section 6 must stay consistent with Resource 3 so the generated images match the site.

# Resource 3: Image Style-Guide Prompt

**Where to run it:** Claude to generate the style wrapper, then GPT Image or Nano Banana Pro
to generate the actual images.
**What it does:** Builds a reusable "style wrapper" so every image you generate shares the
same camera, lens, lighting, and grade. You only ever change the `{scene}`. This is what
keeps the site's imagery cohesive instead of looking like random AI pictures.

---

## How to use
1. Run Part A once to lock your style wrapper. Save the output.
2. For every image, use Part B: drop your scene into `{scene}`, keep the wrapper untouched,
   paste the full result into GPT Image or Nano Banana Pro.

---

## Part A: Generate the style wrapper (run once)

```
You are a photography art director. Define a single reusable image style for a local service
business brand so every generated image looks shot by the same photographer on the same day.

<inputs>
business_type: {business_type}
brand_personality: {brand_personality}   # match Resource 2
color_palette: {color_palette}           # paste the HEX palette from Resource 2
mood: {mood}                             # e.g. "clean, bright, trustworthy, real"
</inputs>

Output a STYLE WRAPPER as a single reusable block specifying:
- camera body and lens (e.g. "shot on Sony A7IV, 35mm prime")
- focal length, aperture, depth of field
- lighting setup (natural/soft/studio, direction, time of day)
- color grade and white balance, tied to the brand palette
- composition rules (framing, headroom, rule of thirds, negative space)
- texture/finish (clean editorial, no HDR, no oversharpening)
- a NEGATIVE list (no text, no logos, no watermarks, no distorted hands, no stocky cheesiness)

Format it so a scene description can be prepended and everything after stays fixed.
```

## Part B: The reusable image prompt template

```
{scene}

--- STYLE (do not change) ---
{paste your locked STYLE WRAPPER from Part A here}
```

Example `{scene}` values for a plumbing site:
- "A professional plumber in clean branded uniform inspecting a modern tankless water heater
  in a bright residential utility room"
- "Close-up of hands using a pipe wrench on a chrome fixture under a kitchen sink, shallow
  depth of field"
- "Exterior of a tidy suburban home at golden hour with a branded service van in the driveway"

---

## Notes
- Generate hero, service, and area imagery all through the same wrapper so the gallery feels
  like one shoot.
- Resize every final image to web spec before use (see the build step). Keep heroes optimized
  for fast LCP.
- The negative list is what removes the "AI slop" tells. Keep it strict.

# Resource 4: Local-Area Research Prompt

**Where to run it:** Claude Code or Claude with web access.
**What it does:** Produces a genuinely different research brief for each service area, so your
area pages carry real local specifics (housing, piping, common issues) instead of reworded
boilerplate. This is what makes the 40-50% content-differentiation rule real.

---

## How to use
1. Run this once per service area. Change only `{specific_area}` each time.
2. Save each brief as `research/{area-slug}.md`.
3. Feed the matching brief into the area-page content generation during the build.

---

## The prompt (copy everything below)

```
You are a local market researcher for a {business_type}. Research the specifics of one
service area so the website's page for it can speak with genuine local authority. Use real,
verifiable details. If you are unsure of a fact, say so rather than inventing it.

<inputs>
business_type: {business_type}            # e.g. "plumbing company"
specific_area: {specific_area}            # e.g. "Pflugerville, TX"
</inputs>

Research and output these sections:

1. HOUSING STOCK
   - Dominant home eras and styles, typical age, common construction types.
   - Approximate share of older vs newer builds.

2. SYSTEMS & MATERIALS (tie to {business_type})
   - For plumbing: piping materials common to the era/area (e.g. cast iron, galvanized,
     polybutylene, copper, PEX), slab vs basement, water heater types.
   - Generalize this section to the relevant systems for other industries.

3. LOCAL CONDITIONS
   - Water hardness/quality, soil type and movement, freeze risk, drought/heat, flood zones.
   - Anything in the local environment that drives service demand.

4. COMMON PROBLEMS
   - The 5-7 issues most likely in this area, each tied to a cause from sections 1-3.

5. LOCAL TEXTURE
   - Real neighborhoods/subdivisions, landmarks, and any relevant local codes or permits.

6. CONTENT ANGLES
   - 5 specific, area-true talking points the page should make that would NOT apply
     identically to a neighboring town. These are what create the 40-50% differentiation.

Keep it factual and specific. Flag any claim you could not verify.
```

---

## Notes
- The value is in section 6: it forces each area page to say something locally true and
  distinct, which is both better for users and what separates this from spun content.
- Run it fresh per area. Do not reuse one area's brief for another.

# Resource 5: Schema Identifier Prompt

**Where to run it:** Claude Code, with the CSV from Resource 1.
**What it does:** Tells you exactly which schema (structured data) each page needs and outputs
ready-to-use JSON-LD. Pair it with `schema-checklist.md` as the reference.

---

## How to use
1. Have your Resource 1 CSV ready.
2. Paste the prompt below into Claude Code and attach/point it at the CSV.
3. Claude returns a per-page schema plan plus JSON-LD blocks to drop into the Astro build.

---

## The prompt (copy everything below)

```
You are a structured-data specialist. For each page in the attached site architecture CSV,
determine the required schema and output valid JSON-LD.

<inputs>
business_type: {business_type}            # e.g. "plumbing company"  -> use the matching schema.org type (e.g. Plumber)
brand_name: {brand_name}
nap: {nap}                                # name, address, phone (must be identical everywhere)
csv: {attach the Resource 1 CSV}
</inputs>

RULES (page_type -> schema):
- homepage: LocalBusiness (use the most specific type, e.g. Plumber) + WebSite + BreadcrumbList
- hub:      CollectionPage + BreadcrumbList
- service: Service (with provider, areaServed, serviceType) + BreadcrumbList + FAQPage if the page has FAQs
- area:     LocalBusiness or Service with areaServed set to that area + BreadcrumbList
- standard (Contact): ContactPage / Organization as appropriate + BreadcrumbList
- standard (About):   AboutPage + BreadcrumbList

REQUIREMENTS:
- NAP must be byte-identical across every block (matches the GBP exactly).
- Set sameAs to the brand's real profiles if provided.
- Do not fabricate aggregateRating or reviews. Only include them if real review data is given.
- Use absolute URLs based on the page slugs.

OUTPUT:
For each page output: page_title, slug, the list of schema types, and a complete JSON-LD
<script type="application/ld+json"> block ready to paste into the page head.
End with a validation reminder to run every page through Google's Rich Results Test.
```

---

## Notes
- The "use the most specific type" rule matters: `Plumber` beats generic `LocalBusiness` for
  entity clarity. For other industries, swap to the correct schema.org subtype
  (Electrician, RoofingContractor, HVACBusiness, etc.).
- Never invent ratings. Fake `aggregateRating` is a manual-action risk and breaks trust.