Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
27 changes: 17 additions & 10 deletions .github/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ For Visual Studio, see [Manual install](#manual-install).

Each agent surfaces an installed plugin differently.

**Claude Code** — type `/unity:` and the skills appear in the command list. `/plugin`
**Claude Code** — type `/unity:` and `/unity:using-unity` appears in the command list. `/plugin`
also shows `unity` as installed and enabled.

**Codex** — run `codex plugin list`:
Expand All @@ -81,8 +81,8 @@ PLUGIN STATUS VERSION
unity@unity-agent-plugin installed, enabled 0.1.9-beta
```

**Grok**: type `/` and the skills appear in the slash menu. Grok uses the plain skill
name, and switches to the plugin-qualified form (`/unity:ui-uitk`) when another
**Grok**: type `/` and `using-unity` appears in the slash menu. Grok uses the plain skill
name, and switches to the plugin-qualified form (`/unity:using-unity`) when another
installed skill shares the same name. `grok plugin list` shows `unity`, and
`grok plugin details unity` lists what it provides.

Expand All @@ -99,11 +99,11 @@ Installed plugins:
• unity@unity-agent-plugin (v0.1.9-beta)
```

`copilot skill list` lists the Unity skills under "Plugin skills".
`copilot skill list` lists `using-unity` under "Plugin skills".

### Manual install

If you can't use the marketplace commands, clone the repo and link each skill into your personal skills directory. Run this from the folder you want the clone in:
If you can't use the marketplace commands, clone the repo and link its skill into your personal skills directory. Run this from the folder you want the clone in:

```bash
git clone https://github.com/Unity-Technologies/unity-agent-plugin.git
Expand Down Expand Up @@ -135,8 +135,8 @@ for d in "$PWD"/skills/*; do ln -sfn "$d" ~/.copilot/skills/"$(basename "$d")";
```

Copilot also reads `~/.claude/skills` and `~/.agents/skills`, so skip this if you
already linked the skills for Claude Code or Codex. On Windows, copy each skill folder
into `%USERPROFILE%\.copilot\skills` instead.
already linked the skill for Claude Code or Codex. On Windows, copy the `skills/using-unity`
folder into `%USERPROFILE%\.copilot\skills` instead.

The skills load in every project from your next session onward. To update them, run `git pull` in the clone. Skills installed this way don't appear under a `unity:` prefix, because they aren't installed as a plugin.

Expand All @@ -161,12 +161,19 @@ do something in your Unity project. For example:
>
> "Review my ScriptableRendererFeature for Render Graph problems"

In Claude Code, Grok and Antigravity the skills also appear in the slash menu, so you can pick one
explicitly instead of describing the task.
The plugin installs one skill, `using-unity`, which lists every Unity skill with what it's for.
Your agent reads that list, picks the skill that fits your request, and follows it. In the slash
menu of Claude Code, Grok and Antigravity it appears as `/unity:using-unity`; the individual
skills don't have their own slash commands.

To pick individual skills from the slash menu instead, install them one by one from
[Unity-Technologies/skills](https://github.com/Unity-Technologies/skills) with
`npx skills add Unity-Technologies/skills`. If you install both, your agent can reach each
skill twice.

For what each skill covers and how to prompt it, see
[About Unity's plugin](https://docs.unity.com/en-us/ai/unity-plugin/about-unity-plugin),
or browse the [skills folder](../skills/).
or browse the [skills](../skills/using-unity/references/).

## Works best with the Unity CLI

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ Unity's official plugin for coding agents, with curated skills for game developm

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.
post-processing, Shader Graph, multiplayer services, Vivox voice chat, in-app purchases and LevelPlay ads. The plugin
installs one skill, `using-unity`, which lists them all; the agent reads only the skill your request needs.

Install steps and usage are in the
[full README](https://github.com/Unity-Technologies/unity-agent-plugin#readme).
79 changes: 66 additions & 13 deletions scripts/check-skill-frontmatter.mjs
Original file line number Diff line number Diff line change
@@ -1,8 +1,16 @@
#!/usr/bin/env node
// Fails when any skills/*/SKILL.md has frontmatter that a strict YAML parser rejects,
// 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.
// Fails when a skill's frontmatter is something a strict YAML parser rejects, or 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.
//
// The plugin ships the index shape: `skills/` holds one skill, `using-unity`, whose
// SKILL.md lists every skill, and each skill is `skills/using-unity/references/<name>/<name>.md`
// (renamed from SKILL.md so agents don't register it on its own). The publish job in
// unity/skills writes that layout. When `skills/using-unity` exists this checks it: the
// index skill's own frontmatter, each skill's file, that `skills/` holds nothing else, and
// that the index lists exactly the skills in `references/`, each with its file. Without it,
// every `skills/<name>/SKILL.md` is checked, as in the flat layout the plugin used before.
//
// 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.
Expand All @@ -12,46 +20,91 @@ import { join } from 'node:path';
import yaml from 'js-yaml';

const root = process.argv[2] ?? 'skills';
const indexSkill = 'using-unity';
const readme = 'README.md';
const minReadmeWords = 40;
let checked = 0;
const failures = [];

for (const dir of readdirSync(root, { withFileTypes: true })) {
if (!dir.isDirectory()) continue;
const path = join(root, dir.name, 'SKILL.md');
const dirs = (path) =>
readdirSync(path, { withFileTypes: true })
.filter((entry) => entry.isDirectory())
.map((entry) => entry.name)
.sort();

/** Checks one skill file's frontmatter; returns its text, or undefined if it's missing. */
function checkSkillFile(path, name) {
if (!existsSync(path)) {
failures.push(`${path}: missing`);
continue;
return undefined;
}
const text = readFileSync(path, 'utf8');
const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
if (!match) {
failures.push(`${path}: no YAML frontmatter block`);
continue;
return text;
}
let data;
try {
data = yaml.load(match[1]);
} catch (error) {
failures.push(`${path}: frontmatter is not valid YAML: ${error.message.split('\n')[0]}`);
continue;
return text;
}
if (typeof data !== 'object' || data === null) {
failures.push(`${path}: frontmatter is not a mapping`);
continue;
return text;
}
if (typeof data.name !== 'string' || data.name.trim() === '') {
failures.push(`${path}: missing or empty name`);
} else if (data.name !== dir.name) {
failures.push(`${path}: name "${data.name}" does not match folder "${dir.name}"`);
} else if (data.name !== name) {
failures.push(`${path}: name "${data.name}" does not match folder "${name}"`);
}
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;
return text;
}

if (existsSync(join(root, indexSkill))) {
for (const name of dirs(root).filter((name) => name !== indexSkill)) {
failures.push(`${join(root, name)}: only ${indexSkill} belongs in ${root}/; this folder loads as a separate skill`);
}
const indexPath = join(root, indexSkill, 'SKILL.md');
const index = checkSkillFile(indexPath, indexSkill) ?? '';
const referencesDir = join(root, indexSkill, 'references');
const skills = existsSync(referencesDir) ? dirs(referencesDir) : [];
if (skills.length === 0) {
failures.push(`${referencesDir}: no skills`);
}
for (const name of skills) {
checkSkillFile(join(referencesDir, name, `${name}.md`), name);
}
// Index lines: "- **<name>**: <description> File: `references/<name>/<name>.md`".
const listed = new Map();
for (const line of index.split(/\r?\n/)) {
const entry = line.match(/^- \*\*([^*]+)\*\*: .* File: `([^`]+)`$/);
if (entry) listed.set(entry[1], entry[2]);
}
for (const name of skills) {
if (!listed.has(name)) {
failures.push(`${indexPath}: doesn't list ${name}, so agents can't reach it`);
} else if (listed.get(name) !== `references/${name}/${name}.md`) {
failures.push(`${indexPath}: lists ${name} with file ${listed.get(name)}, expected references/${name}/${name}.md`);
}
}
for (const name of listed.keys()) {
if (!skills.includes(name)) {
failures.push(`${indexPath}: lists ${name}, which isn't in ${referencesDir}`);
}
}
} else {
for (const name of dirs(root)) {
checkSkillFile(join(root, name, 'SKILL.md'), name);
}
}

if (!existsSync(readme)) {
Expand Down
Loading
Loading