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
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,6 @@
"homepage": "https://raea.io",
"repository": "https://github.com/shinyobjectz/raea",
"license": "FSL-1.1-ALv2",
"skills": ["./sdk/skills/"],
"skills": ["./skills/skills/raea"],
"keywords": ["video", "motion-graphics", "game-development", "rendering", "bevy", "react", "agent-skills"]
}
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,9 +94,9 @@ floor (`raea check hello.mp4`). `raea init` starts a project, and `raea --help`

## Use it from your agent

- **Agent skills.** [`sdk/skills/raea`](sdk/skills/raea/SKILL.md) teaches an agent to write, render and check raea
compositions; [`sdk/skills/raea-bevy`](sdk/skills/raea-bevy) covers 3D and games. The installer adds both to
`~/.claude/skills`.
- **Agent skills.** They live in [raea-skills](https://github.com/shinyobjectz/raea-skills), pinned here as
[`skills/`](skills): `raea` teaches an agent to write, render and check raea compositions, 3D and games
included. The installer adds it to `~/.claude/skills`, and `raea skills install --agent NAME` to other agents.
- **Claude Code plugin.** `/plugin marketplace add shinyobjectz/raea`, then `/plugin install raea@raea`.
- **Craft guides.** `raea guide` prints the floor every edit is held to and the guides for pitches, explainers, stories,
games, motion, music and layout. `raea context PROJECT` says what to read before working on a project.
Expand Down
2 changes: 1 addition & 1 deletion docs/engine.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ second host beside Blitz, for native apps, video and layers in Bevy.

## Skills that stay true

The public agent skills (`raea`, `raea-bevy` and the craft guides) are generated from the code where they can be and
The public agent skill (`raea`, in raea-skills) and the craft guides are generated from the code where they can be and
checked against it where they can't, so they don't drift from the engine.

## Releases
Expand Down
9 changes: 5 additions & 4 deletions engine/cli/conformance/surface.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,12 @@ const listed = new Set([...help.matchAll(/raea ([a-z][\w-]*)/g), ...help.matchAl
const shellVerbs = JSON.parse(/const SHELL: &\[&str\] = &(\[[^\]]*\]);/.exec(readFileSync(join(raea, "engine/cli/src/verbs.rs"), "utf8"))![1]) as string[];
const handled = new Set([...cli.matchAll(/case "(\w+)":/g)].map((m) => m[1]).filter((c) => c !== "--help" && c !== "help"));

/** the hand-written text under dir: a skill's reference/ is the help itself, written by tools/skills.sh gen */
/** the hand-written text under dir: a skill's reference/ is the help itself, written by tools/skills.sh gen, and raea-skills'
* _template is a skill's placeholder text */
function files(dir: string, out: string[] = []): string[] {
for (const f of readdirSync(dir)) {
const p = join(dir, f);
if (lstatSync(p).isDirectory()) f !== "reference" && files(p, out);
if (lstatSync(p).isDirectory()) f !== "reference" && !f.startsWith("_") && files(p, out);
else if (f.endsWith(".md")) out.push(p);
}
return out;
Expand All @@ -79,7 +80,7 @@ describe("raea's surface", () => {
});

test.skipIf(missing || stale)("every `raea <command>` in the agent's context exists", () => {
const sources = [...files(join(raea, "sdk/guides")), ...files(join(raea, "sdk/skills")), "AGENTS.md (cli NOTES)"];
const sources = [...files(join(raea, "sdk/guides")), ...files(join(raea, "skills/skills")), ...(existsSync(join(raea, "sdk/skills")) ? files(join(raea, "sdk/skills")) : []), "AGENTS.md (cli NOTES)"];
const bad: string[] = [];
for (const src of sources) {
const text = src.startsWith("AGENTS.md") ? /const NOTES = `([\s\S]*?)`;/.exec(cli)![1] : readFileSync(src, "utf8");
Expand Down Expand Up @@ -107,7 +108,7 @@ describe("raea's surface", () => {
const host = join(raea, "apps/app/host");
const sources = [
...files(join(raea, "sdk/guides")),
...files(join(raea, "sdk/skills")),
...files(join(raea, "skills/skills")), ...(existsSync(join(raea, "sdk/skills")) ? files(join(raea, "sdk/skills")) : []),
// the feed's prompts (apps/app is a submodule: an export without it checks the rest)
...(existsSync(host) ? readdirSync(host) : []).filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts")).map((f) => join(host, f)),
"AGENTS.md (cli NOTES)",
Expand Down
23 changes: 10 additions & 13 deletions engine/cli/src/skill.rs
Original file line number Diff line number Diff line change
Expand Up @@ -41,10 +41,10 @@ pub fn version() -> String {
.unwrap_or_else(|| format!("{}-checkout", env!("CARGO_PKG_VERSION")))
}

/// The skills raea ships: an install's share/raea/skills, or the checkout's sdk/skills.
/// The skills raea ships: an install's share/raea/skills, or a checkout's skills/skills (the raea-skills submodule).
fn shipped() -> R<PathBuf> {
let home = raea_io_home::home();
["skills", "sdk/skills"].iter().map(|d| home.join(d)).find(|d| d.join("raea/SKILL.md").is_file()).ok_or_else(|| format!("no skills under {}: reinstall raea (curl -fsSL https://raea.io/install | sh)", home.display()))
["skills", "skills/skills"].iter().map(|d| home.join(d)).find(|d| d.join("raea/SKILL.md").is_file()).ok_or_else(|| format!("no skills under {}: reinstall raea (curl -fsSL https://raea.io/install | sh), or in a checkout, git submodule update --init skills", home.display()))
}

/// SKILL.md with `version: V` in its front matter (replacing one that's there), so a copy says which raea it came with.
Expand All @@ -65,7 +65,7 @@ pub fn skill(args: &[String]) -> R<String> {
}
let dir = shipped()?.join(name);
if !dir.join("SKILL.md").is_file() {
return Err(format!("no skill {name:?}: {}", installed_names()?.join(", ")));
return Err(format!("no skill {name:?}{}: {}", if name == "raea-bevy" { " (raea-bevy is the raea skill's 3D guide now: 3d.md beside its SKILL.md)" } else { "" }, installed_names()?.join(", ")));
}
match reference {
Some(r) => {
Expand All @@ -81,19 +81,14 @@ pub fn skill(args: &[String]) -> R<String> {
}

fn installed_names() -> R<Vec<String>> {
let mut v = Vec::new();
for e in std::fs::read_dir(shipped()?).map_err(|e| e.to_string())?.flatten() {
// raea-work is internal (work.raea.io's pages): a checkout has it, a release doesn't ship it
let name = e.file_name().to_string_lossy().into_owned();
if name != "raea-work" && e.path().join("SKILL.md").is_file() {
v.push(name);
}
}
// raea-work is internal (work.raea.io's pages); raea-skills' _template starts a skill and isn't one
let ok = |e: &std::fs::DirEntry, n: &str| n != "raea-work" && !n.starts_with('_') && e.path().join("SKILL.md").is_file();
let mut v: Vec<String> = std::fs::read_dir(shipped()?).map_err(|e| e.to_string())?.flatten().filter_map(|e| Some(e.file_name().to_string_lossy().into_owned()).filter(|n| ok(&e, n))).collect();
v.sort();
Ok(v)
}

/// Copies a folder, following links (raea-bevy's topic files link to the craft guides in a checkout).
/// Copies a folder, following links.
fn copy(from: &Path, to: &Path) -> R<()> {
std::fs::create_dir_all(to).map_err(|e| format!("{}: {e}", to.display()))?;
for e in std::fs::read_dir(from).map_err(|e| e.to_string())?.flatten() {
Expand Down Expand Up @@ -128,6 +123,8 @@ pub fn install(args: &[String]) -> R<String> {
std::fs::write(&md, stamp(&text, &v)).map_err(|e| e.to_string())?;
out += &format!("{}: {name} {v}\n", dst.display());
}
let old = to.join("raea-bevy"); // an older raea's copy (stamped `version:`), whose text is the raea skill's 3d.md now
if std::fs::read_to_string(old.join("SKILL.md")).is_ok_and(|t| t.contains("\nversion: ")) && std::fs::remove_dir_all(&old).is_ok() { out += &format!("{}: removed, now raea's 3d.md\n", old.display()); }
// pinned moves (SK10): a skill per move, so an agent's /quieter loads the one guide
for (i, a) in args.iter().enumerate() {
if a == "--pin" {
Expand Down Expand Up @@ -164,7 +161,7 @@ mod tests {
let core = skill(&[]).unwrap();
assert!(core.starts_with("---\nname: raea\n") && core.contains(&format!("\nversion: {}\n---\n", version())), "{}", &core[..200.min(core.len())]);
assert!(skill(&["--reference".into(), "cli".into()]).unwrap().contains("raea render"));
assert!(skill(&["raea-bevy".into()]).is_ok());
assert!(skill(&["raea-bevy".into()]).unwrap_err().contains("3d.md") && installed_names().unwrap() == ["raea"]);
assert!(skill(&["../x".into()]).is_err());
assert!(skill(&["--reference".into(), "../../x".into()]).is_err());
}
Expand Down
2 changes: 1 addition & 1 deletion engine/cli/src/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ fn the_skill_states_the_core_rules_as_motion_md_does() {
let core = motion.split("## The core rules").nth(1).unwrap().split("\n## ").next().unwrap();
let titles: Vec<&str> = core.lines().filter_map(|l| l.split_once(". **").filter(|(n, _)| n.trim().parse::<u32>().is_ok())).filter_map(|(_, t)| t.split_once("**").map(|(t, _)| t)).collect();
assert_eq!(titles.len(), 10, "{titles:?}");
let skill = include_str!("../../../sdk/skills/raea/SKILL.md");
let skill = &std::fs::read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/../../skills/skills/raea/SKILL.md")).expect("raea-skills: git submodule update --init skills");
let rules = skill.split("Rules that keep renders right").nth(1).unwrap().split("\n\n").next().unwrap();
assert!(rules.contains("`raea guide motion` has all ten"), "{rules}");
let mut bullets: Vec<String> = Vec::new();
Expand Down
2 changes: 1 addition & 1 deletion sdk/guides/craft/bevy/NOTICE
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
raea's Bevy skills library (sdk/guides/craft/bevy.md and bevy/*.md, mirrored in sdk/skills/raea-bevy/) is written for
raea's Bevy skills library (sdk/guides/craft/bevy.md and bevy/*.md, copied into the raea skill's 3D topic files in raea-skills (skills/skills/raea/3d/)) is written for
raea/3d. No text was copied from other packs. Its layout (a short router, one file per topic, each with a
checked example and a list of common mistakes) follows EnzeD/r3f-skills (no license stated; cited, not copied),
chrisgliddon/bevy-skills (MIT) and gamedev-skills' bevy-ecs (Apache-2.0). Bevy API facts come from Bevy's own v0.19.1
Expand Down
2 changes: 1 addition & 1 deletion sdk/guides/craft/bevy/prompts.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ Paste it as it is, with the brackets filled from the brief.

```text
You build one 3D scene in raea, the TSX/Bevy engine, from brief.ts, its plans and its reference pictures. The scene
lives in EDIT.tsx and is frame-pure. Read the raea-bevy skill's scenes.md, meshes.md and materials.md first.
lives in EDIT.tsx and is frame-pure. Read `raea guide bevy/scenes`, `raea guide bevy/meshes` and `raea guide bevy/materials` first.

THE BAR
The target picture media/ref/target.png is a real in-engine screenshot of this scene from the hero camera. The
Expand Down
2 changes: 1 addition & 1 deletion sdk/raea/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ raea render title.tsx -o title.mp4
- Time anchored to words in a transcript (`word()`, `findPhrase()`), so cues follow the speech when the cut moves.
- Games as a pure step from input to state (`useGameState`, `useInput`, `useGameEvents`): played live, rendered from a
logged play, the same pixels.
- 3D and an ECS world in the same tree, drawn by Bevy (`raea/3d`, `/ecs`); see skills/raea-bevy.
- 3D and an ECS world in the same tree, drawn by Bevy (`raea/3d`, `/ecs`); see the raea skill's 3D guide (skills/skills/raea/3d.md).
- Sound made on your Mac as values: `Tone.tokensynth()` instruments for music and `sao()` foley, cached by prompt,
seed and settings; `raea sounds` fetches open sample libraries for a Tone.js `Sampler`.
- The same code renders on the Mac and the iPhone.
Expand Down
2 changes: 1 addition & 1 deletion sdk/raea/docs/bevy-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ export declare function stepBodies(bodies: Body[], dt: number, gravity?: Vec3):

## Existing Bevy knowledge packs (surveyed 2026-10-18)

What the skills library (`sdk/guides/craft/bevy/`, mirrored in `sdk/skills/raea-bevy/`) took from each. Nothing was
What the skills library (`sdk/guides/craft/bevy/`, copied into `skills/skills/raea/3d/` (raea-skills)) took from each. Nothing was
copied from a pack without a permissive license; the library is written for our SDK, so most packs informed its
structure and its list of mistakes rather than its text.

Expand Down
2 changes: 1 addition & 1 deletion sdk/raea/docs/bevy-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -717,7 +717,7 @@ be treated as non-exact.
3. **Generate the TypeScript, then curate it.** Keep the generator as the source of the types and wrappers, and add a
per-plugin allow-list so agents see `RigidBody`, `ColliderConstructor`, `Restitution`, `Friction`, `LinearVelocity`
and `Gravity`, not `SolverBody` or `LastPhysicsTick`. Put the result in `raea` behind the plugin's feature,
such as a `./physics` entry, and teach it in the raea-bevy skill.
such as a `./physics` entry, and teach it in the raea skill's 3D guide.
4. **Hand-write only the asset and event edges**, as reflected components of ours that build the plugin's runtime
objects from numbers (hanabi's `Particles`), so the generator covers them too.
5. **Physics first.** avian3d is the best fit: deterministic, step-driven and data-described, with exact render equals
Expand Down
11 changes: 0 additions & 11 deletions sdk/skills/README.md

This file was deleted.

73 changes: 0 additions & 73 deletions sdk/skills/raea-bevy/SKILL.md

This file was deleted.

1 change: 0 additions & 1 deletion sdk/skills/raea-bevy/animation.md

This file was deleted.

1 change: 0 additions & 1 deletion sdk/skills/raea-bevy/assets.md

This file was deleted.

1 change: 0 additions & 1 deletion sdk/skills/raea-bevy/blender.md

This file was deleted.

1 change: 0 additions & 1 deletion sdk/skills/raea-bevy/characters.md

This file was deleted.

1 change: 0 additions & 1 deletion sdk/skills/raea-bevy/games.md

This file was deleted.

1 change: 0 additions & 1 deletion sdk/skills/raea-bevy/lights.md

This file was deleted.

1 change: 0 additions & 1 deletion sdk/skills/raea-bevy/limits.md

This file was deleted.

1 change: 0 additions & 1 deletion sdk/skills/raea-bevy/liquids.md

This file was deleted.

1 change: 0 additions & 1 deletion sdk/skills/raea-bevy/materials.md

This file was deleted.

Loading
Loading