Customer story setup

Single source of truth: maintain this skill under .agents/skills/customer-story-setup/ only. Claude and Cursor load projected copies under .claude/skills/customer-story-setup and .cursor/skills/customer-story-setup.

Customer story setup (MD -> MDX)

Turns a plain Markdown draft into content/customers/<slug>.mdx in the same pattern as content/customers/canva.mdx and cresta.mdx.

Before writing any file: collect missing input

Do not guess. If any item below is missing from the user's draft or message, ask explicitly and wait for answers (or confirm defaults).

Content & publishing

Topic	Ask
Company name	Legal/marketing name for copy and quotes
Company website	Public URL for the [Company](https://...) link in About <Company>
Slug	Filename: <slug>.mdx (lowercase, hyphens), e.g. cresta -> cresta.mdx
Page title	H1 string for BlogHeader + YAML title (often "How <Company> ... with Langfuse")
Short description	YAML description + BlogHeader description (SEO/social; 1-2 sentences)
Publish date	YAML date + BlogHeader date (e.g. March 26, 2026)
OG image	Optional ogImage: path; if unset, leave empty like other stories

Authors (BlogHeader authors={["..."]})

Topic	Ask
Byline author(s)	Who should appear under the title (keys from data/authors.json)
External / guest speaker	If not in authors.json: collect name, title, optional socials, and headshot path under public/images/people/ or public/images/customers/<slug>/, then add an entry to data/authors.json (see existing entries). Every authors key must resolve in authors.json.

Branding & Users index card

Topic	Ask
Logos	Paths for customerLogo and customerLogoDark (light + dark mode), usually under public/images/customers/<slug>/
Pull quote	customerQuote (short, for grid card)
Quote attribution	quoteAuthor, quoteRole, quoteCompany
Speaker headshot (optional)	quoteAuthorImage for card/SEO if you use the same as Canva
Show on /users	showInCustomerIndex: true | false

Images (screenshots & diagrams)

Produce a numbered checklist for the user (and keep it in the PR description if useful):

1. Folder: public/images/customers/<slug>/
2. For each asset: filename, purpose, where it appears (section + suggested alt text)
3. Remind: customer posts use <Frame fullWidth> around markdown images, e.g. ![Alt](mdc:/images/customers/<slug>/file.png) per site conventions
4. Size each image by aspect ratio (run sips -g pixelWidth -g pixelHeight <file> to get dimensions):
   • Portrait / square (ratio <= 1:1) -> <div className="flex justify-center"><Frame fullWidth className="w-1/2">...</Frame></div>
   • Landscape (~1.5:1) -> <div className="flex justify-center"><Frame fullWidth className="w-2/3">...</Frame></div>
   • Panoramic (> 2:1) -> <Frame fullWidth className="w-full">...</Frame> (no centering wrapper needed)

If the draft says "screenshot here" without files, list placeholders in MDX with consistent paths so the user can drop files in later.

Docs links (optional but recommended)

Ask whether to add sparse internal links. Default policy: only link major product concepts (match what we used on Cresta):

• Observability overview
• Prompt management and/or Playground
• Scores
• Self-hosting
• OpenTelemetry
• Experiments
• LLM-as-a-judge
• Prompt version control

Do not pepper every noun with links. Use paths from llms-docs.txt / available-internal-links rule so links resolve.

---

MDX structure to produce

1. YAML frontmatter at top: title, date, description, ogImage, tag: customer-story, author (display string if needed), customerLogo, customerLogoDark, optional quote fields, showInCustomerIndex.
2. Imports: BlogHeader, CustomerQuote (if quote), ImpactChart (if impact section), CustomerStoryCTA; use Frame for images (global in MDX).
3. BlogHeader: title, description, customerLogo, authors, date; optional image for hero.
4. Body headings: One conceptual H1 only (from BlogHeader). Body uses ## and ###; do not skip levels.
5. Quote block: <CustomerQuote quote="..." name="..." role="..." company="..." />
   • align role / company with frontmatter so the byline reads "Name, Role at Company"
   • avoid duplicating company name in role
6. Images: size by aspect ratio (see checklist item 4 under Images above)
   • portrait/square -> w-1/2 centered
   • landscape -> w-2/3 centered
   • panoramic -> w-full
7. Closing: <ImpactChart items={[{ area, impact }, ...]} /> (optional) then <CustomerStoryCTA />.

Reference implementations: content/customers/canva.mdx, content/customers/cresta.mdx.

---

Repo wiring (after MDX exists)

1. content/customers/meta.json

   • Add "<slug>" to the pages array (with "index" first).
   • Order matters for layout: the Users grid and homepage carousel are sorted by sortCustomerStoriesByMetaOrder in lib/sortCustomerStoriesByMeta.ts, which reads this list. Place the slug where the card should appear (e.g. last in the list = bottom-right in a 2-column grid).

2. Authors

   • If new author: add to data/authors.json (key must match BlogHeader authors).

3. Assets

   • Logos and story images under public/images/customers/<slug>/.

---

Checklist before finishing

• All required fields collected from user (or documented as TBD)
• authors keys exist in data/authors.json
• meta.json includes slug in desired order
• Image checklist given to user with folder path
• Company website link in About section
• Docs links only where agreed; no broken internal URLs
• Replace all em dashes with regular hyphens (-) - the linter will do this anyway; better to do it upfront
• Follow AGENTS.md / documentation-pages.mdc: one H1 via BlogHeader, American English, accessible alt text

---

Quick YAML skeleton (adapt fields)

---
title: "..."
date: ...
description: ...
ogImage:
tag: customer-story
author: ...
customerLogo: "/images/customers/<slug>/...-light.png"
customerLogoDark: "/images/customers/<slug>/...-dark.png"
customerQuote: "..."
quoteAuthor: "..."
quoteRole: "..."
quoteCompany: "..."
showInCustomerIndex: true
---