# Add Faqs

> Add a FAQs section to the end of a ProstDev blog post for AEO. Use when the user wants to add or update frequently-asked questions / Q&A on a post (the "add FAQs", "FAQ section", "AEO Q&A" ask). Writes an optional `faqs` frontmatter array — answers GROUNDED in the post body, never fabricated — that renders a `## FAQs` section, mirrors into the `.md` endpoint, and emits FAQPage JSON-LD. Verifies with a build.

- Skill: `prostdev/add-faqs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add prostdev/add-faqs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prostdev/add-faqs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ProstDev (https://skillmd.com/u/prostdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/prostdev/add-faqs

---


# Add a FAQs section to a ProstDev post

FAQs are an OPTIONAL `faqs` frontmatter array on a post's `.mdx`, rendered as a `## FAQs`
disclosure section (by `Faqs.astro`), mirrored in the `.md`/llms endpoint, AND emitted as
**`FAQPage` JSON-LD** — a machine-readable answer-engine signal (for ChatGPT / Perplexity /
Copilot-style crawlers + the `.md`/`llms.txt` surface). NOTE: Google fully deprecated the FAQ rich
result in May 2026, and its AI experiences (AI Overviews / AI Mode / Gemini) read the *visible page
text* from the regular index, NOT the JSON-LD — so for Google/Gemini the win is the rendered `##
FAQs` section, and the JSON-LD is the bonus for non-Google engines. Blog posts are the site's AEO
surface, so explicit, well-phrased Q&A in the visible text is a direct AEO win. Same plumbing shape as reader notes
(optional array → component OUTSIDE `.prose` → `.md` block), but EDITORIAL, not preserved Wix
content. Full detail → `.claude/docs/content-authoring.md` (the FAQs convention). See [[add-post]]
for the full post schema and [[add-comment]] for the sibling per-post editor (reader notes).

## Steps

1. **Identify the post + READ IT.** `src/content/blog/<slug>.mdx`. You must read the body — every
   answer has to be grounded in what the post ACTUALLY says (next step). Append to an existing
   `faqs:` block or create one after `tags:` (placement in frontmatter doesn't matter; convention is
   after `readerNotes`/`tags`, before `draft`).

2. **HARD RULE — answers are GROUNDED IN THE POST BODY, never fabricated.** Ask the question a real
   reader would ask about this post, and answer it from what the post already states. Do NOT add
   outside facts, version numbers, or claims the post doesn't make. If the post doesn't answer a
   question you'd like to include, drop the question — don't invent an answer. **3–6 Q&A is plenty.**
   Phrase questions naturally ("How do I…", "What's the difference between…", "Why does…") — that's
   what AEO matches against.

3. **Add the entries** (schema in `src/content.config.ts`):

   ```yaml
   faqs:
     - question: "What is the difference between On-Error Propagate and On-Error Continue?"
       answer: "On-Error Propagate re-throws the error to the parent flow; On-Error Continue handles it and lets the flow finish. The `try` scope examples above show each behavior."
     - question: "Where can I read the official reference?"
       answer: "See the MuleSoft docs at https://docs.mulesoft.com for the full error-handling reference."
   ```

   - Both `question` and `answer` are required strings.
   - **`answer` is INLINE PROSE ONLY** — it may contain `` `code` `` chips and bare `https://…` URLs
     (autolinked by the component, new tab + external icon, same as reader notes), but **NO block
     elements**: no bulleted lists, no fenced code blocks, no headings. A clean single paragraph
     keeps the `FAQPage` JSON-LD `acceptedAnswer.text` valid. Need to enumerate? Write it as a
     sentence ("first X, then Y, finally Z"), not a list.

4. **YAML safety.** `question:`/`answer:` are quoted YAML strings, so quote the value (`"…"`) and
   escape an inner `"` as `\"`. A literal `:` mid-sentence is fine inside quotes. A raw `<` is fine
   INSIDE a YAML string, but write XML/config tag names in backticks (`` `<provider>` ``) so they
   render as a code chip rather than plain text.
   - **Escape only the INNER quotes, never the OUTER pair.** `answer: "… \"STRICT\" …"` is correct;
     `answer: \"…\"` (outer pair escaped) is the trap — YAML reads it as a PLAIN scalar starting with
     a literal `\`, the build PASSES, and the page/JSON-LD render visible `\"…\"` backslashes. Grep
     `grep -rn ': \\"' src/content/blog/*.mdx` to catch it (an outer escape always follows `: `).

5. **Verify with a build.** `npm run build` from the repo root — a YAML/schema error names the file.
   The build does NOT catch a render-quality defect that's still valid YAML (e.g. the outer-escape
   trap above, or a stray block element) — so after a BATCH pass also grep the source: outer escapes
   (`: \\"`), and confirm every question ends in `?`. Then optionally `npm run preview` and open
   `/post/<slug>`:
   - the `## FAQs` disclosures render after the body / reader notes, before the tags (both themes,
     keyboard-operable, focus ring visible);
   - view source → a `<script type="application/ld+json">` with `"@type":"FAQPage"` and a
     `"@type":"Question"` per pair;
   - `curl -s localhost:4321/post/<slug>.md` → the trailing `## FAQs` block (`### question` + answer).

## Notes

- The EDIT here is to a SITE file (`src/content/blog/<slug>.mdx`) — a one-commit change in the
  PUBLIC repo, and only when the user explicitly asks. (Editing THIS skill is the internal
  two-commit submodule case.)
- A post with no `faqs` renders nothing — the section, JSON-LD, and `.md` block are all guarded on
  `faqs.length`, so adding the field to one post never touches the others.
- Infra shipped June 2026 with ZERO posts seeded — FAQs are added per-post on demand via this skill,
  not batch-generated.