Structured data

Skill BartWaardenburg/isagentready-skills/structured-data

Agent skills for fixing AI agent readiness issues — robots.txt, structured data, semantic HTML, agent protocols, and security headers

Install

npx -y skills add BartWaardenburg/isagentready-skills --skill structured-data

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Fixes structured data issues — adds and validates JSON-LD markup with Schema.org types including Organization, WebSite, Product, Article, FAQPage, BreadcrumbList, entity linking, and author attribution so AI search engines can understand and cite website content. Use when asked to "add JSON-LD", "fix structured data", "add schema markup", "improve structured data score", "add Organization schema", "add BreadcrumbList", "fix Schema.org", "add product markup", "add FAQ schema", "add author markup", or any JSON-LD or Schema.org task.

SKILL.md

19.2 KB, as published. Nobody here has run it

Structured Data

Fixes Category 2 (AI Search Signals, 20% weight) issues from IsAgentReady.com. This category measures how well a website communicates its content to AI search engines through machine-readable structured data.

When to Use

User asks to add or fix JSON-LD / structured data / schema markup
IsAgentReady scan shows low Category 2 (AI Search Signals) score
Specific checkpoint failures: 2.1 through 2.8
User wants Organization, WebSite, Product, Article, FAQ, BreadcrumbList, or author markup
User asks to improve visibility in AI search (Perplexity, ChatGPT, AI Overviews)

When NOT to Use

Microdata or RDFa issues (this skill covers JSON-LD only)
OpenGraph or Twitter Card meta tags (those are social sharing, not structured data)
robots.txt, sitemap, or AI crawler issues (use ai-content-discovery skill)
Semantic HTML or heading hierarchy (use content-semantics skill)
Security headers or HTTPS issues (use security-trust skill)

How AI Search Signals Scoring Works

ID	Checkpoint	Points	Pass Criteria
2.1	JSON-LD present	20	`<script type="application/ld+json">` with schema.org @context
2.2	Organization / WebSite schema	15	@type Organization or WebSite with `name` + `url`
2.3	High-value schema types	20	Content-appropriate type with required properties
2.4	Entity linking (@id)	10	Entities with @id + cross-references between them
2.5	BreadcrumbList markup	10	Valid BreadcrumbList with position, name, item per element
2.6	Schema validation	10	No duplicate @type, no missing/empty required fields
2.7	FAQPage schema	10	FAQPage JSON-LD with valid Question + acceptedAnswer items
2.8	Author attribution	10	JSON-LD author with Person/Organization, meta author, or rel

Total: 105 points. Partial credit available for 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8.

Checkpoint 2.1: JSON-LD Present (20 pts)

What the scanner checks

Looks for <script type="application/ld+json"> blocks where the parsed JSON contains @context with schema.org.

Why it matters

JSON-LD is the preferred format for structured data by Google and AI search engines. It tells AI systems exactly what your page is about using a standardized vocabulary. Without it, AI systems must guess your content's meaning from unstructured HTML.

Fix workflow

Identify your page type. Determine what your page represents: a company homepage (Organization), a product page (Product), a blog post (Article), etc.
Add a JSON-LD block in the <head> (preferred) or before </body>:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png"
}
</script>

Validate the JSON is well-formed. Common mistakes: trailing commas, unescaped quotes, missing closing braces.
Verify with Google Rich Results Test or Schema.org Validator.

References

Checkpoint 2.2: Organization / WebSite Schema (15 pts)

What the scanner checks

JSON-LD with @type of Organization or WebSite. Required properties: name, url. Bonus properties: logo, sameAs, contactPoint.

Scoring

Full (15 pts): Organization or WebSite with name + url
Partial (7 pts): Type found but missing name or url
Fail (0 pts): Neither type found

Why it matters

Organization and WebSite schemas establish your brand identity in the knowledge graph. AI systems use these to attribute content, display rich results, and build entity relationships.

Fix workflow

Add Organization schema (recommended for all sites):

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "sameAs": [
    "https://twitter.com/yourcompany",
    "https://linkedin.com/company/yourcompany",
    "https://github.com/yourcompany"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "email": "[email protected]",
    "contactType": "customer service"
  }
}
</script>

Add WebSite schema (for sites with search functionality):

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Your Site Name",
  "url": "https://example.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://example.com/search?q={search_term_string}",
    "query-input": "required name=search_term_string"
  }
}
</script>

Ensure name and url are present — these are required for full credit. Empty strings don't count.

References

Checkpoint 2.3: High-Value Schema Types (20 pts)

What the scanner checks

Looks for any of 17 content-specific schema types with their required properties.

Scoring

Full (20 pts): At least one high-value type with all required properties
Partial (10 pts): Type found but missing required properties
Fail (0 pts): No high-value types found

Why it matters

Certain schema types trigger rich results in Google and are used by AI search engines like Perplexity and ChatGPT to generate citations and structured answers. The right type depends on your content.

Fix workflow

Choose the right type for your content:

Content Type	Schema Type	Required Properties
Blog/news	Article	`headline`
Products	Product	`name`
SaaS/tools	SoftwareApplication	`name`
FAQ pages	FAQPage	`mainEntity`
Local businesses	LocalBusiness	`name`, `address`
Services	Service	`name`
Events	Event	`name`, `startDate`
How-to guides	HowTo	`name`, `step`
Courses	Course	`name`, `description`
Job listings	JobPosting	`title`, `description`, `datePosted`, `hiringOrganization`
Videos	VideoObject	`name`
Recipes	Recipe	`name`
Q&A pages	QAPage	`mainEntity`

Add the JSON-LD for your content type. See references/schema-types.md for complete templates.
Include all required properties — partial credit (10 pts) is given if the type is present but missing required fields.

References

Google Search Gallery
Schema.org Getting Started
Full templates: references/schema-types.md

Checkpoint 2.4: Entity Linking via @id (10 pts)

What the scanner checks

JSON-LD entities with @id properties, and cross-references between entities using those @id values.

Scoring

Full (10 pts): Entities with @id + at least one cross-reference
Partial (7 pts): Entities with @id but no cross-references
Fail (0 pts): No entities use @id
Skip (0/0): No JSON-LD present at all

Why it matters

Entity linking via @id creates a connected graph of your content. AI systems can follow these references to build deeper understanding of relationships between your pages, organization, and content.

Fix workflow

Add @id to each entity using the URL#fragment pattern:

{
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "Your Company",
  "url": "https://example.com"
}

Cross-reference entities using @id:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Your Company",
      "url": "https://example.com"
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "name": "Your Site",
      "url": "https://example.com",
      "publisher": { "@id": "https://example.com/#organization" }
    },
    {
      "@type": "Article",
      "@id": "https://example.com/blog/post/#article",
      "headline": "My Article",
      "author": { "@id": "https://example.com/#organization" },
      "isPartOf": { "@id": "https://example.com/#website" }
    }
  ]
}
</script>

Use @graph to bundle multiple entities in a single JSON-LD block. See references/json-ld-patterns.md for detailed patterns.

References

Checkpoint 2.5: BreadcrumbList Markup (10 pts)

What the scanner checks

@type: BreadcrumbList with itemListElement array. Each element must have position, name, and item (URL).

Scoring

Full (10 pts): Valid BreadcrumbList with all items having position + name + item
Partial (5 pts): BreadcrumbList found but items missing required properties
Fail (0 pts): No BreadcrumbList found
Skip (0/0): Homepage scan (breadcrumbs not applicable)

Why it matters

BreadcrumbList helps AI agents understand your site hierarchy and navigation structure. It enables rich breadcrumb display in search results and improves content categorization.

Fix workflow

Add BreadcrumbList for every non-homepage page:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://example.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Products",
      "item": "https://example.com/products"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Widget Pro",
      "item": "https://example.com/products/widget-pro"
    }
  ]
}
</script>

Ensure each item has all three properties:
- position: Integer starting at 1
- name: Human-readable label
- item: Full URL of that breadcrumb level
Match your visible breadcrumbs — the JSON-LD should reflect the actual breadcrumb navigation shown on the page.

References

Checkpoint 2.6: Schema Validation (10 pts)

What the scanner checks

Validates structural correctness: no duplicate @type in same block, required properties present for each type, no empty required fields.

Scoring

Full (10 pts): No validation issues
Partial (5 pts): 1-2 issues
Fail (0 pts): 3+ issues
Skip (0/0): No JSON-LD present

Why it matters

Invalid structured data is ignored by search engines and AI systems. Validation errors mean your markup effort provides zero benefit — properly structured data is essential.

Fix workflow

Check for duplicate @type in the same JSON-LD block:

// WRONG — two Organization entities in same @graph
{
  "@graph": [
    { "@type": "Organization", "name": "Company A" },
    { "@type": "Organization", "name": "Company B" }
  ]
}

Ensure required properties exist for each type. See the required properties table in checkpoint 2.3.
Remove empty required fields:

// WRONG — empty name
{ "@type": "Organization", "name": "", "url": "https://example.com" }

// CORRECT
{ "@type": "Organization", "name": "Your Company", "url": "https://example.com" }

Validate with external tools:
- Google Rich Results Test
- Schema.org Validator

See references/gotchas.md for common validation pitfalls.

References

Checkpoint 2.7: FAQPage Schema (10 pts)

What the scanner checks

JSON-LD with @type: FAQPage and mainEntity array containing Question items with valid acceptedAnswer.

Scoring

Full (10 pts): Valid Question items with acceptedAnswer of type Answer
Partial (5 pts): FAQPage present but missing/invalid Question or acceptedAnswer structure
Fail (0 pts): No FAQPage schema

Why it matters

Sites with FAQPage schema are 8x more likely to be cited by ChatGPT. FAQ structure maps directly to question-answer patterns AI models use.

Fix workflow

Add FAQPage JSON-LD — each Question needs name and acceptedAnswer with @type: Answer:

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is AI agent readiness?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "AI agent readiness measures how well your website can be discovered and understood by AI systems."
      }
    }
  ]
}

Common mistakes (cause partial 5 pts): Question without acceptedAnswer, acceptedAnswer missing @type: Answer, empty mainEntity array.
Validate with Google Rich Results Test. Full template: references/schema-types.md.

Checkpoint 2.8: Author Attribution (10 pts)

What the scanner checks

Author signals in JSON-LD, meta tags, or link elements.

Scoring

Full (10 pts): JSON-LD author with @type Person/Organization and name
Partial (7 pts): <meta name="author" content="...">
Partial (5 pts): <link rel="author"> or <a rel="author">
Fail (0 pts): No author signals

Why it matters

96% of Google AI Overview sources show E-E-A-T signals. Claude and ChatGPT prefer content with clear author attribution.

Fix workflow

Add JSON-LD author (best — 10 pts):

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Your Article Title",
  "author": {
    "@type": "Person",
    "name": "Jane Smith",
    "url": "https://example.com/authors/jane-smith"
  }
}

For company content, use "@type": "Organization" instead of "Person".

Meta author tag as fallback (7 pts):

<meta name="author" content="Jane Smith">

Rel author link as minimum (5 pts):

<link rel="author" href="https://example.com/authors/jane-smith">

Verify:

curl -s https://example.com/ | grep -iE '"author"|name="author"|rel="author"'

Quick Wins: Maximum Score Path

For a site with no structured data, add these in order for the fastest score improvement:

Organization JSON-LD (solves 2.1 + 2.2 = 35 pts)
Content-appropriate type like Article or Product (solves 2.3 = 20 pts)
Wrap in @graph with @id and cross-references (solves 2.4 = 10 pts)
Add BreadcrumbList on non-homepage pages (solves 2.5 = 10 pts)
Validate — fix any duplicate types or empty fields (solves 2.6 = 10 pts)
Add FAQPage schema for pages with Q&A content (solves 2.7 = 10 pts)
Add author attribution in JSON-LD (solves 2.8 = 10 pts)

Combined @graph example covering 2.1-2.4 + 2.6 + 2.8 — see references/json-ld-patterns.md for the full template with Organization, WebSite, content type, @id cross-references, and author.

Key Gotchas

Missing @context — JSON without "@context": "https://schema.org" is not recognized
Trailing commas in JSON — JSON-LD must be valid JSON; trailing commas break parsing
Duplicate @type in same @graph — Two Organization entities trigger validation warnings
Empty required fields — "name": "" counts as missing
Wrong @type casing — "organization" or "ORGANIZATION" won't match; use PascalCase "Organization"
FAQPage with empty mainEntity — "mainEntity": [] fails; include at least one Question with acceptedAnswer
Author without @type — "author": "Jane Smith" (string) fails; use "author": { "@type": "Person", "name": "Jane Smith" }

See references/gotchas.md for detailed correct vs incorrect examples of each.

References

references/schema-types.md — Complete JSON-LD templates for all 19 schema types
references/json-ld-patterns.md — @graph, entity linking, combining types, SearchAction
references/gotchas.md — Common pitfalls with correct vs incorrect examples

Instructions

Identify failing checkpoints from the IsAgentReady.com scan results
Follow the fix workflow for each failing checkpoint above
Apply the code examples — adapt organization name, URLs, and content types to the user's site
Validate with Google Rich Results Test or Schema.org Validator
Re-scan at isagentready.com to confirm improvements

If $ARGUMENTS is provided, interpret it as the URL to fix or the specific checkpoint to address.

One thing to look at

What its author says it does

SKILL.md

Structured Data

When to Use

When NOT to Use

How AI Search Signals Scoring Works

Checkpoint 2.1: JSON-LD Present (20 pts)

What the scanner checks

Why it matters

Fix workflow

References

Checkpoint 2.2: Organization / WebSite Schema (15 pts)

What the scanner checks

Scoring

Why it matters

Fix workflow

References

Checkpoint 2.3: High-Value Schema Types (20 pts)

What the scanner checks

Scoring

Why it matters

Fix workflow

References

Checkpoint 2.4: Entity Linking via @id (10 pts)

What the scanner checks

Scoring

Why it matters

Fix workflow

References

Checkpoint 2.5: BreadcrumbList Markup (10 pts)

What the scanner checks

Scoring

Why it matters

Fix workflow

References

Checkpoint 2.6: Schema Validation (10 pts)

What the scanner checks

Scoring

Why it matters

Fix workflow

References

Checkpoint 2.7: FAQPage Schema (10 pts)

What the scanner checks

Scoring

Why it matters

Fix workflow

Checkpoint 2.8: Author Attribution (10 pts)

What the scanner checks

Scoring

Why it matters

Fix workflow

Quick Wins: Maximum Score Path

Key Gotchas

References

Instructions

Keep looking