@opendirectory.dev/skills 0.1.0

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

@@ -0,0 +1,192 @@
+---
+name: schema-markup-generator
+description: ''
+compatibility: [claude-code, gemini-cli, github-copilot]
+author: OpenDirectory
+version: 1.0.0
+---
+
+# schema-markup-generator
+
+You are an SEO engineer specialising in structured data. Your job is to read a webpage and generate valid JSON-LD schema markup that matches what is actually on the page.
+
+DO NOT INVENT DATA. Every field in the JSON-LD must come from content that exists on the page. If a required field is not present on the page, flag it as missing rather than filling it with placeholder or guessed data.
+
+Before starting, confirm you have a target. Accepted inputs:
+- A live URL to crawl with Chrome
+- A local HTML file path
+- Pasted HTML content
+
+If no input was provided, ask: "What page do you want to generate schema markup for? Give me a URL, a file path, or paste the HTML."
+
+---
+
+## Workflow
+
+### Step 1: Setup Check
+
+Check the environment before doing anything else.
+
+For live URLs: Confirm Chrome is running with remote debugging enabled. If the Chrome DevTools MCP is available, proceed. If not, try fetching the page with curl as a fallback.
+
+For local files or pasted HTML: No Chrome needed. Read the content directly.
+
+Check for GITHUB_TOKEN if the user wants a PR at the end. Note its presence but do not block. Output-only mode works without it.
+
+QA: What is the input source? Is it accessible? State what crawl method you will use.
+
+---
+
+### Step 2: Crawl the Page and Extract Content
+
+Connect to the page using the available method.
+
+Using Chrome DevTools MCP:
+- Navigate to the URL
+- Wait for the page to fully load (including JavaScript-rendered content)
+- Extract the full page text content and visible HTML structure
+- Capture: page title, meta description, headings (h1-h6), all body text, image URLs and alt text, links, any visible prices, dates, author names, company name, address, phone numbers, FAQ sections, numbered steps, reviews and ratings
+
+Using curl fallback:
+- Fetch with a browser User-Agent
+- Parse the HTML for the same content listed above
+
+Using local file or pasted HTML:
+- Read the content directly
+- Parse the same fields
+
+QA: List the key content you found. What is the page about? What structured content exists (FAQ pairs, product pricing, article byline, address, steps)?
+
+---
+
+### Step 3: Detect Schema Types Needed
+
+Analyse the extracted content. A page often needs more than one schema type.
+
+Detection rules:
+
+| Page type | Required content signals | Schema type(s) to generate |
+|-----------|--------------------------|---------------------------|
+| FAQ page or FAQ section | 3 or more question/answer pairs | FAQPage |
+| Blog post or article | Headline, author, publish date, article body | Article or BlogPosting |
+| Company or about page | Company name, description, logo or social links | Organization |
+| Product page | Product name, price, availability | Product |
+| Homepage | Site name, search functionality | WebSite |
+| How-to guide or tutorial | Numbered steps with descriptions | HowTo |
+| Page with breadcrumb navigation | Breadcrumb trail visible on page | BreadcrumbList |
+| Software tool or app | App name, OS, pricing, download link | SoftwareApplication |
+| Local business | Physical address, phone, hours | LocalBusiness |
+
+Apply multiple types if the page qualifies for more than one. A blog post page, for example, often needs Article and BreadcrumbList. An about page often needs Organization and WebSite (if it is the homepage).
+
+State the schema types you will generate and why.
+
+QA: Does the detected type match the page content? Is there enough data to populate the required fields for each type?
+
+---
+
+### Step 4: Read the Spec and Templates
+
+Read `references/json-ld-spec.md` for the required and recommended fields for each detected schema type.
+
+Read `references/output-template.md` for the exact JSON structure to use for each type.
+
+For each schema type you will generate, note:
+- Which required fields are present in the page content
+- Which required fields are missing (you will flag these, not invent them)
+- Which recommended fields are present and worth including
+
+---
+
+### Step 5: Generate the JSON-LD
+
+Generate one `<script type="application/ld+json">` block per schema type.
+
+Rules:
+- Every value must come from the page content extracted in Step 2
+- Use the templates in `references/output-template.md` as the structure
+- For missing required fields: add a comment inside the JSON as `"MISSING_fieldName": "not found on page"` so the user knows what to add
+- For missing recommended fields: omit them silently
+- Use ISO 8601 for all dates and durations
+- Use full absolute URLs for all image, page, and site references
+- Nest objects correctly (author as Person object, publisher as Organization object, etc.)
+- If multiple schema types apply, output each as a separate script block
+
+Do not output generic placeholder values like "Company Name Here" or "Enter description". Either use the real value or flag it as MISSING.
+
+QA: For each generated block, verify: Is every value traceable to the page content? Are all required fields either populated or explicitly flagged as MISSING?
+
+---
+
+### Step 6: Validate the Output
+
+Before presenting the output, run through this checklist for each JSON-LD block:
+
+- [ ] Valid JSON syntax (no trailing commas, balanced braces)
+- [ ] @context is "https://schema.org"
+- [ ] @type matches the intended schema type
+- [ ] All required fields for the type are either populated or flagged as MISSING
+- [ ] All URLs are absolute (start with https://)
+- [ ] All dates use ISO 8601 format
+- [ ] No invented data: every value traces to page content
+- [ ] No placeholder strings left in the output
+
+Fix any syntax errors before presenting. State which required fields were found and which were flagged as MISSING.
+
+---
+
+### Step 7: Output and Deploy
+
+Present the output clearly.
+
+For each schema block:
+1. State the schema type and which page it belongs to
+2. Show the full `<script type="application/ld+json">` block in a code block
+3. State where in the HTML to place it (inside `<head>` before `</head>`)
+4. List any MISSING fields the user needs to fill in manually
+
+Then ask: "Should I open a GitHub PR to inject this into your codebase, or do you want to add it manually?"
+
+If the user confirms a PR:
+- Check for GITHUB_TOKEN and GITHUB_REPO in the environment
+- Detect the framework (Next.js, Astro, plain HTML, etc.) to know the right injection point
+- Insert the script block in the correct location for the framework
+- Open a PR via the GitHub CLI or API
+
+Framework-specific injection points:
+
+| Framework | Where to inject |
+|-----------|----------------|
+| Next.js (App Router) | Add `<Script type="application/ld+json">` inside the page component, or use `next/head` for pages router |
+| Astro | Add inside `<head>` in the page's layout or front matter |
+| HTML | Add inside `<head>` before `</head>` |
+| Jekyll | Add to `_includes/head.html` or the page's front matter with a custom head include |
+| Nuxt | Add via `useHead()` composable or `<Head>` component |
+
+QA: Was the output placed correctly? Are all MISSING fields clearly communicated to the user?
+
+---
+
+## What Good Output Looks Like
+
+- Every JSON-LD value traces directly to visible page content
+- Required fields are populated or explicitly flagged as MISSING with a clear label
+- JSON syntax is valid (parseable by any JSON validator)
+- URLs are absolute and correct
+- Dates are in ISO 8601 format
+- The placement instruction matches the user's actual framework
+- The user knows exactly what to do next
+
+## What Bad Output Looks Like
+
+- Invented values not present on the page ("Best Company Inc.", generic descriptions)
+- Placeholder strings left in the output
+- Relative URLs instead of absolute URLs
+- Missing @context or @type
+- Invalid JSON (trailing comma, unbalanced brackets)
+- Wrong schema type for the page content
+- Silent omission of required fields without flagging them
+
+
+
+

package/skills/schema-markup-generator/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "schema-markup-generator",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Generate schema markup for this FAQ page: https://stripe.com/docs/faq",
+      "expected_output": "Agent crawls the page using Chrome DevTools MCP or curl fallback. Extracts all visible question/answer pairs. Detects FAQPage schema type. Reads references/json-ld-spec.md and references/output-template.md. Generates a valid FAQPage JSON-LD block with one Question object per FAQ pair. Every question and answer text matches the visible page content. No invented Q&A pairs. Outputs a complete <script type='application/ld+json'> block. States where to place it (inside <head>). Flags any required fields that were not found on the page. Offers to open a GitHub PR.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Add schema markup to this blog post: https://vercel.com/blog/how-we-optimized-package-imports-in-next-js",
+      "expected_output": "Agent crawls the blog post page. Detects Article or BlogPosting schema type (plus BreadcrumbList if breadcrumbs are visible). Extracts: headline from page title, author name and profile URL, publish date, article image URL, site name, site logo URL. Generates BlogPosting JSON-LD with all extracted fields. Dates in ISO 8601 format. All image URLs are absolute. If any required field (headline, image, datePublished, author) is missing from the page, flags it with MISSING_ prefix. Outputs separate script blocks for Article and BreadcrumbList if applicable. Character count not required for this skill.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Generate organization schema for our about page at https://linear.app/about",
+      "expected_output": "Agent crawls the about page. Detects Organization schema type. Extracts: company name, website URL, company description, logo URL, social media profile links (LinkedIn, Twitter, GitHub, etc.), contact information if present. Generates Organization JSON-LD with @id set to the site URL plus /#organization. sameAs array contains only social URLs actually found on the page. contactPoint included only if contact details are visible. No invented company data. Offers to open a GitHub PR with the markup.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "This product page needs schema markup: https://www.notion.so/product/ai",
+      "expected_output": "Agent crawls the product page. Detects Product and possibly SoftwareApplication schema types (Notion AI is software). Extracts: product name, description, pricing information, availability status. If ratings are visible on the page, includes aggregateRating. If no ratings are visible, omits aggregateRating. All prices use correct priceCurrency code. availability uses the correct schema.org URL (InStock, OutOfStock, etc.). Flags as MISSING any required fields not found on the page. Outputs a Product or SoftwareApplication JSON-LD block. States validation steps the user should run (Rich Results Test URL).",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Generate all the schema markup needed for our homepage. Here is the HTML: <pasted HTML of a homepage with company name, tagline, search bar, social links, and contact email>",
+      "expected_output": "Agent reads the pasted HTML directly (no Chrome needed). Detects multiple schema types: WebSite (homepage with site name and URL), Organization (company info from the page), and WebSite with potentialAction SearchAction if a search bar is present. Generates separate JSON-LD blocks for each type. WebSite block includes potentialAction only if a search input is found in the HTML. Organization block includes only the social links and contact info actually present in the HTML. No Chrome required since HTML was pasted. No invented data. Outputs each block with clear labels. Lists MISSING fields if any required fields were absent from the HTML.",
+      "files": []
+    }
+  ]
+}

package/skills/schema-markup-generator/references/json-ld-spec.md

@@ -0,0 +1,263 @@
+# JSON-LD Schema Markup Spec
+
+This document defines the required and recommended fields for each schema type this skill generates. The agent reads this before generating any markup.
+
+---
+
+## Section 1: What JSON-LD Is and Why It Matters
+
+JSON-LD (JavaScript Object Notation for Linked Data) is Google's preferred format for structured data. You embed it as a `<script type="application/ld+json">` tag in the page `<head>`.
+
+Why it works better than alternatives (Microdata, RDFa):
+- Separate from HTML markup: you change the data without touching the visual layout
+- Google parses it reliably, including on JavaScript-rendered pages
+- AI crawlers (Google AI Overviews, ChatGPT, Perplexity) read JSON-LD consistently
+
+What it does for your pages:
+- Enables rich results in Google search (star ratings, FAQ dropdowns, product prices, how-to steps)
+- Helps Google understand what a page is about, not just what it says
+- Signals to AI systems that your content is authoritative and structured
+
+---
+
+## Section 2: Core JSON-LD Rules
+
+Every JSON-LD block must follow these rules:
+
+- The script tag: `<script type="application/ld+json">` placed inside `<head>`
+- Every block needs `"@context": "https://schema.org"` as the first property
+- Every block needs `"@type"` specifying the schema type
+- All URLs must be absolute (start with `https://`)
+- All dates must use ISO 8601 format: `"2026-04-10"` or `"2026-04-10T09:00:00+00:00"`
+- All durations must use ISO 8601: `"PT15M"` (15 minutes), `"PT1H30M"` (1 hour 30 minutes)
+- Multiple schema types on one page: one `<script>` block per type, not combined into one
+
+---
+
+## Section 3: Schema Types Reference
+
+### FAQPage
+
+Use when: The page has 2 or more question/answer pairs visible to the user. FAQ sections, support pages, product FAQ tabs.
+
+Google rich result: FAQ dropdowns appear directly under the search result.
+
+Required fields:
+- `@type`: "FAQPage"
+- `mainEntity`: array of Question objects, each with:
+  - `@type`: "Question"
+  - `name`: the question text (must match text visible on page)
+  - `acceptedAnswer.@type`: "Answer"
+  - `acceptedAnswer.text`: the answer text (must match text visible on page)
+
+Rules:
+- Questions and answers must be visible on the page — do not include hidden content
+- Minimum 2 questions, no maximum
+- Answer text can include basic HTML tags: `<p>`, `<ul>`, `<ol>`, `<li>`, `<a>`, `<br>`, `<strong>`, `<em>`
+- Do not mark up content that requires clicking "expand" to see unless that content is in the DOM
+
+---
+
+### Article and BlogPosting
+
+Use when: The page is a blog post, news article, opinion piece, or editorial content.
+
+Use `Article` for general editorial content. Use `BlogPosting` specifically for informal blog posts. Use `NewsArticle` for news publications.
+
+Google rich result: Article can appear in Google Discover and News with image, title, and date.
+
+Required fields:
+- `@type`: "Article", "BlogPosting", or "NewsArticle"
+- `headline`: the article title (max 110 characters for Google News)
+- `image`: array of image URLs. At least one image. Recommended: provide three aspect ratios (16x9, 4x3, 1x1). Minimum 50,000 pixels total (e.g. 696x392px).
+- `datePublished`: ISO 8601 publish date
+- `author`: object or array with `@type` ("Person" or "Organization") and `name`
+
+Recommended fields:
+- `dateModified`: ISO 8601 last-updated date
+- `publisher`: Organization object with `name`, `url`, `logo`
+- `description`: article summary (from meta description or first paragraph)
+- `url`: canonical URL of the article
+
+---
+
+### Organization
+
+Use when: The page represents a company, nonprofit, or institution. Common on About, Company, or homepage pages.
+
+Google use: Establishes entity understanding for Knowledge Panel. Helps Google connect your site to your brand.
+
+Required fields:
+- `@type`: "Organization"
+- `name`: company name
+- `url`: company website
+
+Recommended fields:
+- `logo`: ImageObject with `url`, `width`, `height`
+- `sameAs`: array of social profile URLs (LinkedIn, Twitter/X, YouTube, GitHub, etc.)
+- `description`: company description
+- `contactPoint`: ContactPoint object with `contactType` and `email` or `telephone`
+- `@id`: use `"https://yourdomain.com/#organization"` as a stable identifier
+
+---
+
+### Product
+
+Use when: The page sells or describes a specific product with a price.
+
+Google rich result: Product price, availability, and ratings appear in search results.
+
+Required fields (at least one of these must be present to qualify for rich results):
+- `review` (Review object)
+- `aggregateRating` (AggregateRating object)
+- `offers` (Offer object)
+
+Core fields:
+- `@type`: "Product"
+- `name`: product name
+- `image`: array of product image URLs
+- `description`: product description
+
+Offer fields (when pricing is on the page):
+- `offers.@type`: "Offer"
+- `offers.priceCurrency`: ISO 4217 code ("USD", "GBP", "EUR")
+- `offers.price`: numeric price as string ("29.99")
+- `offers.availability`: one of `https://schema.org/InStock`, `https://schema.org/OutOfStock`, `https://schema.org/PreOrder`
+- `offers.url`: product page URL
+
+AggregateRating fields (when ratings are on the page):
+- `aggregateRating.ratingValue`: average rating (e.g. 4.5)
+- `aggregateRating.reviewCount`: number of reviews
+- `aggregateRating.bestRating`: maximum rating (usually 5)
+
+---
+
+### WebSite
+
+Use when: Generating markup for the homepage or site-level schema.
+
+Google use: Enables the Sitelinks Searchbox in search results when users search your brand name.
+
+Required fields:
+- `@type`: "WebSite"
+- `name`: site name
+- `url`: homepage URL
+
+Recommended fields (for Sitelinks Searchbox):
+- `potentialAction.@type`: "SearchAction"
+- `potentialAction.target.urlTemplate`: search URL pattern (e.g. `"https://example.com/search?q={search_term_string}"`)
+- `potentialAction.query-input`: `"required name=search_term_string"`
+
+Only add `potentialAction` if the site has a working search feature. Do not add it for sites without search.
+
+---
+
+### HowTo
+
+Use when: The page is a step-by-step guide or tutorial with numbered steps.
+
+Google rich result: Steps appear directly in search results as an expandable list.
+
+Required fields:
+- `@type`: "HowTo"
+- `name`: guide title
+- `step`: array of HowToStep objects, each with:
+  - `@type`: "HowToStep"
+  - `name`: step title
+  - `text`: step description
+
+Recommended fields:
+- `image`: feature image for the guide
+- `estimatedDuration`: total time as ISO 8601 duration (e.g. `"PT30M"`)
+- `supply`: array of HowToSupply objects if materials are needed
+- `tool`: array of HowToTool objects if tools are needed
+
+---
+
+### BreadcrumbList
+
+Use when: The page has a visible breadcrumb navigation trail.
+
+Google use: Displays breadcrumb path in search results instead of the full URL.
+
+Required fields:
+- `@type`: "BreadcrumbList"
+- `itemListElement`: array of ListItem objects, each with:
+  - `@type`: "ListItem"
+  - `position`: integer position starting at 1
+  - `name`: display text for this breadcrumb
+  - `item`: absolute URL (required for all items except the last)
+
+Rules:
+- Positions must be sequential integers starting at 1
+- The last item does not need an `item` URL (it is the current page)
+
+---
+
+### SoftwareApplication
+
+Use when: The page describes a software tool, app, or developer product.
+
+Google rich result: Star ratings and price can appear in search results.
+
+Required fields:
+- `@type`: "SoftwareApplication"
+- `name`: app name
+- `operatingSystem`: one or more of "Windows", "macOS", "Linux", "Android", "iOS", "Web"
+- `applicationCategory`: one of "GameApplication", "BusinessApplication", "EducationalApplication", "DeveloperApplication", "DesignApplication", "UtilitiesApplication", "SecurityApplication", "SocialNetworkingApplication"
+
+Recommended fields:
+- `offers`: pricing (use `"price": "0"` for free apps, or actual price)
+- `aggregateRating`: if ratings are on the page
+- `description`: app description
+- `url`: app or product page URL
+- `downloadUrl`: direct download link if available
+
+---
+
+### LocalBusiness
+
+Use when: The page represents a physical business location with an address.
+
+Google rich result: Business details, hours, and ratings appear in local search results and maps.
+
+Required fields:
+- `@type`: "LocalBusiness" (or a more specific subtype: "Restaurant", "Store", "MedicalBusiness", etc.)
+- `name`: business name
+- `address`: PostalAddress object with `streetAddress`, `addressLocality`, `addressRegion`, `postalCode`, `addressCountry`
+
+Recommended fields:
+- `telephone`: phone number in international format
+- `url`: website URL
+- `openingHoursSpecification`: array of OpeningHoursSpecification objects with `dayOfWeek`, `opens`, `closes`
+- `aggregateRating`: if reviews are on the page
+- `image`: business photos
+- `priceRange`: "$", "$$", "$$$", or "$$$$"
+
+---
+
+## Section 4: Common Validation Errors
+
+These errors cause Google to reject or ignore schema markup:
+
+| Error | What causes it | How to fix |
+|-------|----------------|------------|
+| Missing @context | Forgot the first line | Add `"@context": "https://schema.org"` |
+| Relative URLs | Using `/path` instead of `https://domain.com/path` | Use absolute URLs everywhere |
+| Wrong date format | Using "April 10, 2026" instead of ISO 8601 | Use `"2026-04-10"` format |
+| Content mismatch | Schema says X, visible page says Y | Schema must reflect page content |
+| Hidden content | Marking up content not visible to users | Only markup visible, on-page content |
+| Invented data | Filling fields with guessed or generic values | Every value must come from the page |
+| Invalid JSON | Trailing comma, unmatched bracket | Validate JSON syntax before outputting |
+| Wrong @type for content | Using "Article" for a product page | Match @type to actual page purpose |
+
+---
+
+## Section 5: Validation Tools
+
+After generating markup, the user should validate it at:
+
+- Google Rich Results Test: https://search.google.com/test/rich-results
+- Schema.org Validator: https://validator.schema.org
+
+These tools show which rich result types the markup qualifies for and flag any errors.