# GEO schema & structured data Human Guide ## What This Is For Schema.org structured data audit and generation optimized for AI discoverability — detect, validate, and generate JSON-LD markup It gives the agent a clearer input/output frame for search and SEO workflows: what context to ask for, what decisions to make, and what usable artifact to return. Use this as a human-readable version of the GEO schema & structured data agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions. ## When To Use This - Use this when you need a repeatable process for GEO schema & structured data. - Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt. - Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact. ## When Not To Use This - Do not use this when you only need a quick factual answer. - Do not use this when the work depends on private data you cannot share with the assistant. - Do not use this as a replacement for legal, compliance, financial, or medical review. ## What You Need Before Starting - The goal or business outcome you want. - The audience, customer segment, or market context. - Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance. - Constraints such as tone, length, channel, deadline, region, or approval requirements. - A clear definition of what a good final answer should look like. ## Step-By-Step Workflow 1. State the job clearly: "Use the GEO schema & structured data guide to help me with..." 2. Add context: audience, goal, offer, channel, source material, and constraints. 3. Ask the assistant to identify missing inputs before producing the final output. 4. Have the assistant follow the skill-specific guidance below. 5. Review the result against the final checklist and ask for revisions where needed. ## Skill-Specific Guidance - Fetch the target page HTML using `fetch_page.py` (see note below) - Detect all existing structured data (JSON-LD, Microdata, RDFa) - Validate detected schemas against Schema.org specifications - Identify missing recommended schemas based on business type - Generate ready-to-use JSON-LD code blocks - **Valid JSON**: Is the JSON-LD syntactically valid? Check for trailing commas, unquoted keys, malformed strings. - **Valid @type**: Does the `@type` match a recognized Schema.org type? Check against https://schema.org/docs/full.html. - **Required Properties**: Does the schema include all required properties for its type? (See per-type requirements below.) - **Recommended Properties**: Does the schema include recommended properties that increase AI discoverability? - **sameAs Links**: Does the schema include `sameAs` properties linking to other platform presences? - **URL Validity**: Do all URLs in the schema resolve (not 404)? - **Nesting**: Is the schema properly nested (e.g., author inside Article, address inside Organization)? ## Decision Points And Nuance The original skill emphasizes: Purpose, How to Use This Skill, Step 1: Detection, Scan for JSON-LD, Scan for Microdata, Scan for RDFa, Priority Order, Step 2: Validation, Step 3: Schema Types for GEO, Organization (CRITICAL — every business site). Use these questions to steer the work: - What is the intended audience or buyer? - What source material must be preserved? - What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion? - What examples represent the desired quality bar? - What should the assistant avoid? ## Common Mistakes - **IMPORTANT:** WebFetch converts HTML to markdown and strips `` content, which removes JSON-LD blocks. Use `fetch_page.py` instead: - **Required Properties**: Does the schema include all required properties for its type? (See per-type requirements below.) - Additional required properties: - Author (Person) required for GEO: - "query-input": "required name=search_term_string" - **Required:** `name`, `url` - | HowTo | Rich results deprecated Aug 2023 | Still useful for AI parsing, but do not promise rich results | - | VideoObject `contentUrl` | Changed behavior 2024 | Must point to actual video file, not page URL | ## Copy-And-Paste Prompt ```text Use the GEO schema & structured data human guide. My goal: [Describe the business outcome] Audience: [Describe who this is for] Context and source material: [Paste notes, examples, links, or existing copy] Constraints: [Tone, length, channel, timeline, must-include items, must-avoid items] Before producing the final output, ask me for any missing information that would materially improve the result. ``` ## Final Checklist - [ ] The output matches the original goal. - [ ] The audience and context are reflected in the answer. - [ ] Important constraints and source material were preserved. - [ ] The assistant made the relevant decisions explicit. - [ ] The final artifact is ready to use, review, or hand to the next person. ## Source This guide was generated from the zubair-trabzada/geo-seo-claude skill entry for `geo-schema`. ## Source Skill Notes These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic. # GEO Schema & Structured Data ## Purpose Structured data is the primary machine-readable signal that tells AI systems what an entity IS, what it does, and how it connects to other entities. While schema markup has traditionally been about earning Google rich results, its role in GEO is fundamentally different: **structured data is how AI models understand and trust your entity**. A complete entity graph in structured data dramatically increases citation probability across all AI search platforms. ## How to Use This Skill 1. Fetch the target page HTML using `fetch_page.py` (see note below) 2. Detect all existing structured data (JSON-LD, Microdata, RDFa) 3. Validate detected schemas against Schema.org specifications 4. Identify missing recommended schemas based on business type 5. Generate ready-to-use JSON-LD code blocks 6. Output GEO-SCHEMA-REPORT.md --- ## Step 1: Detection **IMPORTANT:** WebFetch converts HTML to markdown and strips `` content, which removes JSON-LD blocks. Use `fetch_page.py` instead: ```bash python3 ~/.claude/skills/geo/scripts/fetch_page.py page ``` The output includes a `structured_data` array with all parsed JSON-LD blocks from the page. ### Scan for JSON-LD Look for `