docs(skills): add SKILL-MIGRATION-GUIDE + adopt root-SKILL.md hybrid as standard

- reference/SKILL-MIGRATION-GUIDE.md: one-page recipe to add a root SKILL.md to an
  existing skill (additive, no rewrite) — target structure, frontmatter checklist,
  a verified validation snippet, incremental-adoption guidance. References 16/17.
- CLAUDE.md: replace "Dual-Platform Skill Structure" with the hybrid (root SKILL.md +
  code/ + desktop/) as the going-forward standard; add "Root SKILL.md first" design
  principle; require a root SKILL.md for new skills; link the guide in Key Reference Files.
- SKILL-FORMAT-REQUIREMENTS.md: note the root-SKILL.md standard + cross-link the guide.

Validation snippet self-tested against 16/17 (frontmatter ≤1024, kebab name, all
referenced relative paths resolve).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -160,19 +160,28 @@ This is a Claude Skills collection repository containing:
 | 81 | mac-optimizer | macOS system health audit & optimization (Claude Code only) | "audit my mac", "system health", "clean up caches", "check security", "update packages" |
 | 82 | our-gdrive-organizer | Organize a Google Drive folder under OurDigital conventions: refresh README index, refresh per-subfolder READMEs, propose renames + moves | "/organize", "organize the Drive folder", "refresh the index", "rescan the folder" |
 
-## Dual-Platform Skill Structure
+## Skill Structure (root `SKILL.md` + dual-platform packaging)
 
-Each skill has two independent versions:
+**Going-forward standard.** Each skill has a root `SKILL.md` (the official Agent Skills
+format — natively loadable by Claude Code / Desktop / API) plus the OurDigital `code/` +
+`desktop/` packaging. Reference implementations: `16-seo-schema-validator`,
+`17-seo-schema-generator`. To migrate an older skill, follow
+`reference/SKILL-MIGRATION-GUIDE.md` (additive — no rewrite).
 
 ```
 XX-skill-name/
-├── code/                    # Claude Code version
-│   ├── CLAUDE.md            # Action-oriented directive
-│   ├── scripts/             # Executable Python/Bash
-│   └── docs/                # Documentation
+├── SKILL.md                 # Root directive — official Agent Skills format (LOADABLE)
+├── scripts/                 # Runnable scripts (single source of truth)
+├── references/              # Heavy docs, loaded on demand
+├── templates/               # Optional
+├── fixtures/                # Optional sample/test inputs
 │
-├── desktop/                 # Claude Desktop version
-│   ├── SKILL.md             # Skill directive with YAML frontmatter
+├── code/                    # Claude Code packaging
+│   ├── CLAUDE.md            # Redirects to ../SKILL.md + ../scripts (no duplication)
+│   └── scripts/             # Legacy/aux tools only
+│
+├── desktop/                 # Claude Desktop packaging
+│   ├── SKILL.md             # Desktop directive with YAML frontmatter
 │   ├── skill.yaml           # Extended metadata (optional)
 │   └── tools/               # MCP tool documentation
 │
@@ -180,24 +189,24 @@ XX-skill-name/
 └── README.md                # Overview
 ```
 
-### Platform Differences
+Older skills may still be `code/` + `desktop/` only (no root `SKILL.md`) — valid, but not
+directly loadable. Migrate incrementally, not in bulk.
 
-| Aspect | `code/` | `desktop/` |
-|--------|---------|------------|
-| Directive | CLAUDE.md | SKILL.md (with YAML frontmatter) |
-| Metadata | In CLAUDE.md | skill.yaml (optional) |
-| Tool docs | N/A | tools/ directory |
-| Execution | Direct Bash/Python | MCP tools only |
-| Scripts | Required | Reference only |
+### Layer roles
 
-### SKILL.md Format (Desktop)
+| Layer | Role |
+|-------|------|
+| root `SKILL.md` | Canonical, loadable directive + bundled resources |
+| `code/` | Claude Code packaging; `CLAUDE.md` redirects to the root |
+| `desktop/` | Claude Desktop view; `SKILL.md` + `skill.yaml` + `tools/` |
+
+### SKILL.md frontmatter (root + desktop)
 
 ```markdown
 ---
-name: skill-name-kebab-case
+name: skill-name-kebab-case        # letters, numbers, hyphens only
 description: |
-  Brief description of what the skill does.
-  Triggers: keyword1, keyword2, 한국어 트리거.
+  What it does + when to use. Triggers: keyword1, keyword2, 한국어 트리거.
 ---
 
 # Skill Title
@@ -205,6 +214,8 @@ description: |
 Content starts here...
 ```
 
+Whole frontmatter ≤ 1024 chars. Full rules + migration recipe: `reference/SKILL-MIGRATION-GUIDE.md`.
+
 ## Directory Layout
 
 ```
@@ -287,10 +298,11 @@ our-claude-skills/
 ## Skill Design Principles
 
 1. **One thing done well** - Each skill focuses on a single capability
-2. **Directives under 1,500 words** - Concise, actionable
-3. **Self-contained** - Each platform version is fully independent
-4. **Code-first development** - Build Claude Code version first
-5. **Progressive numbering** - Logical grouping by domain
+2. **Root `SKILL.md` first** - Ship a loadable root `SKILL.md`; keep `code/`+`desktop/` as packaging
+3. **Directives under 1,500 words** - Concise, actionable; push detail into `references/`
+4. **Self-contained** - Bundle scripts/refs as relative paths; one source of truth (no script dupes)
+5. **Code-first development** - Build and self-test the runnable version first
+6. **Progressive numbering** - Logical grouping by domain
 
 ## Creating New Skills
 
@@ -299,8 +311,12 @@ our-claude-skills/
 python example-skills/skills-main/skill-creator/scripts/init_skill.py <skill-name> --path custom-skills/
 ```
 
+New skills must include a root `SKILL.md` (the hybrid pattern above); model them on
+`16-seo-schema-validator` / `17-seo-schema-generator`.
+
 ## Key Reference Files
 
-- `reference/SKILL-FORMAT-REQUIREMENTS.md` - Format specification
+- `reference/SKILL-MIGRATION-GUIDE.md` - Add a root `SKILL.md` to an existing skill (hybrid pattern, going-forward standard)
+- `reference/SKILL-FORMAT-REQUIREMENTS.md` - Dual-platform format specification
 - `example-skills/skills-main/skill-creator/SKILL.md` - Skill creation guide
 - `AGENTS.md` - Agent routing guide for Task tool