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>
2026-05-28 00:50:50 +09:00
parent 1e3b2a4fa0
commit 01201ee4a2
3 changed files with 133 additions and 25 deletions
--- a/CLAUDE.md
+++ b/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
--- a/reference/SKILL-FORMAT-REQUIREMENTS.md
+++ b/reference/SKILL-FORMAT-REQUIREMENTS.md
@@ -1,5 +1,10 @@
 # Claude Skills - Format Requirements

+> **Going-forward standard:** each skill also gets a **root `SKILL.md`** (official Agent
+> Skills format, natively loadable) alongside the `code/` + `desktop/` packaging described
+> below. To add one to an existing skill, see `SKILL-MIGRATION-GUIDE.md`. This document
+> remains the spec for the dual-platform packaging layers.
+
 ## Overview

 This document describes the format requirements for Claude Skills in this repository. Skills support dual-platform development (Claude Code and Claude Desktop) with separated concerns.
--- a/reference/SKILL-MIGRATION-GUIDE.md
+++ b/reference/SKILL-MIGRATION-GUIDE.md
@@ -0,0 +1,87 @@
+# Skill Migration Guide — add a root `SKILL.md` (hybrid pattern)
+
+One page. How to make an existing dual-platform skill **natively loadable** as an Agent
+Skill without rewriting it. Reference implementations: `custom-skills/16-seo-schema-validator`
+and `custom-skills/17-seo-schema-generator`.
+
+## Why
+
+Claude Code / Desktop / API natively load the **Agent Skills format**: a directory whose
+**root** holds a `SKILL.md` (YAML frontmatter + body) plus optional bundled resources. Our
+older skills keep the directive in `desktop/SKILL.md` and `code/CLAUDE.md` — not at the
+root — so they aren't directly loadable. The fix is **additive**: promote a `SKILL.md` to
+the root. Keep `code/` and `desktop/` as-is. **No rewrite, no logic change.**
+
+## Target (hybrid) structure
+
+```
+XX-skill-name/
+├── SKILL.md            # ← NEW: root directive, official format (loadable)
+├── scripts/            # ← runnable scripts (single source of truth)
+├── references/         # ← heavy docs, loaded on demand
+├── templates/          # ← optional
+├── fixtures/           # ← optional (sample/test inputs)
+├── code/               # KEPT — code/CLAUDE.md redirects to ../SKILL.md + ../scripts
+└── desktop/            # KEPT — desktop/SKILL.md + skill.yaml + tools/
+```
+
+Scripts live **once** at the root `scripts/`; `code/CLAUDE.md` points to `../scripts/`
+(don't duplicate). Don't move existing scripts that other skills already reference.
+
+## Recipe (≈10 min/skill)
+
+1. **Copy** `desktop/SKILL.md` → root `SKILL.md`. (It's already frontmatter + body — the
+   right shape; it was just in the wrong place.)
+2. **Fix the frontmatter** against the checklist below.
+3. **Promote resources** to root siblings: if real scripts/docs live under `code/`, move
+   the canonical copy to root `scripts/` + `references/`; reference them from `SKILL.md`
+   with **relative paths** (`scripts/foo.py`, `references/bar.md`).
+4. **Redirect `code/CLAUDE.md`** to a short pointer: "canonical = `../SKILL.md`; scripts =
+   `../scripts/`" (see 16/17 `code/CLAUDE.md`).
+5. **Leave `desktop/`** intact (SKILL.md, skill.yaml, tools/). It stays the Desktop view.
+6. **Verify** (below). Commit.
+
+## Frontmatter checklist (the only hard requirement)
+
+```yaml
+---
+name: skill-name-kebab-case        # letters, numbers, hyphens ONLY
+description: |                     # third person; START with "Use when…" / what+when
+  What it does in one line. Triggers: kw1, kw2, 한국어 트리거.
+---
+```
+
+- [ ] `name`: kebab-case, no spaces/parens/special chars. (May keep the `NN-` prefix.)
+- [ ] `description`: third-person; says **when to use** + trigger keywords (EN + KO).
+- [ ] **Whole frontmatter ≤ 1024 characters.**
+- [ ] Body: concise markdown (aim < 500 words of always-on content); push detail into
+      `references/` and link it — don't `@`-include (that force-loads and burns context).
+- [ ] Optional fields allowed: `version`, `author`, `license`, `allowed-tools`, `metadata`.
+
+## Verify before committing
+
+```bash
+# frontmatter present + size sane
+head -20 custom-skills/XX-skill/SKILL.md
+python3 - <<'PY'
+import re,sys,pathlib
+t=pathlib.Path("custom-skills/XX-skill/SKILL.md").read_text()
+m=re.match(r'^---\n(.*?)\n---',t,re.S); assert m,"no frontmatter"
+fm=m.group(1); assert len(fm)<=1024,f"frontmatter {len(fm)} >1024"
+assert re.search(r'^name:\s*[a-z0-9-]+\s*$',fm,re.M),"name must be kebab-case"
+assert 'description:' in fm,"description required"
+print("OK: frontmatter valid")
+PY
+# every relative path referenced in SKILL.md must exist
+grep -oE '`(scripts|references|templates|fixtures)/[^`]+`' custom-skills/XX-skill/SKILL.md
+# if the skill has scripts, run its bundled sample/fixture end to end
+```
+
+## Adopt going forward
+
+- **New skills:** create a root `SKILL.md` from day one (the hybrid above). `code/` +
+  `desktop/` remain optional packaging, not the primary directive.
+- **Existing skills:** migrate **incrementally** — when you next touch a skill, apply the
+  recipe. A bulk migration of all skills isn't worth the churn unless you specifically
+  need them all loadable at once.
+- When in doubt, copy the shape of `16-seo-schema-validator` / `17-seo-schema-generator`.