ourdigital/our-claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(seo-schema-validator): back the upgraded SKILL.md with a working 5-layer pipeline

Browse Source 
The "Upgrade Schema Validator" commit added SKILL.md referencing files that did
not exist. Implement them so the skill actually runs:

- scripts/validate_schema.py — 5-layer offline validator (L0 coverage, L1 syntax,
  L2 vocabulary/value-format, L3 rich-result, L4 consistency) with xlsx/csv/jsonl/
  json/dir/live-URL adapters. Gate = zero P0; exits 1 on failure.
- scripts/schema_rules.json — curated hotel-focused, offline rule set (edit-only
  extension point).
- scripts/make_sample.py + fixtures/sample_schema.csv — deliberately flawed fixture
  seeding ≥1 defect per layer; used to self-test.
- references/ — validation-methodology, defect-taxonomy (25 codes), hotel-type-map.
- templates/ — client-qa-report, decision-log.
- code/CLAUDE.md — redirect legacy single-URL tool to the new pipeline.

Noise control: MISSING_RECOMMENDED aggregated one-line-per-node; unexpected-property
checks opt-in via --strict. Generalized client-specific shilla-type-map → hotel-type-map.
Self-tested: default P0=5/P1=4/P2=14 FAIL, --strict --no-recommended P2=0, adapters verified.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Yim
2026-05-27 23:48:51 +09:00
parent ba88247496
commit 4f48ba3c59
12 changed files with 1636 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
custom-skills/16-seo-schema-validator/code/CLAUDE.md
View File

@@ -1,148 +1,57 @@
# CLAUDE.md
# CLAUDE.md — seo-schema-validator (Claude Code)
## Overview
## Canonical entry point
Structured data validator: extract, parse, and validate JSON-LD, Microdata, and RDFa markup against schema.org vocabulary.
This skill was upgraded to a **5-layer dataset-QA pipeline**. The authoritative
directive and run instructions live in the skill root:
## Quick Start
- **`../SKILL.md`** — modes, the 5 layers, stage gates, how to run.
- **`../scripts/validate_schema.py`** — the validator (run this, not the legacy script below).
- **`../scripts/schema_rules.json`** — the offline rule set (edit this to add a type/rule).
- **`../references/`** — `validation-methodology.md`, `defect-taxonomy.md`, `hotel-type-map.md`.
- **`../templates/`** — `client-qa-report-template.md`, `decision-log.md`.
```bash
pip install -r scripts/requirements.txt
python scripts/schema_validator.py --url https://example.com
# Primary use — QA an AUTHORED dataset before the client sees it (Mode A)
python ../scripts/validate_schema.py DATASET.xlsx --url-list URLLIST.xlsx --out schema_qa_out
# Highest-signal pre-review gate
python ../scripts/validate_schema.py DATASET.csv --strict --no-recommended --out qa_strict
# Try the bundled flawed fixture first
python ../scripts/make_sample.py
python ../scripts/validate_schema.py ../fixtures/sample_schema.csv --out demo_out
# Post-deploy live audit (Mode B) — feeds seo-comprehensive-audit stage 4
python ../scripts/validate_schema.py --live https://example.com --out live_out
```
## Scripts
Gate rule: **PASS = zero P0.** The process exits 1 when the gate fails, so it stops
`&&` chains and CI. Only P0-free entries advance to client review.
| Script | Purpose |
|--------|---------|
| `schema_validator.py` | Extract and validate structured data |
| `base_client.py` | Shared utilities |
## Legacy single-URL tool (kept for quick one-offs)
## Usage
`scripts/schema_validator.py --url <URL>` extracts and validates structured data from
one live page (JSON-LD / Microdata / RDFa via extruct). It predates the pipeline and is
**not** the gate. For any dataset or client-facing QA, use `validate_schema.py` above.
```bash
# Validate page schema
python scripts/schema_validator.py --url https://example.com
# JSON output
pip install -r scripts/requirements.txt # extruct, jsonschema, rdflib, lxml, requests
python scripts/schema_validator.py --url https://example.com --json
# Validate local file
python scripts/schema_validator.py --file schema.json
# Check Rich Results eligibility
python scripts/schema_validator.py --url https://example.com --rich-results
```
## Supported Formats
## Notion output (OurDigital SEO Audit Log)
| Format | Detection |
|--------|-----------|
| JSON-LD | `<script type="application/ld+json">` |
| Microdata | `itemscope`, `itemtype`, `itemprop` |
| RDFa | `vocab`, `typeof`, `property` |
## Validation Levels
### 1. Syntax Validation
- Valid JSON structure
- Proper nesting
- No syntax errors
### 2. Schema.org Vocabulary
- Valid @type values
- Known properties
- Correct property types
### 3. Google Rich Results
- Required properties present
- Recommended properties
- Feature-specific requirements
## Schema Types Validated
| Type | Required Properties | Rich Result |
|------|---------------------|-------------|
| Article | headline, author, datePublished | Yes |
| Product | name, offers | Yes |
| LocalBusiness | name, address | Yes |
| FAQPage | mainEntity | Yes |
| Organization | name, url | Yes |
| BreadcrumbList | itemListElement | Yes |
| WebSite | name, url | Sitelinks |
## Output
```json
{
"url": "https://example.com",
"schemas_found": 3,
"schemas": [
{
"@type": "Organization",
"valid": true,
"rich_results_eligible": true,
"issues": [],
"warnings": []
}
],
"summary": {
"valid": 3,
"invalid": 0,
"rich_results_eligible": 2
}
}
```
## Issue Severity
| Level | Description |
|-------|-------------|
| Error | Invalid schema, blocks rich results |
| Warning | Missing recommended property |
| Info | Optimization suggestion |
## Dependencies
```
extruct>=0.16.0
jsonschema>=4.21.0
rdflib>=7.0.0
lxml>=5.1.0
requests>=2.31.0
```
## Notion Output (Required)
**IMPORTANT**: All audit reports MUST be saved to the OurDigital SEO Audit Log database.
### Database Configuration
When a run is part of an OurDigital/D.intelligence audit, log a summary to the SEO Audit
Log database. Per the user-level Notion rule, push **page content** with the
`notion-writer` skill; use Notion MCP only for **properties** (Status, Category, etc.).
| Field | Value |
|-------|-------|
| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
| URL | https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef |
### Required Properties
| Property | Type | Description |
|----------|------|-------------|
| Issue | Title | Report title (Korean + date) |
| Site | URL | Audited website URL |
| Category | Select | Technical SEO, On-page SEO, Performance, Schema/Structured Data, Sitemap, Robots.txt, Content, Local SEO |
| Priority | Select | Critical, High, Medium, Low |
| Found Date | Date | Audit date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: [TYPE]-YYYYMMDD-NNN |
### Language Guidelines
- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., SEO Audit, Core Web Vitals, Schema Markup)
- URLs and code remain unchanged
### Example MCP Call
```bash
mcp-cli call notion/API-post-page '{"parent": {"database_id": "2c8581e5-8a1e-8035-880b-e38cefc2f3ef"}, "properties": {...}}'
```
| Category | `Schema/Structured Data` |
| Priority | map gate: FAIL→Critical/High, PASS-with-P1→Medium, PASS-clean→Low |
| Audit ID | `SCHEMA-YYYYMMDD-NNN` |
Report content in Korean; keep technical terms (Schema, JSON-LD, rich result) and
URLs/code unchanged.