small-business-website-spec
Skill121 starsChanged 5 months agoMITView on GitHub
Planning reference for rebuilding a small business website: page structure, copy voice, estimator widget, SEO requirements, form handling, DNS migration, and the no-code vs static-framework decision (Base44 vs Astro/Vercel vs WordPress). NOT a deploy tool for no-code platforms — no-code builders have no agent-accessible CLI. Includes the honest reasons we pivoted from no-code to a static framework.
In this repository15 other files it gives its agents.
- agent-cheatsheet-builderSkill
- construction-agentSkill
- crm-liteSkill
- estimator-engineSkill
- financial-analysisSkill
- grasshopper-voicemail-monitorSkill
- hermes-production-opsSkill
- lead-to-paymentSkill
- mailchimp-integrationSkill
- marketing-campaign-builderSkill
- outlook-graphSkill
- quickbooks-onlineSkill
- small-business-ai-transformationSkill
- stripe-link-cliSkill
- stripe-paymentsSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 29
NOT for automated no-code deployment — no agent-accessible CLI exists there
- Distinctive: line 46
How to choose: if the site needs user accounts, database writes, or complex app behavior, no-code (or a real framework with a backend) …
- Distinctive: line 48
If it's a marketing site — pages, photos, an estimator widget, a contact form — a static build is cheaper, faster to load, better for SEO, …
- Distinctive: line 132
Add a verify-script check for cheap-sounding words: *affordable, budget-friendly, cheap, competitive pricing, "we work with many budgets," …
- Distinctive: line 138
If you advertise a guarantee, state its exceptions wherever the guarantee appears — exceptions buried on a distant page erode trust and …
- Distinctive: line 158
Stock photos: verify licensing before a live launch.
- Very specific: line 163
Region classification sync: if you update region tiers in estimator-engine, update the estimator widget options AND the rate-card file.
- Distinctive: line 173
GitHub PATs expire: if the clone URL embeds a PAT, pushes fail mysteriously ~30 days later.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
Small Business Website Spec
⚠️ This is a planning/specification reference, not a deployable skill for no-code platforms. Base44 and similar builders have no CLI the agent can call — building there means dragging pages in a web editor, done by a human. A static framework (Astro/Hugo/Eleventy) on Vercel/Netlify/Cloudflare Pages is agent-workable: the agent can clone the repo, edit, run checks, and push. Either way, this skill is the spec: page structure, copy voice, estimator widget, SEO checklist, form handling, and the DNS cutover runbook.
When to Use
- Planning a website rebuild for a small service business
- Choosing between no-code (Base44, Wix Studio, Squarespace) and a static framework (Astro on Vercel)
- Page structure, copy voice, estimator widget, SEO requirements
- DNS migration notes (registrar → new host)
- Wiring contact-form submissions into the agent (email → IMAP polling → CRM → Telegram)
- NOT for automated no-code deployment — no agent-accessible CLI exists there
Platform Decision: No-Code vs Static Framework
Both paths are valid. Pick by workload, not by hype:
| Factor | No-code (Base44 etc.) | Static framework (Astro/Vercel etc.) |
| Who builds it | Human, in a web editor (drag-and-drop) | Human or AI coding agent, in a repo |
| Time to first draft | Hours | Days |
| Monthly cost | ~$50/mo for domain connection + GitHub sync on Builder-tier plans | $0 on Vercel/Netlify free tiers (or an existing plan) |
| SEO | Prerendering exists but is often a black box you can't control | Static HTML — fully crawlable, you own everything |
| Export/exit | Frontend only; backend (auth, DB, entities) stays on the platform SDK — you can't self-host by exporting | It's your repo. Portable by definition. |
| Site types that fit | Interactive apps, member areas, anything needing a real backend | Marketing sites: pages + one estimator widget + one contact form |
| Mutability | A living app on their platform — platform updates can change rendering without you touching anything | An immutable build artifact on CDN edge — it can't break while untouched |
| Agent's role | Paying for the subscription (via stripe-link-cli) and writing the spec — not the build | Full repo work: edit, test, verify, push, deploy |
How to choose: if the site needs user accounts, database writes, or complex app behavior, no-code (or a real framework with a backend) earns its subscription. If it's a marketing site — pages, photos, an estimator widget, a contact form — a static build is cheaper, faster to load, better for SEO, and fully agent-workable.
We started on Base44 (for a hackathon "the agent bought the subscription" beat,
which is what stripe-link-cli is for), then pivoted to Astro-on-Vercel for the
production site because a static marketing site had zero backend needs. The
pivot itself was cheap because the spec (this document) was written before
either build — page inventory, copy voice, estimator logic, and SEO checklist
all carried over unchanged.
Prerequisites
- Domain at a registrar (GoDaddy or similar) — keep DNS there, repoint records
- Static path: git repo, framework (Astro recommended), hosting account (Vercel/Netlify)
- No-code path: builder account, manual signup + build in the web interface
- Form delivery: an email API (Resend/Postmark/SES) or SMTP — forms should email the owner's inbox
- Payment for no-code subscriptions via the
stripe-link-cliskill (agent handles the spend, human handles the build)
Website Architecture
Pages needed (marketing site for a service business)
- Home — hero image, value proposition, primary CTA ("Get Free Estimate"), estimator above the fold
- Service pages — one per service line (built from a template route; each names the reader's exact situation in the first two sentences)
- Service area / location pages — one per market city (template route, real local copy, not doorway spam)
- Realtors & property managers — the B2B repeat-revenue page, if referrals drive the business
- About / Why Us — owner story, process steps, trust signals, real photos
- Gallery — real job photos, captioned
- FAQ — include a "what makes you different from everyone else?" answer
- Contact — form with estimator pre-fill flow
- Reviews — embedded review widget (or hold back until the widget is wired)
- Thank you —
noindex, conversion event fires here - Terms — warranty/terms as a proper page (not a PDF scan)
- 404, plus
robots.txt,llms.txt(for AI/agentic search),sitemap-index.xml
Estimator tool integration
The estimator is the conversion hook AND the differentiator. Pricing logic
lives in ONE place (see estimator-engine skill; a rate-card.json both the
website widget and the agent read is the cleanest split).
- Input: square footage, region tier, property type (residential/commercial/apartment), add-ons
- Output: a ±15% range, never a single number, never internal line-item math
- Flow: result → one tap → contact form pre-filled with all inputs + quoted range
- Mobile-first: thumb-reachable controls, ≤60 seconds, ≤8 taps
- The website widget, the agent's chat estimator, and the rate-card file
must all read from the same rate card. If a price changes, change the rate
card first; both consumers pick it up. Canonical source:
estimator-engine.
Contact form handler
- Serverless function (or the host's form feature) receives the POST
- Email API (Resend etc.) delivers to the owner's inbox — reply-to set to the submitter so the owner can hit Reply
- Honeypot spam field (hidden "company" input — if filled, reject silently)
- Validate: required core fields, plus "at least one of phone or email"
- Carrying estimator data into the form? Keep it as structured fields in the submission email — the agent's inbox monitor parses them (see below)
- Optional webhook to the agent — but see "Lead intake" before exposing one
Lead intake (agent integration)
Two ways to get form submissions to the agent:
A. IMAP polling (recommended default). The form emails the owner's inbox
with a stable subject prefix (New website lead: ...) and a structured
plain-text body. A no_agent=True cron script polls the inbox every 3 min,
parses the fields, logs to CRM, and texts the owner's Telegram. Latency ~3 min
— irrelevant for a few leads a week. No public endpoint, nothing to attack.
Full pattern: grasshopper-voicemail-monitor skill and its notification-email
reference.
B. Webhook (faster, more surface). The form handler POSTs straight to an agent endpoint. You get instant delivery but you must expose, secure, rate- limit, and monitor a public URL on the agent box. Only worth it at volume.
Choose A unless leads/minute is a real metric for you. The webhook code can stay in the form handler, dormant, if you want the option open.
Content guide
Copy voice
- Premium-because-[your real differentiator] — never "affordable," "budget-friendly," "cheap" (they attract price-shoppers, not your buyers)
- Lead with the outcome (it works, it's guaranteed, it's permanent) — not the chemistry
- Name the reader's exact situation in the first 2 sentences of every service page
- Specificity = trust: real cities, real timeframes, real guarantee terms
- ~7th-grade reading level, short sentences
Banned-word check
Add a verify-script check for cheap-sounding words: affordable, budget-friendly, cheap, competitive pricing, "we work with many budgets," best-in-class, world-class, "look no further." Ban list lives in the repo and runs in CI — banned words slip back in with every copy edit otherwise.
Guarantee
If you advertise a guarantee, state its exceptions wherever the guarantee appears — exceptions buried on a distant page erode trust and invite disputes.
Common Pitfalls
- Contact-form cutover risk: the OLD site's form probably works and goes to the owner's inbox. Do NOT repoint DNS until the new form is verified delivering to that same inbox on a staging domain. Breaking a working lead path is worse than keeping the old site live another week.
- DNS propagation: 24-48h. Save old DNS values for instant rollback.
- Email routing: changing A/CNAME records is fine, but MX records stay
pointed at the email host (e.g. Workspace:
imap.secureserver.net/smtpout.secureserver.net). Repointing MX silently breaks the business's email. - Mobile-first: most service-business leads come from phones. Test at 320px, 375px, 414px widths.
- 301 redirects: map old (especially WordPress) URLs → new pages before cutover, or years of accumulated SEO equity 404s overnight.
- Banned words: enforce via the verify script, not vigilance.
- Terms & conditions: a scanned-image PDF has no extractable text — transcribe it into a real page.
- Stock photos: verify licensing before a live launch; "we scraped them from our old site" is not a license.
- Browserless agent box: no-code checkout and Lighthouse audits need a
browser. The agent can't drive a web UI without Chromium
(
npx playwright install --with-deps chromium); run audits via web tools. - Region classification sync: if you update region tiers in
estimator-engine, update the estimator widget options AND the rate-card file. All three must match. Canonical source:estimator-engine. - No-code export is a one-way door: the frontend exports; the backend doesn't. If you start on no-code, treat it as a prototype — don't wire business logic (auth, DB, entities) into it that you'll have to rebuild.
- Agent pushes to
main: for a 1-2 person shop, direct-push with a quality gate (tests + verify script) is faster than PR review. Whatever you choose, make it a written convention — agents follow conventions, they don't infer them. - GitHub PATs expire: if the clone URL embeds a PAT, pushes fail
mysteriously ~30 days later. Check the token's expiry when setting up,
and note the
git remote set-urlfix before it bites.
DNS Configuration (registrar → Vercel example)
Type: CNAME
Name: www
Value: cname.vercel-dns.com
Type: A
Name: @
Value: 76.76.21.21 (Vercel default)(No-code hosts give you their own CNAME/A targets — same idea.)
Do NOT touch MX records — email stays with the email host.
Cutover order:
- New contact form verified delivering to the owner's inbox (staging domain)
- Owner sign-off on content + design
- THEN repoint DNS
- Old DNS values saved for instant rollback
Verification Checklist
Quality gate (automated — run before every push)
- Every page renders static HTML with copy in the raw HTML (no client-only content)
- Unique title (≤60 chars) + meta description (≤155 chars) per indexable page
- Exactly one H1 + substantial body copy per page
- Zero banned words (enforced by script)
- Estimator output matches the agent's chat estimator (same rate card, test N quotes)
- Guarantee caveats reachable from every page mentioning "guarantee"
- Structured data (LocalBusiness, Service, FAQPage) + tap-to-call on every page
- robots.txt, llms.txt, sitemap-index.xml present; /thank-you is noindex
- Unit tests pass (pricing engine + form validation)
Pre-cutover (manual)
- Owner sign-off on the site
- Form submissions verified delivering to the owner's inbox on the real domain
- Schema.org validates (Google Rich Results Test)
- Lighthouse mobile: Performance ≥90, SEO ≥95, Accessibility ≥90
- Real photos on the site (machines/equipment/jobs, not stock)
Post-cutover
- DNS propagated (
dig yourdomain.com) + HTTPS working - 301 redirects from old URLs live
- Email MX records preserved (don't break email)
- Search Console + Bing Webmaster verified; sitemap submitted
- Analytics events firing (estimator_start, estimator_complete, form_submit, call_click)
- Mobile responsive verified on real devices
- Lead-intake monitor (if used) picking up form submissions → CRM → Telegram
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
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.

