From 30dae15001a8f3b30bfbae398f8d457f47fab2e9 Mon Sep 17 00:00:00 2001
From: Christopher Addison <christophera@unity3d.com>
Date: Thu, 29 Oct 2026 11:46:04 -0400
Subject: [PATCH 1/2] docs: give the root README a full overview and gate the
 directory scan checks

The Claude Code plugin directory scan wants a root README.md of at least 40
words and no angle brackets in skill descriptions. The root README was an
18-word stub, kept short on purpose because Antigravity shows it as the
marketplace overview. It now describes what the skills cover in about 90
words and links to the full README in .github/, which still holds the
install steps.

check-skill-frontmatter.mjs now fails on angle brackets in a description and
on a root README under 40 words, and the skills workflow runs when README.md
changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/validate-skills.yml |  2 ++
 README.md                             |  8 ++++++++
 scripts/check-skill-frontmatter.mjs   | 19 ++++++++++++++++++-
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/validate-skills.yml b/.github/workflows/validate-skills.yml
index d5dad1c..4f7a988 100644
--- a/.github/workflows/validate-skills.yml
+++ b/.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:
diff --git a/README.md b/README.md
index b8b30ff..cb5fb77 100644
--- a/README.md
+++ b/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.
+
+Works with Claude Code, Codex, Grok and Antigravity. Install steps and usage are in the
+[full README](https://github.com/Unity-Technologies/unity-agent-plugin#readme).
diff --git a/scripts/check-skill-frontmatter.mjs b/scripts/check-skill-frontmatter.mjs
index e30dcba..883892c 100644
--- a/scripts/check-skill-frontmatter.mjs
+++ b/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`);

From 62a422d2f694de2de0b1b7f7fc5af91bec99a4b5 Mon Sep 17 00:00:00 2001
From: Christopher Addison <christophera@unity3d.com>
Date: Thu, 29 Oct 2026 12:17:33 -0400
Subject: [PATCH 2/2] docs: drop the supported-agents line from the root README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index cb5fb77..28336b7 100644
--- a/README.md
+++ b/README.md
@@ -7,5 +7,5 @@ building UI with UI Toolkit, uGUI or IMGUI, 2D sprites and tilemaps, physics, au
 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.
 
-Works with Claude Code, Codex, Grok and Antigravity. Install steps and usage are in the
+Install steps and usage are in the
 [full README](https://github.com/Unity-Technologies/unity-agent-plugin#readme).