schema-markup

Overview of schema-markup skill

What the schema-markup skill does

The schema-markup skill helps you add, fix, or upgrade structured data on real pages using valid schema.org patterns, with a strong bias toward JSON-LD and Google-visible rich result opportunities. It is most useful when you already know the page you want to mark up, but want faster decisions on the right schema type, required properties, and a code example that is ready to implement.

Who should install schema-markup

This schema-markup skill is a good fit for SEO teams, content marketers, web developers, and site owners who need to ship structured data without guessing through docs. It is especially useful for:

• marketing sites and SaaS homepages
• blog and article templates
• product, software, FAQ, event, and local business pages
• teams cleaning up inaccurate or incomplete markup

The real job-to-be-done

Most users are not looking for a theory lesson on structured data. They need to answer practical questions fast:

• Which schema type fits this page?
• Can multiple schema types be combined?
• What properties are worth adding now?
• What is safe to implement without overclaiming?
• What JSON-LD should go into the page template today?

The skill is designed around those decisions, not just a list of schema types.

What makes this schema-markup skill different

The strongest differentiator is that it guides toward accurate, page-matched markup instead of “add every schema possible.” The repository also includes a useful references/schema-examples.md file with concrete examples for common types like Organization, WebSite, Article, Product, SoftwareApplication, FAQPage, HowTo, BreadcrumbList, LocalBusiness, and Event. That makes the skill more actionable than a generic prompt.

Biggest limits to know before installing

This is not a crawler, validator, or live-page scanner. The schema-markup skill depends on the page facts you provide. If your inputs are vague, the output can look polished but still be wrong for eligibility or implementation. It also focuses on markup generation and selection, not broader technical SEO diagnosis.

How to Use schema-markup skill

Install schema-markup skill

Install from the repo with:

npx skills add https://github.com/coreyhaines31/marketingskills --skill schema-markup

If you are evaluating before installation, review:

• skills/schema-markup/SKILL.md
• skills/schema-markup/references/schema-examples.md
• skills/schema-markup/evals/evals.json

These three files tell you most of what matters: trigger conditions, output expectations, and example patterns.

Read these files first

Start in this order:

1. SKILL.md for workflow and decision rules
2. references/schema-examples.md for copyable JSON-LD patterns
3. evals/evals.json to see what “good output” looks like in practice

The evals are particularly helpful because they reveal the intended behavior: check context first, choose relevant schema types, use @graph when needed, provide complete JSON-LD, and recommend validation.

Best input format for schema-markup usage

The schema-markup skill works best when you give it page-level facts, not just “add schema.” Include:

• page URL or page type
• page purpose
• visible on-page entities
• business type
• target rich result, if any
• any current schema or errors
• CMS or framework
• fields you can actually populate

A weak request:

• “Add schema markup for SEO.”

A strong request:

• “Create JSON-LD for our SaaS homepage. We are a project management platform. Visible elements include company name, logo, product overview, customer logos, pricing link, and site search. We want Organization, WebSite, and the most appropriate product-related type. We deploy in Next.js and can inject one script in the layout.”

Turn a rough goal into a usable prompt

A good schema-markup prompt should ask for four outputs:

1. recommended schema type(s)
2. reasoning for each choice
3. complete JSON-LD
4. validation and implementation notes

Example prompt structure:

• “Use the schema-markup skill.”
• “First determine the page type and rich result eligibility.”
• “Then recommend the minimal correct schema set.”
• “Generate production-ready JSON-LD.”
• “Flag any claims that are unsupported by visible content.”
• “Tell me where to place it in our template.”

That framing gets more reliable output than simply asking for sample code.

Page types this skill handles well

Based on the repository examples and evals, the schema-markup skill is strongest for:

• homepage Organization and WebSite
• blog/article markup
• Product and SoftwareApplication
• FAQPage
• HowTo
• BreadcrumbList
• LocalBusiness
• Event
• mixed-page implementations using @graph

If your page clearly maps to one of these, adoption is easy.

When to use @graph in schema-markup

Use @graph when one page legitimately contains multiple entities or page roles, such as:

• homepage with Organization + WebSite
• SaaS homepage with Organization + WebSite + SoftwareApplication
• article page with Article + BreadcrumbList

This matters because many teams either split markup awkwardly across scripts or overstuff one type with unrelated properties. The skill’s examples and eval expectations point toward cleaner multi-type modeling.

Practical workflow for schema-markup for SEO Content

A practical schema-markup usage flow is:

1. identify the page’s primary purpose
2. confirm which content is actually visible
3. select the smallest valid schema set
4. generate JSON-LD
5. implement in template or page component
6. validate in Google Rich Results Test and Schema.org Validator
7. compare markup to live content after publishing

For SEO content teams, this prevents the common mistake of adding rich-result-oriented markup that does not match the rendered page.

Implementation tips that change output quality

A few inputs materially improve the result:

• provide canonical URL, logo URL, and image URLs
• specify whether ratings, pricing, or FAQs are truly visible
• state if the page is transactional, editorial, navigational, or local
• mention framework constraints like Next.js, WordPress, or head-script injection
• tell the skill whether markup should be minimal or comprehensive

Without these details, the model may choose the right type but weak property coverage.

Validation steps after schema-markup install

After generating markup, validate with:

• Google Rich Results Test
• Schema.org Validator

Then manually verify:

• every marked-up field exists on the page
• URLs are absolute
• dates are in valid formats
• images are crawlable
• multiple entities are not duplicated inconsistently across templates

The repository repeatedly leans toward accuracy first, which is the right adoption mindset.

Common repository-backed patterns to borrow

The included examples file is worth using as a pattern library, especially for:

• Organization with sameAs and contactPoint
• WebSite with SearchAction
• complete FAQ question/answer nesting
• product-like and software-related entity setup
• a Next.js implementation example

That means the schema-markup guide is not just conceptual; it is usable as a starter kit.

schema-markup skill FAQ

Is schema-markup better than a normal AI prompt?

Usually yes, if your goal is implementation-ready markup. A normal prompt may produce syntactically valid JSON-LD but still pick the wrong type, omit important properties, or markup things that do not exist on the page. The schema-markup skill is more opinionated about page fit, accuracy, and multi-schema composition.

Is the schema-markup skill beginner-friendly?

Yes, if you can describe the page clearly. You do not need deep schema.org knowledge to get value. But beginners still need to provide factual page inputs. The skill is not magic; it cannot infer missing business details safely.

Can schema-markup help with existing broken markup?

Yes. This is one of the best use cases. Give it the current markup, the page type, and the actual visible content. Ask it to identify mismatches, remove unsupported properties, and rewrite the JSON-LD cleanly.

Does schema-markup guarantee rich results?

No. The schema-markup skill can improve eligibility and implementation quality, but Google decides whether to show rich results. Correct markup, page quality, content type, and search demand all matter.

When should I not use schema-markup?

Do not rely on this skill alone when you need:

• a full technical SEO audit
• live site crawling at scale
• ranking diagnosis
• JavaScript rendering analysis
• broad content strategy

It is best for page-level structured data decisions, not whole-site SEO troubleshooting.

Is schema-markup useful for SaaS and marketing sites?

Yes. The evals explicitly point toward homepage use cases such as Organization, WebSite, and SoftwareApplication-style modeling. This makes it more relevant for modern B2B and SaaS teams than schema guides that focus only on ecommerce.

How to Improve schema-markup skill

Give schema-markup the page facts it cannot infer

The fastest way to improve output is to provide:

• exact page purpose
• visible elements
• brand name and URLs
• author, publisher, date, price, rating, FAQ, or event data where relevant
• what you can and cannot legally or technically claim

This reduces false assumptions and improves property completeness.

Ask for a schema decision before asking for code

A better prompt sequence is:

1. “Decide the correct schema types.”
2. “Explain why each fits.”
3. “List missing data needed for a complete implementation.”
4. “Then generate final JSON-LD.”

This catches bad type selection early and makes the schema-markup skill much more reliable on mixed-purpose pages.

Avoid the biggest failure mode: overmarking

The most common schema mistake is adding markup for things that are not clearly present on the page. Examples:

• FAQPage for hidden or non-user-facing FAQs
• Review or rating data without visible evidence
• Product on generic brand pages with no true product detail
• HowTo on pages that are really blog posts

If you use schema-markup conservatively, results are usually better.

Improve multi-entity output with explicit relationships

When requesting multiple types, tell the skill how they relate:

• “This page is the company homepage”
• “The article belongs to this publisher”
• “The software application is the main product described here”
• “Breadcrumbs are rendered above the H1”

That helps the skill produce cleaner @graph output instead of disconnected entities.

Use the examples file as a quality benchmark

Before shipping output, compare it against references/schema-examples.md. Check whether your result includes the expected structural patterns for that type. This is one of the most practical ways to improve schema-markup usage without reading all of schema.org.

Iterate after first draft instead of accepting it raw

After the first output, ask follow-ups like:

• “Strip this to only required and high-value recommended properties.”
• “Rewrite for a blog post rather than a generic article.”
• “Convert this to a single @graph block.”
• “Adapt this for Next.js server-rendered injection.”
• “Audit this against the visible page content and remove unsupported fields.”

That second pass is often where the schema-markup skill becomes production-ready.

Pair schema-markup with validation and SERP reality checks

Even strong JSON-LD should be tested against:

• actual rendered page content
• validation tools
• whether the target rich result is realistic for that page type

The best schema-markup workflow is not “generate once and paste,” but “generate, validate, reconcile, publish.”