diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..c21c0c3 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,17 @@ +{ + "name": "raea", + "owner": { + "name": "raea", + "url": "https://raea.io" + }, + "metadata": { + "description": "raea's plugin for Claude: the raea skill and its hooks, from the skills/ folder of this repository." + }, + "plugins": [ + { + "name": "raea", + "source": "./skills", + "description": "Make video, motion graphics, games and 3D scenes with raea, the Render Anything Engine: the raea skill, and hooks that run raea's quick check on a composition after it's saved and show media in the raea app instead of the Mac's viewer." + } + ] +} diff --git a/CLAUDE.md b/CLAUDE.md index 1f6245c..0677ae3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,6 +29,9 @@ programmer. Teach as you go, in plain words. ## Layout - `skills//SKILL.md` — the skills (`_template/` is skipped by checks) +- `skills/` is also raea's Claude plugin: `.claude-plugin/plugin.json` (its `skills` must list every skill), + `hooks/` (not a skill), `README.md` (what the plugin runs, shown in Claude's plugin directory) and `icon.png`. + `just plugin` runs Claude Code's validator on it. - `features/*.feature` — behaviour specs (Gherkin), run by `crates/skillcheck/tests/bdd.rs` - `crates/skillcheck/` — the Rust checker - `upstream/raea/` — generated by `just sync-raea`; never hand-edit diff --git a/README.md b/README.md index d85e69a..8aa805a 100644 --- a/README.md +++ b/README.md @@ -35,11 +35,19 @@ just ci # run every check | `just link` | install this repo's skills into Claude Code, live | | `just drift` | after a raea update: re-snapshot, list stale skills | | `just word cut` | check a term with montology before using it | +| `just plugin` | check the Claude plugin (`skills/`) with Claude Code's own validator | + +## Use it as a Claude plugin + +`skills/` is raea's plugin for Claude: the skills its manifest lists, plus hooks that run raea's quick check +after a composition is saved and send media to `raea show`. Install it in Claude Code with +`/plugin install raea --marketplace shinyobjectz/raea-skills`; [skills/README.md](skills/README.md) says what it runs. +A new skill goes in `skills/.claude-plugin/plugin.json`'s `skills` too, or `just check` fails. ## Layout ``` -skills/ one folder per skill (SKILL.md) +skills/ one folder per skill (SKILL.md); the folder is also raea's Claude plugin features/ behaviour specs in Gherkin (Given / When / Then) crates/ skillcheck — the Rust checker and test runner upstream/raea/ snapshot of the raea these skills are checked against diff --git a/crates/skillcheck/src/lib.rs b/crates/skillcheck/src/lib.rs index b06dc96..facd946 100644 --- a/crates/skillcheck/src/lib.rs +++ b/crates/skillcheck/src/lib.rs @@ -311,13 +311,15 @@ pub fn check_skill(dir: &Path, upstream: Option<&Upstream>) -> Vec { out } -/// Checks every skill under `skills_dir` (folders starting with `_` or `.` are skipped). +/// Checks every skill under `skills_dir` (folders starting with `_` or `.` are skipped, and so are the plugin's own +/// folders when `skills_dir` is a Claude plugin), then the plugin's manifest. pub fn check_repo(skills_dir: &Path, upstream_dir: &Path) -> Result { let upstream = Upstream::load(upstream_dir)?; let mut report = Report::default(); if !skills_dir.exists() { return Ok(report); } + let plugin = skills_dir.join(PLUGIN_MANIFEST).is_file(); let mut dirs: Vec<_> = fs::read_dir(skills_dir) .with_context(|| format!("reading {}", skills_dir.display()))? .filter_map(|e| e.ok()) @@ -325,17 +327,91 @@ pub fn check_repo(skills_dir: &Path, upstream_dir: &Path) -> Result { .filter(|p| p.is_dir()) .filter(|p| { let n = p.file_name().unwrap_or_default().to_string_lossy(); - !n.starts_with('_') && !n.starts_with('.') + !n.starts_with('_') + && !n.starts_with('.') + && !(plugin && PLUGIN_DIRS.contains(&n.as_ref())) }) .collect(); dirs.sort(); + let mut names = Vec::new(); for dir in dirs { report.skills_checked += 1; report.findings.extend(check_skill(&dir, upstream.as_ref())); + names.push( + dir.file_name() + .unwrap_or_default() + .to_string_lossy() + .to_string(), + ); + } + if plugin { + report.findings.extend(check_plugin(skills_dir, &names)); } Ok(report) } +/// The manifest that makes the skills folder a Claude plugin, relative to it. +pub const PLUGIN_MANIFEST: &str = ".claude-plugin/plugin.json"; +/// The plugin's own folders beside the skills, which aren't skills. +pub const PLUGIN_DIRS: &[&str] = &["hooks"]; + +/// Checks the plugin manifest: it parses, has a name, and its `skills` lists every skill folder and nothing else, so +/// no skill is left out of the plugin and no entry points at a skill that's gone. +pub fn check_plugin(skills_dir: &Path, skills: &[String]) -> Vec { + let mut out = Vec::new(); + let mut fail = |message: String| { + out.push(Finding { + level: Level::Error, + skill: "plugin".into(), + message, + }) + }; + let path = skills_dir.join(PLUGIN_MANIFEST); + let manifest: serde_yaml::Value = match fs::read_to_string(&path) + .map_err(|e| e.to_string()) + .and_then(|t| serde_yaml::from_str(&t).map_err(|e| e.to_string())) + { + Ok(v) => v, + Err(e) => { + fail(format!("{PLUGIN_MANIFEST} doesn't parse: {e}")); + return out; + } + }; + if manifest + .get("name") + .and_then(|n| n.as_str()) + .is_none_or(str::is_empty) + { + fail(format!("{PLUGIN_MANIFEST} has no `name`")); + } + let listed: Vec<&str> = match manifest.get("skills") { + Some(serde_yaml::Value::String(s)) => vec![s.as_str()], + Some(serde_yaml::Value::Sequence(v)) => v.iter().filter_map(|s| s.as_str()).collect(), + _ => Vec::new(), + }; + let folder = |entry: &str| { + entry + .trim_start_matches("./") + .trim_end_matches('/') + .to_string() + }; + for name in skills { + if !listed.iter().any(|e| folder(e) == *name) { + fail(format!( + "skills/{name} isn't in the plugin's skills ({PLUGIN_MANIFEST}): add \"./{name}\", or the plugin ships without it" + )); + } + } + for entry in listed { + if !skills_dir.join(folder(entry)).join("SKILL.md").is_file() { + fail(format!( + "the plugin's skills list {entry:?}, which holds no SKILL.md" + )); + } + } + out +} + #[cfg(test)] mod tests { use super::*; diff --git a/crates/skillcheck/tests/bdd.rs b/crates/skillcheck/tests/bdd.rs index dfb0dfc..5461f50 100644 --- a/crates/skillcheck/tests/bdd.rs +++ b/crates/skillcheck/tests/bdd.rs @@ -58,6 +58,23 @@ fn empty_folder(lib: &mut Library, name: String) { fs::create_dir_all(lib.root().join("skills").join(name)).unwrap(); } +#[given(expr = "the plugin manifest lists the skills {string}")] +fn plugin_lists(lib: &mut Library, entries: String) { + let list: Vec = entries + .split_whitespace() + .map(|e| format!("{e:?}")) + .collect(); + let manifest = format!("{{\"name\": \"raea\", \"skills\": [{}]}}", list.join(", ")); + plugin_manifest(lib, manifest); +} + +#[given(expr = "the plugin manifest is {string}")] +fn plugin_manifest(lib: &mut Library, text: String) { + let dir = lib.root().join("skills/.claude-plugin"); + fs::create_dir_all(&dir).unwrap(); + fs::write(dir.join("plugin.json"), text).unwrap(); +} + #[when("I run the skill check")] fn run_check(lib: &mut Library) { let root = lib.root(); diff --git a/docs/HOW-SKILLS-WORK.md b/docs/HOW-SKILLS-WORK.md index bccb490..2187059 100644 --- a/docs/HOW-SKILLS-WORK.md +++ b/docs/HOW-SKILLS-WORK.md @@ -39,6 +39,10 @@ This is called *progressive disclosure*: small label, bigger body, deepest detai | `/.claude/skills/` | Anyone working in that project | | A plugin (like i-have-adhd) | Whoever installs the plugin | +This repo's `skills/` folder is itself a plugin, `raea`, listed in Claude's plugin +directory: whoever installs it gets the skills its manifest +(`skills/.claude-plugin/plugin.json`) lists, plus raea's hooks. + `just link` puts this repo's skills into `~/.claude/skills/` as links, so your edits apply the next session — no copying. diff --git a/features/plugin.feature b/features/plugin.feature new file mode 100644 index 0000000..38df8e2 --- /dev/null +++ b/features/plugin.feature @@ -0,0 +1,74 @@ +Feature: The skills folder is a Claude plugin + skills/ is also raea's plugin for Claude: skills/.claude-plugin/plugin.json names it, and Claude Code, Cowork and + claude.ai load the skills its `skills` lists. A skill the manifest leaves out never reaches the plugin's users, so + every skill folder must be listed, and every entry must be a skill. The plugin's own folders (hooks/) aren't skills. + + Background: + Given raea "0.1.0-canary.3" is the current upstream snapshot + + Scenario: Every skill listed passes + Given a skill folder "cut-by-words" with this SKILL.md: + """ + --- + name: cut-by-words + description: Cut talking-head footage at the words a person chooses, with raea cut. + metadata: + raea-tested-against: 0.1.0-canary.3 + --- + # Cut by words + """ + And the plugin manifest lists the skills "./cut-by-words" + When I run the skill check + Then it passes with no warnings + + Scenario: A skill the manifest leaves out fails + Given a skill folder "cut-by-words" with this SKILL.md: + """ + --- + name: cut-by-words + description: Cut talking-head footage at the words a person chooses, with raea cut. + metadata: + raea-tested-against: 0.1.0-canary.3 + --- + """ + And a skill folder "captions" with this SKILL.md: + """ + --- + name: captions + description: Put captions on a cut from its words, with raea. + metadata: + raea-tested-against: 0.1.0-canary.3 + --- + """ + And the plugin manifest lists the skills "./cut-by-words" + When I run the skill check + Then it fails + And an error mentions "skills/captions isn't in the plugin's skills" + + Scenario: A manifest entry with no skill fails + Given a skill folder "cut-by-words" with this SKILL.md: + """ + --- + name: cut-by-words + description: Cut talking-head footage at the words a person chooses, with raea cut. + metadata: + raea-tested-against: 0.1.0-canary.3 + --- + """ + And the plugin manifest lists the skills "./cut-by-words ./gone" + When I run the skill check + Then it fails + And an error mentions "holds no SKILL.md" + + Scenario: The plugin's hooks folder is not a skill + Given an empty skill folder "hooks" + And the plugin manifest lists the skills "" + When I run the skill check + Then it passes + And 0 skills were checked + + Scenario: A manifest that doesn't parse fails + Given the plugin manifest is "{ not json" + When I run the skill check + Then it fails + And an error mentions "doesn't parse" diff --git a/justfile b/justfile index b70a4eb..45efa00 100644 --- a/justfile +++ b/justfile @@ -68,6 +68,7 @@ link: mkdir -p ~/.claude/skills for d in skills/*/; do n="$(basename "$d")"; [[ "$n" == _* ]] && continue + [ -f "skills/$n/SKILL.md" ] || continue # the plugin's hooks/ isn't a skill ln -sfn "$PWD/skills/$n" ~/.claude/skills/"$n" echo "linked $n" done @@ -80,6 +81,17 @@ unlink: [ -L ~/.claude/skills/"$n" ] && rm ~/.claude/skills/"$n" && echo "unlinked $n" done; true +# ── The Claude plugin ────────────────────────────────── + +# Check the plugin (skills/) and its marketplace with Claude Code's own validator +plugin: + claude plugin validate skills + claude plugin validate . + +# Try the plugin in one Claude Code session, without installing it +plugin-try: + claude --plugin-dir skills + # ── Tracking raea ────────────────────────────────────── # Snapshot the installed raea into upstream/raea/ (run after every raea update) diff --git a/skills/.claude-plugin/plugin.json b/skills/.claude-plugin/plugin.json new file mode 100644 index 0000000..4d307c7 --- /dev/null +++ b/skills/.claude-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "raea", + "displayName": "raea", + "description": "Make video, motion graphics, games and 3D scenes with raea, the Render Anything Engine: the raea skill, and hooks that run raea's quick check on a composition after it's saved and show media in the raea app instead of the Mac's viewer.", + "author": { + "name": "raea", + "url": "https://raea.io" + }, + "homepage": "https://raea.io", + "repository": "https://github.com/shinyobjectz/raea-skills", + "license": "Apache-2.0", + "keywords": ["video", "motion-graphics", "3d", "games", "rendering", "bevy", "react", "typescript"], + "icon": "./icon.png", + "documentationUrl": "https://raea.io/docs/", + "supportUrl": "https://github.com/shinyobjectz/raea-skills/issues", + "privacyPolicyUrl": "https://raea.io/privacy/", + "termsOfServiceUrl": "https://raea.io/terms/", + "skills": ["./raea"] +} diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..b62bbf6 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,69 @@ +# raea for Claude + +raea is the Render Anything Engine. You write a video, a motion graphic, a game or a 3D scene as React and TypeScript, +and raea renders it on your computer's GPU with an engine built on Bevy. The same file renders to video, plays live as +a game, or renders single frames to check. This plugin teaches Claude to use raea well and connects Claude Code to it. + +## What's in it + +- **The raea skill** (`raea/`). It covers how to install raea, write a composition, render and check it, and what each + kind of work needs: footage cut by its words, motion graphics and type, sound and music, 3D scenes (Bevy materials, + lights, physics, Gaussian splats), games, app interfaces, generated media, and delivery. Its `reference/` files are + generated from raea's code, so they list the real verbs, flags and SDK imports. +- **Two hooks** (`hooks/`), for Claude Code and Cowork. Before Claude runs a shell command, a command that opens a + still, a video or a sound in the Mac's viewer is stopped once and Claude is told to use `raea show`, which puts it in + the raea app where you can answer it; the same command again goes through. This happens only while the raea app is + installed. After Claude saves a composition (a `.tsx` file that calls `registerRoot`), `raea check --quick` runs on + it and Claude gets what it finds. + +## Install the plugin + +Add it from the plugin directory: **Customize > Plugins** on claude.ai, or `/plugin directory` in Claude Code. Or install +it straight from this repository in Claude Code (2.1.275 or later): + +``` +/plugin install raea --marketplace shinyobjectz/raea-skills +``` + +## Install raea + +The plugin uses the `raea` command, which you install yourself: + +- macOS (Apple Silicon) or Linux (x86_64): `curl -fsSL https://raea.io/install | sh` +- Windows 10 or 11, in PowerShell: `irm https://raea.io/install.ps1 | iex` + +Until `raea` is on your PATH the hooks do nothing, and the skill tells Claude how to install it when you ask for +something that needs it. raea's installer also copies the skill into `~/.claude/skills`; with the plugin you can set +`RAEA_NO_SKILLS=1` when you install raea to skip that copy. + +If you already ran `raea skills install --agent claude`, the same two hooks are in `~/.claude/settings.json`, and the +plugin's hook script steps aside so they never run twice. + +## Where it works + +| | Skill | Hooks | +|---|---|---| +| Claude Code | yes | yes | +| Cowork | yes | yes, when raea is installed where the session runs | +| Chat on claude.ai | yes | no (chat doesn't run hooks) | + +Rendering needs raea on a computer, so in chat the skill can explain and write compositions but can't render them. + +## What it runs and sends + +The plugin itself sends nothing anywhere and stores nothing. Its hook script (`hooks/raea-hook.sh`) runs +`raea hook claude` on your computer, which reads the tool call Claude Code hands it, may run raea's quick check on the +saved file, and keeps a small marker under `~/.raea/hooks` so a command it stopped goes through when tried again. It +reads `~/.claude/settings.json` only to see whether raea's hooks are already there. + +The skill tells Claude to run the `raea` command, which works on your computer. A few of raea's verbs reach the +network when you ask for them: the installer downloads raea from raea.io, `raea gen` calls the generation providers you +set up with your own keys (and spends your money there, so the skill has Claude quote the cost first), and a review +link made in the raea app uploads the cut you choose to share. raea's privacy policy is at https://raea.io/privacy/. + +## Source and license + +This folder is the `skills/` folder of +[shinyobjectz/raea-skills](https://github.com/shinyobjectz/raea-skills), where the skill is written and checked. +Apache-2.0; the copied guides keep their notices (`raea/3d/NOTICE`, `raea/craft/NOTICE`). Questions and bugs: +[issues](https://github.com/shinyobjectz/raea-skills/issues). diff --git a/skills/hooks/hooks.json b/skills/hooks/hooks.json new file mode 100644 index 0000000..7803ac6 --- /dev/null +++ b/skills/hooks/hooks.json @@ -0,0 +1,28 @@ +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/raea-hook.sh", + "timeout": 30 + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Write|Edit|MultiEdit", + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/raea-hook.sh", + "timeout": 60 + } + ] + } + ] + } +} diff --git a/skills/hooks/raea-hook.sh b/skills/hooks/raea-hook.sh new file mode 100755 index 0000000..9534a53 --- /dev/null +++ b/skills/hooks/raea-hook.sh @@ -0,0 +1,10 @@ +#!/bin/sh +# The raea plugin's hooks. Claude Code hands this script the tool call on stdin, before a Bash command and after a +# file is saved, and `raea hook claude` answers it: media opened in the Mac's viewer is pointed at `raea show` once, +# and a saved composition gets raea's quick check, run locally. +# +# It does nothing when raea isn't installed, and nothing when `raea skills install` has already put the same hooks +# in ~/.claude/settings.json, so they never run twice. +command -v raea >/dev/null 2>&1 || exit 0 +grep -qs 'raea hook' ~/.claude/settings.json && exit 0 +exec raea hook claude diff --git a/skills/icon.png b/skills/icon.png new file mode 100644 index 0000000..c7ccbff Binary files /dev/null and b/skills/icon.png differ