From 01201ee4a2cb1502d7b1687150937a25c6dd003d Mon Sep 17 00:00:00 2001 From: Andrew Yim Date: Thu, 28 May 2026 00:50:50 +0900 Subject: [PATCH] docs(skills): add SKILL-MIGRATION-GUIDE + adopt root-SKILL.md hybrid as standard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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) --- CLAUDE.md | 66 +++++++++++-------- reference/SKILL-FORMAT-REQUIREMENTS.md | 5 ++ reference/SKILL-MIGRATION-GUIDE.md | 87 ++++++++++++++++++++++++++ 3 files changed, 133 insertions(+), 25 deletions(-) create mode 100644 reference/SKILL-MIGRATION-GUIDE.md diff --git a/CLAUDE.md b/CLAUDE.md index 4430f2b..74fcabd 100644 --- 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 --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 diff --git a/reference/SKILL-FORMAT-REQUIREMENTS.md b/reference/SKILL-FORMAT-REQUIREMENTS.md index 154aedb..392419d 100644 --- 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. diff --git a/reference/SKILL-MIGRATION-GUIDE.md b/reference/SKILL-MIGRATION-GUIDE.md new file mode 100644 index 0000000..beeaea3 --- /dev/null +++ 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`.