How to Add User Case Pages

This guide explains how to add a new user case page to the SkillBoss pSEO system without changing React code.

The current system is JSON-driven:

• Source file: /content/use-cases/pseo-pages-v1.json
• List page: /use-cases
• Detail page pattern: /use-cases/[slug]
• Rendering logic: lib/use-case-pages.ts

If you follow this guide, you should only need to edit the JSON file.

What Happens When You Add a Record

Each object inside pseo-pages-v1.json becomes one public page.

Example:

{
  "slug": "run-one-person-agency-ai-automation",
  "title": "How to Run a One-Person Agency with AI Automation",
  "meta": "You are a freelancer who wants agency-level output...",
  "urlPrefix": "use-cases"
}

This will be rendered as:

/use-cases/run-one-person-agency-ai-automation

Important:

• The current implementation publishes all records under /use-cases/[slug]
• urlPrefix is kept in the data for future expansion, but it does not currently change the public route

Required Fields

Every record must include these fields:

{
  "slug": "unique-page-slug",
  "title": "Page title / H1",
  "meta": "Meta description",
  "category": "Category label",
  "before": "Pain point / current state",
  "after": "Outcome after using SkillBoss",
  "sections": [],
  "steps": [],
  "faq": [],
  "related": [],
  "heroImage": "https://...",
  "heroAlt": "Accessible image description",
  "ctaText": "Primary CTA copy",
  "ctaUrl": "https://...",
  "authority_citations": []
}

If one of these is missing, the admin preview validator should flag it.

Field Format Rules

slug

Rules:

• Must be unique across the whole file
• Use lowercase letters, numbers, and hyphens
• Do not use spaces
• Keep it descriptive and SEO-friendly

Good:

build-ai-sales-call-prep-system

Bad:

Build AI Sales Call Prep System
build_ai_sales_call_prep_system
sales

title

Rules:

• This becomes the page H1
• Keep it readable and specific
• Prefer “How to …” / “Build …” / “Monitor …” phrasing for search intent

meta

Rules:

• Write it like a real search snippet, not keyword stuffing
• Usually 120-160 characters is ideal
• Explain the outcome clearly

before and after

Rules:

• before should describe the painful current state
• after should describe the improved future state after using SkillBoss
• These fields are displayed near the top of the page, so they need to be concise and high-signal

sections

Format:

[
  {
    "heading": "Why Manual Work Breaks at Scale",
    "content": "<p>HTML paragraph content here.</p>"
  }
]

Rules:

• heading becomes an H2
• content is HTML and is rendered directly
• Use semantic HTML like <p>, <ul>, <ol>, <a>
• Do not paste broken HTML

steps

Supported shapes:

{ "name": "Step title", "text": "Step description" }

or

{ "title": "Step title", "description": "Step description" }

or

{ "title": "Step title", "content": "Step description" }

Recommendation:

• Prefer name + text for consistency

faq

Supported shapes:

{ "q": "Question?", "a": "Answer." }

or

{ "question": "Question?", "answer": "Answer." }

Recommendation:

• Prefer q + a for consistency
• Write 5 strong FAQs that answer real objections or search intent

related

Format:

[
  {
    "slug": "another-page-slug",
    "title": "Related page title"
  }
]

Rules:

• Prefer slugs that already exist in the same JSON file
• If a related slug does not exist, the UI will fall back to a safe related page, but this is not ideal

authority_citations

Format:

[
  {
    "source": "HubSpot",
    "claim": "Teams using intent data see higher conversion rates",
    "context": "Supports the argument about timing-based outreach"
  }
]

Rules:

• Use credible sources only
• Each citation should support a specific argument in the page
• Best practice is to also include a real source URL in the section body when possible

Safe Workflow For Marketing

1. Duplicate an existing good record in pseo-pages-v1.json
2. Replace the content field-by-field
3. Keep the same JSON structure
4. Confirm the new slug is unique
5. Confirm related.slug references are real when possible
6. Upload the updated JSON into the admin preview screen
7. Check validation output before asking engineering to publish

Admin Preview Checklist

Use the admin page:

/admin/use-cases

Before publish, confirm:

• Record count looks correct
• No validation issues
• Slugs are clean and unique
• Category breakdown looks reasonable
• The first slug preview matches expectation

Run the release-safe check from the repo root:

pnpm check:use-cases

That command verifies:

• JSON validation passes
• Every published slug resolves through the shared adapter
• Every page has render-safe title/meta/sections/steps/faq/citations
• Every public route is unique and follows /use-cases/[slug]

Common Mistakes To Avoid

Do not:

• Change field names casually
• Mix multiple route strategies in one batch
• Use duplicate slugs
• Leave empty arrays for sections, faq, or steps
• Put plain text into sections.content if it should be HTML
• Add fake citations or unverifiable claims
• Assume urlPrefix changes the route today

Current Route Rule

Right now, all user case records are published under:

/use-cases/[slug]

Even if the JSON contains:

"urlPrefix": "industry"

the public page still renders at:

/use-cases/the-slug

If engineering later expands route families like /industry/[slug] or /templates/[slug], this document should be updated.

When To Ask Engineering For Help

Ask engineering before publishing if:

• You want a new section type that does not fit the current template
• You need a different route family
• You want custom schema markup
• You want per-page design changes
• The admin preview shows validation errors you do not understand

Quick Template

Use this starter object when drafting a new page:

{
  "client": "skillboss",
  "clientName": "SkillBoss",
  "domain": "cases.skillboss.co",
  "slug": "replace-this-slug",
  "title": "Replace this title",
  "meta": "Replace this meta description",
  "category": "Replace this category",
  "before": "Describe the painful current state.",
  "after": "Describe the improved future state.",
  "sections": [
    {
      "heading": "Why this problem matters",
      "content": "<p>Write section content here.</p>"
    }
  ],
  "steps": [
    {
      "name": "Step 1",
      "text": "Explain the first implementation step."
    }
  ],
  "ctaText": "Replace CTA text",
  "ctaUrl": "https://www.skillboss.co",
  "faq": [
    {
      "q": "Add a real question here?",
      "a": "Add the answer here."
    }
  ],
  "related": [
    {
      "slug": "another-existing-slug",
      "title": "Related page title"
    }
  ],
  "heroImage": "https://assets.skillboss.co/example-image.webp",
  "heroAlt": "Describe the hero image",
  "authority_citations": [
    {
      "source": "Trusted source",
      "claim": "A specific claim",
      "context": "Why this matters to the page"
    }
  ],
  "urlPrefix": "use-cases"
}

This is the safest way for non-engineers to add new records without breaking the template.