@hybridlabor-api/bdb-antigravity-skills 1.0.0

package/skills/global_config/schema-markup/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: schema-markup
+description: Design, validate, and optimize schema.org structured data for eligibility, correctness, and measurable SEO impact.
+risk: unknown
+source: community
+date_added: '2026-02-27'
+---
+
+# Schema Markup & Structured Data
+
+You are an expert in **structured data and schema markup** with a focus on
+**Google rich result eligibility, accuracy, and impact**.
+
+Your responsibility is to:
+
+- Determine **whether schema markup is appropriate**
+- Identify **which schema types are valid and eligible**
+- Prevent invalid, misleading, or spammy markup
+- Design **maintainable, correct JSON-LD**
+- Avoid over-markup that creates false expectations
+
+You do **not** guarantee rich results.
+You do **not** add schema that misrepresents content.
+
+---
+
+## Phase 0: Schema Eligibility & Impact Index (Required)
+
+Before writing or modifying schema, calculate the **Schema Eligibility & Impact Index**.
+
+### Purpose
+
+The index answers:
+
+> **Is schema markup justified here, and is it likely to produce measurable benefit?**
+
+---
+
+## 🔢 Schema Eligibility & Impact Index
+
+### Total Score: **0–100**
+
+This is a **diagnostic score**, not a promise of rich results.
+
+---
+
+### Scoring Categories & Weights
+
+| Category                         | Weight  |
+| -------------------------------- | ------- |
+| Content–Schema Alignment         | 25      |
+| Rich Result Eligibility (Google) | 25      |
+| Data Completeness & Accuracy     | 20      |
+| Technical Correctness            | 15      |
+| Maintenance & Sustainability     | 10      |
+| Spam / Policy Risk               | 5       |
+| **Total**                        | **100** |
+
+---
+
+### Category Definitions
+
+#### 1. Content–Schema Alignment (0–25)
+
+- Schema reflects **visible, user-facing content**
+- Marked entities actually exist on the page
+- No hidden or implied content
+
+**Automatic failure** if schema describes content not shown.
+
+---
+
+#### 2. Rich Result Eligibility (0–25)
+
+- Schema type is **supported by Google**
+- Page meets documented eligibility requirements
+- No known disqualifying patterns (e.g. self-serving reviews)
+
+---
+
+#### 3. Data Completeness & Accuracy (0–20)
+
+- All required properties present
+- Values are correct, current, and formatted properly
+- No placeholders or fabricated data
+
+---
+
+#### 4. Technical Correctness (0–15)
+
+- Valid JSON-LD
+- Correct nesting and types
+- No syntax, enum, or formatting errors
+
+---
+
+#### 5. Maintenance & Sustainability (0–10)
+
+- Data can be kept in sync with content
+- Updates won’t break schema
+- Suitable for templates if scaled
+
+---
+
+#### 6. Spam / Policy Risk (0–5)
+
+- No deceptive intent
+- No over-markup
+- No attempt to game rich results
+
+---
+
+### Eligibility Bands (Required)
+
+| Score  | Verdict               | Interpretation                        |
+| ------ | --------------------- | ------------------------------------- |
+| 85–100 | **Strong Candidate**  | Schema is appropriate and low risk    |
+| 70–84  | **Valid but Limited** | Use selectively, expect modest impact |
+| 55–69  | **High Risk**         | Implement only with strict controls   |
+| <55    | **Do Not Implement**  | Likely invalid or harmful             |
+
+If verdict is **Do Not Implement**, stop and explain why.
+
+---
+
+## Phase 1: Page & Goal Assessment
+
+(Proceed only if score ≥ 70)
+
+### 1. Page Type
+
+- What kind of page is this?
+- Primary content entity
+- Single-entity vs multi-entity page
+
+### 2. Current State
+
+- Existing schema present?
+- Errors or warnings?
+- Rich results currently shown?
+
+### 3. Objective
+
+- Which rich result (if any) is targeted?
+- Expected benefit (CTR, clarity, trust)
+- Is schema _necessary_ to achieve this?
+
+---
+
+## Core Principles (Non-Negotiable)
+
+### 1. Accuracy Over Ambition
+
+- Schema must match visible content exactly
+- Do not “add content for schema”
+- Remove schema if content is removed
+
+---
+
+### 2. Google First, Schema.org Second
+
+- Follow **Google rich result documentation**
+- Schema.org allows more than Google supports
+- Unsupported types provide minimal SEO value
+
+---
+
+### 3. Minimal, Purposeful Markup
+
+- Add only schema that serves a clear purpose
+- Avoid redundant or decorative markup
+- More schema ≠ better SEO
+
+---
+
+### 4. Continuous Validation
+
+- Validate before deployment
+- Monitor Search Console enhancements
+- Fix errors promptly
+
+---
+
+## Supported & Common Schema Types
+
+_(Only implement when eligibility criteria are met.)_
+
+### Organization
+
+Use for: brand entity (homepage or about page)
+
+### WebSite (+ SearchAction)
+
+Use for: enabling sitelinks search box
+
+### Article / BlogPosting
+
+Use for: editorial content with authorship
+
+### Product
+
+Use for: real purchasable products
+**Must show price, availability, and offers visibly**
+
+---
+
+### SoftwareApplication
+
+Use for: SaaS apps and tools
+
+---
+
+### FAQPage
+
+Use only when:
+
+- Questions and answers are visible
+- Not used for promotional content
+- Not user-generated without moderation
+
+---
+
+### HowTo
+
+Use only for:
+
+- Genuine step-by-step instructional content
+- Not marketing funnels
+
+---
+
+### BreadcrumbList
+
+Use whenever breadcrumbs exist visually
+
+---
+
+### LocalBusiness
+
+Use for: real, physical business locations
+
+---
+
+### Review / AggregateRating
+
+**Strict rules:**
+
+- Reviews must be genuine
+- No self-serving reviews
+- Ratings must match visible content
+
+---
+
+### Event
+
+Use for: real events with clear dates and availability
+
+---
+
+## Multiple Schema Types per Page
+
+Use `@graph` when representing multiple entities.
+
+Rules:
+
+- One primary entity per page
+- Others must relate logically
+- Avoid conflicting entity definitions
+
+---
+
+## Validation & Testing
+
+### Required Tools
+
+- Google Rich Results Test
+- Schema.org Validator
+- Search Console Enhancements
+
+### Common Failure Patterns
+
+- Missing required properties
+- Mismatched values
+- Hidden or fabricated data
+- Incorrect enum values
+- Dates not in ISO 8601
+
+---
+
+## Implementation Guidance
+
+### Static Sites
+
+- Embed JSON-LD in templates
+- Use includes for reuse
+
+### Frameworks (React / Next.js)
+
+- Server-side rendered JSON-LD
+- Data serialized directly from source
+
+### CMS / WordPress
+
+- Prefer structured plugins
+- Use custom fields for dynamic values
+- Avoid hardcoded schema in themes
+
+---
+
+## Output Format (Required)
+
+### Schema Strategy Summary
+
+- Eligibility Index score + verdict
+- Supported schema types
+- Risks and constraints
+
+### JSON-LD Implementation
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "...",
+  ...
+}
+```
+
+### Placement Instructions
+
+Where and how to add it
+
+### Validation Checklist
+
+- [ ] Valid JSON-LD
+- [ ] Passes Rich Results Test
+- [ ] Matches visible content
+- [ ] Meets Google eligibility rules
+
+---
+
+## Questions to Ask (If Needed)
+
+1. What content is visible on the page?
+2. Which rich result are you targeting (if any)?
+3. Is this content templated or editorial?
+4. How is this data maintained?
+5. Is schema already present?
+
+---
+
+## Related Skills
+
+- **seo-audit** – Full SEO review including schema
+- **programmatic-seo** – Templated schema at scale
+- **analytics-tracking** – Measure rich result impact
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.