diff --git a/skills/ue5-unreal/SKILL.md b/skills/ue5-unreal/SKILL.md index 90a6e0a..817de16 100644 --- a/skills/ue5-unreal/SKILL.md +++ b/skills/ue5-unreal/SKILL.md @@ -1,11 +1,11 @@ --- name: ue5-unreal description: > - Unreal Engine 5 development assistant — log analysis, asset auditing, - engine-docs research, and Python script generation via Spaghetti Unreal AI + Unreal Engine 5 development assistant — crash analysis, asset auditing, + knowledge-base search, and Python script generation via Spaghetti Unreal AI Workbench. Call these tools when the user is working in a UE5 project and - needs expert help with log errors or crashes, asset cleanup, engine docs, - or editor automation. + needs expert help with crashes, asset cleanup, engine docs, or editor + automation. --- # UE5 Unreal AI Workbench Tools @@ -17,80 +17,73 @@ connect — a browser window opens for sign-in at spaghetti.gg). ## Prerequisites -The user must have signed in at [spaghetti.gg](https://spaghetti.gg) at least -once (accounts and welcome credits are created on first sign-in). +Your UE5 project must have a `.spaghetti` file at its root containing +`team_id` and `project_id`. If no `.spaghetti` exists, the first tool call +returns an Agentic Directive instructing you to create one. Follow it. -A `.spaghetti` file at the UE5 project root (`team_id`, `project_id`) is -optional — without it, calls bill the user's personal wallet and everything -works except the two project-scoped research tools (`search_logs_temporal`, -`investigate_incident`). If you see a "no user account exists" error, point -the user at the portal sign-in; if you see "not a member of team", the -`.spaghetti`/headers point at the wrong team. +## Available tools (Phase 1 — MVP) -## Available tools +### Crash Investigator (`spaghetti/analyze_crash`) -### Log Analyzer (`spaghetti/analyze_logs`) +**When to call:** The user reports a UE5 crash, paste an output log, or +mentions a crash dump / minidump. -**When to call:** The user reports errors or a crash in their UE5 project and -has a log file (for example `Saved/Logs/.log`, or a crash log). +**What it does:** Parses the UE5 Output Log and crash dumps, identifies +root-cause nodes or C++ pointers, and returns a precise fix with context from +the proprietary UE5 bug knowledge base. -**What it does:** Full-log analysis — structured findings with severity and -evidence, crash triage naming the suspect Blueprint, and statistics. Uploads -are session-based; large logs never flow through chat. +**Input:** Crash log text (paste the Output Log contents or the relevant +section). -**Input:** A local log path (`logPath`) to start a session, or pasted log -text (`logText`) as the fallback path. +**Safety:** Read-only analysis. Returns a diagnosis + suggested fix; does +not modify project files. -**Cost:** 5 credits per session, billed only when analysis runs — empty logs -or logs with no Error/Fatal entries are free. Retries never bill twice. +### Asset Janitor (`spaghetti/audit_assets`) -**Safety:** Read-only analysis. Does not modify project files. +**When to call:** The user asks about asset cleanup, naming conventions, unused +assets, missing LODs, or compliance reports. -### Asset Janitor (`spaghetti/tidy_assets`) +**What it does:** Finds textures without LODs, detects naming-convention +violations (`T_`, `BP_`, etc.), identifies unused/0-reference assets, and +generates compliance reports. -**When to call:** The user asks about asset cleanup, naming conventions, -unused assets, missing LODs, or compliance reports. - -**What it does:** Audits a project asset inventory — unused assets with -reclaimable sizes, redirectors, naming-convention violations, LOD problems — -and returns a prioritized report plus a downloadable CSV. - -**Input:** An inventory JSONL path. With the UE connector plugin installed, -call its `export_asset_inventory` tool in the editor first (it writes -`Saved/spaghetti_inventory.jsonl`); without it, a short Python-console script -produces the same file. - -**Cost:** 3 credits per session, billed only when a report is produced. +**Input:** Optionally specify which checks to run (naming, LODs, unused). **Safety:** Audit is read-only. If the user wants to apply fixes, use -Tool-Maker to generate a dry-run script first. +Tool-Maker to generate a dry-run Python script first. -### Research tools (free) +### Smart Librarian (`spaghetti/search_kb`) -- `search_docs_code` — hybrid search over curated UE engine documentation. -- `search_patterns` — recommended engine approaches vs anti-patterns for a described intent. -- `search_logs_temporal` — time/severity/subsystem-filtered search over logs previously ingested by `analyze_logs`. Requires project context. -- `query_temporal_relations` — entity-relation traversal over ingested logs (up to 3 hops, optionally as of a point in time). -- `investigate_incident` — bounded investigation combining logs, relations, docs, and patterns. Requires project context. +**When to call:** The user asks about UE5 engine architecture, best practices, +or how specific systems work. Also for snippet search (verified node setups, +Blueprint patterns). + +**What it does:** Semantic search over two knowledge bases: +- **Team KB:** your project's private RAG index (studio docs, past bug + resolutions, conventions). +- **UE5 Engine Graph:** GraphRAG over the public UE 5.8 source for multi-hop + reasoning about engine architecture. + +**Input:** Natural-language query about UE5 or your project's knowledge base. ### Tool-Maker (`spaghetti/make_tool`) **When to call:** The user wants to automate a UE5 editor task (batch-rename -assets, apply settings, generate reports, etc.). +assets, apply materials, configure project settings, etc.). -**What it does:** Generates an editor-automation Python script from a -natural-language description of the task. +**What it does:** Generates a safe, production-quality Python script using +`unreal.EditorAssetLibrary` API. The script runs via the UE 5.8 Python remote +execution bridge. **Safety — three-layer model:** -1. **API allowlist:** only approved editor APIs. -2. **Dry run:** delivered scripts are simulation transforms — destructive - operations commented out, reversible operations wrapped in - `unreal.ScopedTransaction` for undo support. -3. **Human approval:** the user Approves/Declines via the client's approval - flow. Billed 10 credits only on approval; blocked, declined, and - cancelled runs are free. +1. **API allowlist:** only approved `unreal.EditorAssetLibrary` functions. +2. **Dry run:** scripts default to simulation mode (log what would happen, + don't execute destructive ops). +3. **Human approval:** before any destructive script runs, the user sees an + Approve/Reject dialog. -**Always show the generated script to the user before executing.** +**Always show the generated script to the user before executing.** If the +script modifies assets, wrap in `unreal.ScopedTransaction` for undo support. ## Safety defaults @@ -99,9 +92,9 @@ natural-language description of the task. - **Use ScopedTransaction** for reversible operations (enables Ctrl+Z). - **Read the Output Log** for errors after any automated editor operation. -## Billing +## Context -Tool calls bill the user's personal wallet, or the team wallet when team -context is set. If you see `402 Payment Required` / "Insufficient credits", -call the free `topup` tool to create a checkout link, or direct the user to +The `.spaghetti` file at the project root identifies which team and project +this UE5 project belongs to. All tool calls are billed to the team's Spaghetti +wallet. If you see a `402 Payment Required`, direct the user to `spaghetti.gg/billing` to top up.