chore(seo-schema-generator): restore dual-platform code/ + desktop/ structure

The full-merge commit removed 17's code/ and desktop/ folders along with the old template-fill generator, leaving 17 structurally inconsistent with 16 (and the repo's documented dual-platform convention). Restore them for the MERGED skill: - code/CLAUDE.md — Claude Code directive pointing to the root two-mode pipeline (no script duplication; root scripts/ stays the single source of truth). - desktop/SKILL.md + skill.yaml — Claude Desktop directive for the two-mode skill. - desktop/tools/{firecrawl,perplexity}.md — restored verbatim from git (still used by Mode 1 crawl / Mode 2 research). The old generator's logic stays retired; only the dual-platform folder structure and relevant tool docs return. 17 now matches 16's layout. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-28 00:45:10 +09:00
parent 1706a820fe
commit 1e3b2a4fa0
5 changed files with 151 additions and 0 deletions
--- a/custom-skills/17-seo-schema-generator/code/CLAUDE.md
+++ b/custom-skills/17-seo-schema-generator/code/CLAUDE.md
@@ -0,0 +1,52 @@
+# CLAUDE.md — seo-schema-generator (Claude Code)
+
+## Canonical entry point
+
+This skill was upgraded to a **two-mode source-to-schema pipeline** (it absorbed and
+retired the old template-fill generator). The authoritative directive and run
+instructions live in the skill root:
+
+- **`../SKILL.md`** — the two modes, the claims-register pivot, stage gates, how to run.
+- **`../scripts/extract_site_claims.py`** — Mode 1: existing site → claims register.
+- **`../scripts/build_schema_drafts.py`** — claims register → JSON-LD drafts + dataset CSV.
+- **`../scripts/type_templates.json`** — draft templates (edit JSON to add a type).
+- **`../references/`** — `site-extraction-methodology.md` (Mode 1), `source-to-schema-methodology.md` (Mode 2), `source-authority-hierarchy.md`, `entity-and-type-map.md`.
+- **`../templates/`** — `claims-register.csv`, `source-register.csv`, `review-guide.md`.
+
+```bash
+# Try the bundled sample first (Mode 2)
+python ../scripts/make_sample.py
+python ../scripts/build_schema_drafts.py ../fixtures/sample_claims.csv --out drafts_out
+
+# Mode 1 — existing site → claims register (URLs, or local .html / a directory offline)
+python ../scripts/extract_site_claims.py https://example.com/ --out site_claims
+python ../scripts/build_schema_drafts.py site_claims/claims_register.csv --out drafts_out
+
+# Hand off to the QA gate (must reach zero P0)
+python ../../16-seo-schema-validator/scripts/validate_schema.py \
+    drafts_out/schema_drafts_dataset.csv --out qa_out
+```
+
+Core rule: **only CONFIRMED, non-conflicting claims become schema.** Unfilled template
+slots are pruned — never emitted as `{{…}}` or `TODO`. **Generate (17) → Validate (16).**
+
+## Retired
+
+The previous template-fill tool (`schema_generator.py` + per-type JSON templates) is
+superseded by the claims-register engine above and has been removed. Use
+`build_schema_drafts.py` for all generation.
+
+## Notion output (OurDigital SEO Audit Log)
+
+When generation is part of an OurDigital/D.intelligence engagement, 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**.
+
+| Field | Value |
+|-------|-------|
+| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
+| Category | `Schema/Structured Data` |
+| Audit ID | `SCHEMA-YYYYMMDD-NNN` |
+
+Report content in Korean; keep technical terms (Schema, JSON-LD, claims register) and
+URLs/code unchanged.
--- a/custom-skills/17-seo-schema-generator/desktop/SKILL.md
+++ b/custom-skills/17-seo-schema-generator/desktop/SKILL.md
@@ -0,0 +1,55 @@
+---
+name: seo-schema-generator
+description: |
+  Generates validation-ready JSON-LD for a site via a claims register — Mode 1 from
+  an existing website, Mode 2 from collected sources for a not-yet-published site.
+  Triggers: generate schema, create JSON-LD, source-to-schema, pre-launch schema,
+  schema from site, claims register, 스키마 생성, 스키마 저작.
+---
+
+# SEO Schema Generator
+
+> Desktop reference. The full, runnable specification (scripts, references, templates,
+> fixtures, stage gates) is the skill-root `SKILL.md` and its bundled directories — this
+> file is the Claude Desktop entry point.
+
+## Purpose
+
+Author JSON-LD for a site whether or not its pages exist yet. Both scenarios route
+through one pivot — a **claims register** (provenance-tracked, conflict-resolved facts) —
+then generate pruned drafts that hand off to **seo-schema-validator** (generate → validate).
+
+## Two modes, one pipeline
+
+| | Mode 1 — existing site | Mode 2 — collected sources |
+|---|---|---|
+| Source of truth | the live pages | scattered sources (DART, Wikidata, brochures) |
+| Seed the register with | extract from pages | manual research |
+| Hard part | extraction & mapping | authority hierarchy + entity reconciliation |
+
+Everything after the claims register (build drafts → prune unfilled slots → validate)
+is identical. **Only CONFIRMED, non-conflicting claims become schema;** unfilled template
+slots are deleted, never shipped as placeholders.
+
+## MCP Tool Usage
+
+```
+mcp__firecrawl__scrape / crawl : Mode 1 — pull existing pages to extract facts
+mcp__perplexity__search        : Mode 2 — discover & cross-check authoritative sources
+```
+
+## Workflow
+
+1. Lock the entity→type map (scope first).
+2. Seed the claims register (Mode 1: extract from pages · Mode 2: research → register).
+3. Reconcile to CONFIRMED; clear conflicts.
+4. Build drafts from type templates (placeholders pruned).
+5. Validate with seo-schema-validator — gate = zero P0.
+6. Fix P0, re-validate, then client review against the report (not raw JSON).
+
+## Notes
+
+- Mode 1 inference (title/OpenGraph) is seeded PENDING and never auto-ships; existing
+  JSON-LD is seeded CONFIRMED. If a site already has good JSON-LD, audit it with
+  seo-schema-validator (Mode B) instead of regenerating.
+- Authoritative rich-result eligibility still needs Google's online test on a sample.
--- a/custom-skills/17-seo-schema-generator/desktop/skill.yaml
+++ b/custom-skills/17-seo-schema-generator/desktop/skill.yaml
@@ -0,0 +1,14 @@
+# Skill metadata (extracted from SKILL.md frontmatter)
+
+name: seo-schema-generator
+description: |
+  JSON-LD generator with two modes — from an existing website, or from collected
+  sources for a not-yet-published site — both via a claims register. Triggers:
+  generate schema, create JSON-LD, source-to-schema, schema from site, claims register.
+
+# Optional fields
+allowed-tools:
+  - mcp__firecrawl__*
+  - mcp__perplexity__*
+
+# triggers: []  # TODO: Extract from description
--- a/custom-skills/17-seo-schema-generator/desktop/tools/firecrawl.md
+++ b/custom-skills/17-seo-schema-generator/desktop/tools/firecrawl.md
@@ -0,0 +1,15 @@
+# Firecrawl
+
+> TODO: Document tool usage for this skill
+
+## Available Commands
+
+- [ ] List commands
+
+## Configuration
+
+- [ ] Add configuration details
+
+## Examples
+
+- [ ] Add usage examples
--- a/custom-skills/17-seo-schema-generator/desktop/tools/perplexity.md
+++ b/custom-skills/17-seo-schema-generator/desktop/tools/perplexity.md
@@ -0,0 +1,15 @@
+# Perplexity
+
+> TODO: Document tool usage for this skill
+
+## Available Commands
+
+- [ ] List commands
+
+## Configuration
+
+- [ ] Add configuration details
+
+## Examples
+
+- [ ] Add usage examples