Skip to content
Get packs

Guide · Agent skill

How to use the FAQ Schema Markup agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The faq skill is a set of instructions that teaches an AI agent to add FAQPage structured data, a hidden JSON-LD block describing questions and answers, to web pages that already show FAQ content. It also tells the agent how to check existing pages for correct markup. This guide covers what the skill does, how to install it, how to trigger it, and the limits you should respect.

FAQ Schema Markupthedaviddias/Front-End-Checklist · MIT

Quick start

  1. 1Download the skill. Download the ZIP from the faq skill page and unzip it.
  2. 2Place the folder. Move the folder to ~/.claude/skills/ for personal use or to .claude/skills/ inside a project.
  3. 3Or upload it. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
  4. 4Ask with a plain request. Describe the page and the FAQ content you want marked up or checked.
  5. 5Review the output. Confirm every schema question has a matching visible answer on the page.
  6. 6Validate. Test the page with Google's Rich Results Test at https://search.google.com/test/rich-results.

What is an agent skill and what does the faq skill do?

An agent skill is a folder of instructions that an AI agent (such as Claude) loads when a task matches the skill's description. The faq skill is defined in a file called SKILL.md and covers adding FAQPage schema markup to pages.

When it applies, the agent can add a JSON-LD script with a mainEntity list of Question objects, where each question has a name and an acceptedAnswer of type Answer with a text property. It can also audit existing pages: it looks for the FAQPage block, checks that the structure is valid, and confirms that the schema matches the questions and answers visible on the page.

  • Adds FAQPage JSON-LD to landing pages or blog posts that show FAQ content
  • Generates FAQPage JSON-LD from existing question-and-answer text
  • Validates existing FAQ structured data for syntax and for matching visible content

Install the faq skill

Download the ZIP from the skill's page on our site and unzip it. The skill is a folder containing SKILL.md and references/rule.md.

For personal use, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What the skill needs

The skill does not list any requirements. It does not run scripts and does not use the network. Its validation step points you to Google's Rich Results Test at https://search.google.com/test/rich-results, which you use in your own browser.

  • Requires: nothing listed
  • Runs scripts: no
  • Uses network: no

How to trigger the skill with natural requests

You do not need a special command. Describe the task in plain language, and the agent will use the skill when your request matches its description. Be specific about the page and the content you have.

  • Add FAQ schema to this landing page, the FAQ section is already in the HTML
  • Generate FAQPage JSON-LD from these five questions and answers
  • Check whether the structured data on this blog post matches the FAQ section
  • Validate the FAQPage markup in this file for syntax errors

Example: adding FAQPage markup to a page

The skill's example pairs a question with its answer in a JSON-LD block. The answer text should match what visitors see on the page.

Every question in the schema must have a corresponding visible answer on the page. Hidden or mismatched markup is ignored by Google and can trigger a manual action.

  • Confirm the page visibly shows the questions and answers
  • Add the JSON-LD script to the page head or body
  • Run the page through Google's Rich Results Test
{"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "How do I reset my password?", "acceptedAnswer": {"@type": "Answer", "text": "Click 'Forgot password' on the login page and enter your email address. You will receive a reset link within 5 minutes."}}]}

Safety notes and limits

Only use FAQPage markup on pages that show FAQ-style question-and-answer content to users. The skill warns that markup for content not visible on the page is ignored and may trigger a manual action from Google.

The skill describes possible benefits, such as expandable Q&A in results and possibly higher click-through. It cannot promise rich results or better rankings.

  • Do not add markup for questions that are not shown on the page
  • Check the agent's output before deploying, since it is a code change to your site
  • Rich results are not guaranteed

Tips for better results

Give the agent the exact FAQ text from the page so the markup matches it word for word. When auditing, ask the agent to cross-reference each schema question against the visible questions in the HTML.

  • Keep answers in the markup identical to the visible answers
  • Use the audit request to find pages where markup and content have drifted apart
  • Re-validate after each change with the Rich Results Test

What people use it for

  • Adding FAQPage JSON-LD to a product landing page that already has an FAQ section
  • Generating structured data for a blog post's question-and-answer list
  • Auditing existing FAQ markup across pages for missing acceptedAnswer or mismatched text
  • Preparing pages for Google rich results before a launch

Frequently asked questions

How do I install the faq agent skill?

Download the ZIP from the skill's page and unzip it. Put the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder, or upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Is the faq skill free?

The skill is published under the MIT licence. The source does not mention pricing for it, so check the directory page for any terms.

What does the faq skill need to run?

The skill lists no requirements. It does not run scripts and does not use the network.

Will adding FAQPage schema guarantee rich results?

No. The skill says valid FAQPage markup can generate rich results and may improve click-through, but it cannot guarantee either. Google decides whether to show them.

Can I add FAQ schema to a page that has no visible FAQ?

No. The skill says to use FAQPage markup only when the page shows FAQ-style Q&A content to users. Hidden or mismatched markup is ignored and can trigger a manual action from Google.

How do I check if my FAQ schema is valid?

Ask the agent to audit the page, then test the URL or code with Google's Rich Results Test at https://search.google.com/test/rich-results.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use the faq skill if you are a front-end developer or SEO-minded marketer adding or auditing FAQ sections on landing pages or blog posts. Skip it for pages without visible FAQ content, or if you need guaranteed search results, since the skill cannot promise them.

Download the skill