Skip to content
Merged
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
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -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."
}
]
}
3 changes: 3 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@ programmer. Teach as you go, in plain words.
## Layout

- `skills/<name>/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
Expand Down
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
80 changes: 78 additions & 2 deletions crates/skillcheck/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -311,31 +311,107 @@ pub fn check_skill(dir: &Path, upstream: Option<&Upstream>) -> Vec<Finding> {
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<Report> {
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())
.map(|e| e.path())
.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<Finding> {
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::*;
Expand Down
17 changes: 17 additions & 0 deletions crates/skillcheck/tests/bdd.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> = 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();
Expand Down
4 changes: 4 additions & 0 deletions docs/HOW-SKILLS-WORK.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ This is called *progressive disclosure*: small label, bigger body, deepest detai
| `<project>/.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.

Expand Down
74 changes: 74 additions & 0 deletions features/plugin.feature
Original file line number Diff line number Diff line change
@@ -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"
12 changes: 12 additions & 0 deletions justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
Expand Down
19 changes: 19 additions & 0 deletions skills/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"]
}
69 changes: 69 additions & 0 deletions skills/README.md
Original file line number Diff line number Diff line change
@@ -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).
Loading
Loading