docs: give the root README a full overview and gate the directory scan checks

.github/workflows/validate-skills.yml

@@ -4,12 +4,14 @@ on:
   pull_request:
     paths:
       - 'skills/**'
+      - 'README.md'
       - 'scripts/check-skill-frontmatter.mjs'
       - '.github/workflows/validate-skills.yml'
   push:
     branches: [main]
     paths:
       - 'skills/**'
+      - 'README.md'
 
 jobs:
   frontmatter:

README.md

@@ -1,3 +1,11 @@
 # Unity
 
 Unity's official plugin for coding agents, with curated skills for game development, monetization, and performance optimization.
+
+The skills give your agent Unity's documented practices for everyday work: starting a project, managing packages,
+building UI with UI Toolkit, uGUI or IMGUI, 2D sprites and tilemaps, physics, audio, localization, URP rendering and
+post-processing, Shader Graph, multiplayer services, Vivox voice chat, in-app purchases and LevelPlay ads. The agent loads
+a skill only when your request needs it.
+
+Install steps and usage are in the
+[full README](https://github.com/Unity-Technologies/unity-agent-plugin#readme).

scripts/check-skill-frontmatter.mjs

@@ -3,11 +3,17 @@
 // or that lacks a non-empty `name` matching its folder or a non-empty `description`.
 // Agents parse the frontmatter with a real YAML parser and silently drop a skill that
 // fails, so this is the only place the defect becomes visible.
+//
+// Also enforces two checks from the Claude Code plugin directory's scan: no angle brackets
+// (like `<genre>`) in a skill description, and a root README.md of at least 40 words.
+// A failed scan holds the release back, and the scan reports it only after submission.
 import { readdirSync, readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import yaml from 'js-yaml';
 
 const root = process.argv[2] ?? 'skills';
+const readme = 'README.md';
+const minReadmeWords = 40;
 let checked = 0;
 const failures = [];
 
@@ -42,13 +48,24 @@ for (const dir of readdirSync(root, { withFileTypes: true })) {
   }
   if (typeof data.description !== 'string' || data.description.trim() === '') {
     failures.push(`${path}: missing or empty description`);
+  } else if (/[<>]/.test(data.description)) {
+    failures.push(`${path}: description contains angle brackets; reword or use a plain placeholder`);
   }
   checked += 1;
 }
 
+if (!existsSync(readme)) {
+  failures.push(`${readme}: missing at the repo root`);
+} else {
+  const words = readFileSync(readme, 'utf8').split(/\s+/).filter((w) => /\p{L}/u.test(w)).length;
+  if (words < minReadmeWords) {
+    failures.push(`${readme}: ${words} words, the plugin directory needs at least ${minReadmeWords}`);
+  }
+}
+
 if (failures.length > 0) {
   console.error(`${failures.length} problem(s) in ${checked} skill(s):`);
   for (const failure of failures) console.error(`  ${failure}`);
   process.exit(1);
 }
-console.log(`${checked} skills: frontmatter OK`);
+console.log(`${checked} skills: frontmatter OK; ${readme} OK`);