v2.0 — install via Claude Code /plugin manager

Install

/plugin marketplace add ABostrom/ushell-skill
/plugin install ushell@ABostrom-skills

Replaces the v1.x clone-and-symlink instructions (Windows-only PowerShell, manual sync per release). The Claude Code plugin manager handles updates from here.

What's New

v2.0 is a distribution-layer release. Skill content itself is byte-identical to v1.4 — same iron rules, same 78 commands, same 14 workflows, same anti-patterns, same 13/13 GREEN scenarios. What changed is how it gets onto your machine.

Plugin manifests

New .claude-plugin/ directory at repo root holds the marketplace and plugin descriptors that make /plugin install work:

• marketplace.json — declares the ABostrom-skills marketplace.
• plugin.json — declares the ushell plugin at version 2.0.0, MIT-licensed, with keywords for discoverability.

Skill content moved under skills/ushell/

SKILL.md and the eight reference/*.md files moved from repo root to skills/ushell/. All renames preserved at 100% similarity — git log --follow skills/ushell/SKILL.md walks the history through the move. Relative links inside SKILL.md to reference/*.md still resolve because both moved by the same depth.

Documentation updated for the new install path

• README.md — install snippet rewritten as the two /plugin commands; repo-tree diagram reflects the new layout; status bumped to v2.0; v1.x migration callout added.
• CLAUDE.md — "Working tree vs install location" section rewritten to describe the plugin manager; read-first pointers retargeted at skills/ushell/reference/....
• docs/onboarding.md — Step 1 install rewritten; all ../reference/*.md markdown links retargeted at ../skills/ushell/reference/...; verify-install snippet now uses /plugin list instead of Get-ChildItem on the old symlink path.

Test harness retargeted

tests/run-green.ps1 now points $SkillRoot at skills/ushell/ and pre-flight-checks that SKILL.md exists at the new path before emitting dispatch prompts. tests/with-skill.md updated to name the new skill-load location. Smoke-tested before release.

Migrating from v1.x

If you installed v1.x via the symlink instructions:

Remove-Item "$env:USERPROFILE\.claude\skills\ushell"

…then run the two /plugin commands at the top of this note. The two install paths don't collide (the plugin manager installs into ~/.claude/plugins/cache/ABostrom-skills/ushell/2.0.0/), so the cleanup is optional but tidy.

The v1.4 tag is preserved if you need to fall back to the symlink install.

What Didn't Change

The skill itself. Every iron rule, every command page, every workflow DAG, every anti-pattern, every UE-args grammar rule. If you've been running v1.4, your subagent transcripts after upgrading will look identical. v2.0 is purely about getting more people running the same content with less friction.

Compatibility

ushell ships with Unreal Engine (Engine/Extras/ushell/), so this skill's reference content implicitly targets one specific UE version's ushell. v2.0 is authored against UE 5.7.

UE version	Status	What it means
5.7	✅ Tested against	The 13 GREEN scenarios all ran here. reference/*.md citations point at Engine/Extras/ushell/... in a UE 5.7 tree.
5.6	🟡 Expected to work	Minor flag/verb-name differences possible. File an issue with the drift; it'll get inline > **UE 5.6:** callouts at the affected entries.
5.0 – 5.5	⚠️ Unverified	Older ushell has fewer verbs and some renamed flags; the skill may confidently recommend a command that doesn't exist in your tree. PRs welcome.
5.8+	⏳ Pending retest	When the engine ships, tests/run-green.ps1 gets re-run, drift gets patched, the matrix grows. Cut as the next minor release.
6.0+	🚧 Future major	Significant UE majors trigger a major skill version bump (v3.0).

The full policy — how drift is handled, when minor/major skill versions bump, when to escalate from single-trunk to per-engine release branches — is documented on main at docs/versioning.md.

Spec

Full design rationale and investigation findings: docs/superpowers/specs/2026-05-13-phase17-install-ergonomics.md.

v1.4 — Lyra learnings landed

Pre-v2.0 — symlink-install era. For the current /plugin install flow, see v2.0.

Learnings from Epic-authored Lyra. Read-through of D:\LyraStarterGame (UE 5.6) plus the latest upstream Lyra in EpicGames/UnrealEngine surfaced ~16 patterns the skill should document. The MUST and SHOULD tiers all landed in v1.4.

BuildGraph schema and task additions

reference/buildgraph.md grew three new sections:

• §11 — Built-in BuildGraph properties. Table of 14 built-ins: $(IsBuildMachine), $(IsPreflight), $(Horde), $(Change), $(CodeChange), $(PreflightChange), $(Branch), $(EscapedBranch), $(RootDir), $(BuildName), $(BuildNamePath), $(NetworkOutputDirectory), $(PreNodeName), $(RequiredEditorPlatforms), $(TargetPlatforms)/$(TargetConfigurations)/$(EditorPlatforms).
• §12 — Engine-shipped meta-scripts (source-build only). BuildAndTestProject.xml, PGOProfileProject.xml, GauntletSettings.xml, and the two AutomatedPerfTesting meta-scripts. Critical caveat: installed engines (Epic Games Launcher) do NOT ship these — the Lyra pattern only works with a source-build engine. Installed-engine users should write BuildGraph from scratch.
• §13 — Extending BuildAndTestProject.xml. Lyra's append-to-$(BuildAndTestExtendedRequirements) + declare-super-aggregate pattern. Explains why $(PreNodeName) matters for multi-project BuildGraph jobs.

Schema additions (§3): <ForEach>, <Do If="...">, <Switch>/<Case>/<Default>, conditional expression syntax (And/Or/!/Exists/ContainsItem).

Task additions (§4): <RetrieveArtifact> (Horde artifact pull), <Strip> (separate symbol stripping), <SetVersion> (stamp Build.version).

Custom UAT command authoring

reference/uat.md §10 is new. Four subsections covering the full author-your-own-UAT-command path:

• §10.1 — <Project>.Automation.csproj template (Lyra-derived, with AutomationUtils / Localization / XLoc / Crowdin / EpicGames.Core / Gauntlet / UnrealBuildTool ProjectReferences).
• §10.2 — Writing BuildCommand subclasses: [Help] attributes, ParseParam/ParseParamValue, CommandUtils.P4.*, CommandUtils.RunCommandlet(uproject, exe, name, args) for spinning up the editor from a UAT command.
• §10.3 — Authoring Gauntlet test classes: EpicGameTestNode<Cfg> + EpicGameTestConfig + [AutoParam], with engine-side Controllers.Add() pairing.
• §10.4 — Multi-storefront target pattern (LyraGame | LyraGameEOS | LyraGameSteam | LyraGameSteamEOS) — separate .Target.cs per storefront, BuildGraph picks via -set:TargetName=.

New workflow recipes

• Recipe 15 — PCB-for-UGS: full BuildGraph skeleton for the Lyra pattern (Compile → Strip → Zip → Submit to a separate P4 stream with FileType=binary+FS32 for UGS auto-deploy).
• Recipe 16 — PGO two-step (Profile → Optimize) via the engine's PGOProfileProject.xml meta-script.

Misc

• reference/uat.md §1 picked up -compile, -nocompile, -nocompileeditor, -ScriptDir, -NoP4 (lifted from real Lyra usage).
• reference/uat.md §4.3 documents the 11-variant UE.CookByTheBook* cook test matrix Lyra wires from CI options.
• commands.md .uat entry: added -compile and -UseLocalBuildStorage to examples.
• LICENSE — MIT, added at repo root.

Research source: tests/lyra-learnings.md (gitignored from skill content but committed in the repo).

v1.3 — live output streaming + F6

Pre-v2.0 — symlink-install era. For the current /plugin install flow, see v2.0.

Live output streaming patterns and a correctness fix for .build clean.

Live output streaming (Mode A + Mode B)

Two complementary modes for showing ushell output in Claude Code conversations as the user (or a subagent) drives a build. Both documented in reference/invocation.md with rationale for every flag.

• Mode A — synchronous Bash call (no run_in_background). Cmd output flows directly into the tool result inline. Works up to Bash tool's 10-minute cap. Canonical recipe uses MSYS_NO_PATHCONV=1 + single-quoted cmd string + tr + sed to strip ANSI codes + grep -aE filter for progress markers. Demonstrated live during the battle test — a 46-action rebuild streamed inline.
• Mode B — background + Monitor. Bash kicks off ushell with run_in_background:true, writing to a sentinel-bracketed log file. A separate Monitor tails the log with stdbuf -oL grep for the same markers. STREAM_BEGIN / STREAM_END sentinels let Monitor exit cleanly instead of hitting its 600s default timeout. Each match becomes a real-time conversation event. For builds longer than 10 min.

tests/stream-ushell.sh — production helper for Mode B. Auto-locates ushell.bat by walking up from the .uproject; supports USHELL_BAT env override; converts /e/... bash paths to E:\... Windows paths; sentinel-brackets the log for Monitor shutdown.

F6 — --clean is clean-only, NOT clean+rebuild

Skill defect: .build clean editor and .build editor --clean both pass UBT's -Clean flag, which means "clean and stop". Verified empirically — a .build editor --clean run deleted ProjectGear's editor binaries and exited 0 with zero compile actions; a follow-on .build editor was needed to restore them.

Fixed in reference/commands.md:

• Shared _BuildCmd options block: --clean now documented as "Clean only".
• .build clean editor entry: header changed to "Clean only the editor (NOT clean+rebuild)"; canonical chained-rebuild pattern documented: .build clean editor && .build editor.

Battle test write-up

Extended in tests/battle-test-projectgear.md with the B6 section + cumulative findings summary table.

v1.2 — five real-world fixes from ProjectGear

Pre-v2.0 — symlink-install era. For the current /plugin install flow, see v2.0.

Five real-world fixes from a battle test against E:\Work\Games\ProjectGear. Lifts the skill from "reproduces synthetic GREEN" to "survives real-world use." All findings documented at tests/battle-test-projectgear.md with reproducible commands and log evidence.

Fixes

• F1 — --nosummary defensive-add bites. SKILL.md and reference/invocation.md said "commands that have it (build, sync, mergedown, switch, …)" — the … was too permissive. Real impact: an agent following the skill defensively added --nosummary to .info and got ERROR: Unknown argument(s) 'nosummary'. Replaced with an explicit accepts/rejects table grounded in the @summarise decorator. Removed --nosummary from the example invocation.
• F2 — .info projects on standalone projects. Added Preconditions to the commands.md entry plus a dedicated troubleshooting.md entry: on standalone-project-against-installed-engine layouts, the command leaks an OSError stack trace to stderr but exits 0. Use plain .info instead.
• F3 — "Program targets not supported" noise on installed engines is expected and non-fatal. Documented in troubleshooting.md.
• F4 — Boot-time vs. command-time wording differs. The boot-time !! Unable to locate any projects from 'X' (from ushell.bat itself) is distinct from the command-time stack trace (Unable to establish an Unreal context... from a verb's get_unreal_context). Both now appear in troubleshooting.md so users find the entry whichever symptom they see first.
• F5 (MAJOR) — -PackageDir= does NOT restrict ResavePackages scope. Verified by reading Engine/Source/Editor/UnrealEd/Private/Commandlets/ContentCommandlets.cpp:129-200 from EpicGames/UnrealEngine release 5.7. The commandlet accepts -Package=, -PackageFolder=, or -Map= (case-insensitive); -PackageDir= is silently ignored, falling through to "resave everything" including engine packages. A "tiny dir" run resaved 1500+ Engine packages before being killed. Patched in 7 files: unreal-args.md, workflows.md, buildgraph.md, commands.md, uat.md, channel-authoring.md.

Why this release matters

Synthetic GREEN scenarios verify the skill against the failure modes you expected. Battle tests against real projects surface failure modes you didn't. v1.2 closes the gap on five.

v1.1 — documentation expansion + S8-S13

Pre-v2.0 — symlink-install era. For the current /plugin install flow, see v2.0.

Documentation expansion and an expanded test corpus. The skill content itself is unchanged from v1.0; v1.1 makes it approachable for new contributors and adds six scenarios that v1.0's 7-scenario corpus didn't reach.

New documentation

• docs/onboarding.md — six-step walkthrough from zero to "I can drive my UE project from Claude". Targets the developer who's new to UE or ushell or Claude Code or all three.
• docs/cookbook.md — 13 user-facing recipes for the daily loop, Insights trace at CL, crash repro, bisect, cook+stage+run, stream switch, cherrypicks, perf tests, BuildCookRun, plugin packaging, Gauntlet, channel authoring.
• docs/how-it-works.md — architecture and design philosophy. Why the two-layer split, why Preconditions/Produces, why named anti-patterns.
• docs/before-and-after.md — RED-vs-GREEN gallery drawn from real transcripts. Concrete proof of skill value.
• README — comprehensive rewrite. Three before/after examples up top, full repo layout, coverage summary, testing instructions, reading order.

New scenarios (S8–S13)

Six tests covering surface S1–S7 didn't reach:

• S8 — Plugin packaging for Marketplace (.uat BuildPlugin with the since-4.25 -TargetPlatforms= gotcha).
• S9 — BuildGraph nightly CI script.
• S10 — Cherrypick hotfix across streams (with edigrate awareness).
• S11 — WorldPartitionBuilder commandlet.
• S12 — Cooked Editor distribution (-target=...CookedEditor -CookedEditor).
• S13 — ODSC shader compile server.

Each scenario has a verbatim user prompt in tests/baseline.md and a bullet rubric in tests/with-skill.md with threshold scoring where bulk-correct compliance meets the design intent.

Test runner

tests/run-green.ps1 — prints each scenario's dispatch instructions as an Agent tool call. Supports -Scenarios "S2,S6,S9" filter and -OpenRubric to open the rubric for live scoring. Doesn't dispatch agents itself (that requires a Claude Code session); just makes the re-run workflow declarative.

.\tests\run-green.ps1                       # all 13 scenarios
.\tests\run-green.ps1 -Scenarios "S2,S6,S9" # subset
.\tests\run-green.ps1 -OpenRubric           # open scoring file

v1.0 — initial public release

Pre-v2.0 — symlink-install era. For the current /plugin install flow, see v2.0.

First public release of the ushell skill. The 7-scenario test-first design loop is complete: 7/7 baseline RED scenarios all hit 7/7 GREEN with the skill loaded, plus 6 extended scenarios (S8–S13) covering plugin packaging, BuildGraph CI, cross-stream cherrypicks, WorldPartitionBuilder, Cooked Editor, and ODSC.

What landed

• SKILL.md (~12 KB always-loaded) — iron rules, detection gate, quick-reference table covering ~55 verbs, goal-directed planning rule, named anti-patterns (?PlayerStartTag=, -encrypt, invented .engine/.platform, etc.).
• reference/commands.md — 78 ushell verb pages across unreal/core and unreal/perforce. Every entry: When / Usage / Args / Flags / Preconditions / Produces / Implicit behaviour / Pitfalls / Examples / Source.
• reference/workflows.md — 14 goal-first DAGs. Headline: Insights trace at CL on platform P, with .zen snapshot list as a peer of .cook (the 50× speedup).
• reference/uat.md — UAT deep dive. Full BuildCookRun ProjectParams catalogue, the 7 verbs in execution order, pak/iostore/zen interaction, 15-recipe gallery, the canonical Gauntlet RunUnreal contract, top community gotchas.
• reference/buildgraph.md — full schema, 30+ built-in tasks documented with working XML, CookedEditor and LiveLinkHub case studies, 8 idiomatic recipes.
• reference/unreal-args.md — UE's own CLI lexicon (the post--- surface). FURL.Portal grammar inlined verbatim from the user's seed doc with call-stack citations through AGameModeBase::FindPlayerStart_Implementation.
• reference/channel-authoring.md — writing new ushell verbs. Lowercase channels/, describe.flow.py (not __init__.py), the smallest viable channel template.
• reference/troubleshooting.md — symptom-keyed diagnostics.

Headline RED→GREEN

Without the skill, baseline Claude confidently produces ?PlayerStartTag=MainStart with a fabricated C++ citation. With the skill loaded, it produces the real #MainStart URL Portal segment with a citation to URL.cpp.

Built test-first per the superpowers:writing-skills meta-skill.