Add gum-skills/ folder with 5 consumer-facing AI skills (#2700)

Establishes a permanent home for external-facing AI skills that consumers drop into their project's .claude/skills/ to work *with* Gum (distinct from the engine-internal .claude/skills/ set for working *on* Gum). Fulfills the folder the published docs/ai/ai-skills.md already links to.

Adds README.md plus five skills: gum-overview (file types, Forms vs raw visuals, the three usage modes, project wiring, the content-copy rule), gumcli (edit->validate->verify recipes), gum-file-format (enum->int tables for Units/Origins/ChildrenLayout, qualified InstanceName.Property variables, instance parenting, and the silent-failure landmines), gum-forms-controls (controls vs raw visuals, composition via AddChild, the state/category system), and gum-layout (units, Anchor/Dock, stacking).

Content is grounded in source (enum values, GumService init, package IDs, Anchor/Dock/AddChild APIs) and validated by a fresh-agent dry-run whose findings drove a round of fixes; the file-format skill's example passes gumcli check and renders.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vchelaru

gum-skills/README.md

@@ -0,0 +1,69 @@
+# gum-skills
+
+Skills for developers building game UI **with** Gum.
+
+Drop the subfolders you want into your project's `.claude/skills/` (or your
+user-global `~/.claude/skills/`) to give an AI assistant such as Claude Code
+durable, concept-level context on Gum — file formats, layout, Forms controls,
+and the `gumcli` command-line tool. A skill loads automatically when its
+`description` matches what you are doing, so the assistant stops guessing at
+Gum's conventions and starts following them.
+
+These are **3rd-party skills**: they describe how to *use* Gum from a game
+project. Skills for working *on* Gum itself live in the repo's own
+`/.claude/skills/` folder and are not meant for distribution — do not add
+engine-internal material here.
+
+## Getting started
+
+Copy `gum-overview` first — it is the single entry point the other skills
+assume — then add the topical skills that match your work:
+
+| Skill | Use it for |
+|-------|-----------|
+| `gum-overview` | What Gum is, project file types, usage modes, project wiring. **Start here.** |
+| `gumcli` | Scaffolding, code generation, validation, and screenshots from the command line. |
+| `gum-file-format` | Reading and safely hand-editing `.gumx`/`.gusx`/`.gucx`/`.gutx` XML. |
+| `gum-forms-controls` | Buttons, text boxes, lists, panels, and the state/category styling system. |
+| `gum-layout` | Positioning and sizing — units, anchor/dock, stacking. |
+
+A good default set is `gum-overview` + `gumcli` + whichever of `gum-layout`,
+`gum-forms-controls`, and `gum-file-format` your task touches.
+
+These skills pair with two other AI aids Gum ships: the **MCP documentation
+server** (live, authoritative doc lookups) and **`gumcli`** (act on a project
+and verify the result). See <https://docs.flatredball.com/gum/ai> for the full
+picture.
+
+## Authoring a new skill
+
+Each skill is a folder containing a single `SKILL.md`. The file starts with
+YAML frontmatter and uses `##` sections for the body:
+
+```markdown
+---
+name: gum-example
+description: One line telling the assistant WHEN this skill is relevant. Triggers: distinctive words, file types, symbols.
+---
+
+# Title
+
+## Section
+Concise, high-signal guidance. Link to the docs for depth.
+```
+
+Guidelines:
+
+- **`description` is a trigger, not a summary.** Keep it to one line. Lead with
+  the topic, then list the distinctive words, file extensions, or symbols that
+  should activate it. It is loaded on every session, so keep it short.
+- **Link to the docs; don't restate them.** Point at
+  <https://docs.flatredball.com/gum> for anything that lives there. A skill is a
+  map and a list of gotchas, not a copy of the manual.
+- **Keep it short and self-contained.** The reader does not have Gum's source
+  tree — favor concrete rules and small examples over "see this class."
+- **Add a `references/` subfolder** only when a skill needs bulky supporting
+  material (long tables, extended examples) that would bloat `SKILL.md`.
+
+When a skill becomes broadly useful, propose adding it here by opening an issue
+or PR on the [Gum repository](https://github.com/vchelaru/Gum).

gum-skills/gum-file-format/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: gum-file-format
+description: Reading and safely hand-editing Gum's XML files — enum-to-int mappings for Units/Origins/ChildrenLayout, qualified InstanceName.Property variables, and why hand-edited files silently break. Triggers: editing .gusx/.gucx/.gutx by hand, WidthUnits/XOrigin values, gumcli check errors.
+---
+
+# Gum File Format
+
+Gum projects are XML, serialized with .NET's `XmlSerializer`. Prefer editing
+them with the Gum tool or `gumcli`; when you must read or hand-edit, this skill
+covers the structure and the traps. **Always run `gumcli check` after a hand
+edit** — several failure modes below are silent otherwise (see **gumcli**).
+
+## File → root element
+
+| Extension | Root element |
+|-----------|--------------|
+| `.gumx` (project) | `<GumProjectSave>` — lists element references, loaded first |
+| `.gusx` (screen) | `<ScreenSave>` |
+| `.gucx` (component) | `<ComponentSave>` |
+| `.gutx` (standard element) | `<StandardElementSave>` |
+| `.behx` (behavior) | `<BehaviorSave>` |
+
+## Element structure
+
+Every file needs the complete root tag **with both XML-schema namespaces** —
+the `xsi:`/`xsd:` prefixes used on every `<Value>` are undefined without them.
+The element has a `<Name>`, an optional `<BaseType>` (what it inherits from,
+e.g. `Container`), one or more `<State>`s (the first is `Default`), and a list
+of `<Instance>`s (child objects). A state holds `<Variable>` entries. This is a
+complete, valid screen (it passes `gumcli check`):
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<ScreenSave xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <Name>MainMenu</Name>
+  <State>
+    <Name>Default</Name>
+    <Variable Type="ChildrenLayout" Name="MenuStack.ChildrenLayout"><Value xsi:type="xsd:int">1</Value></Variable>
+    <Variable Type="string" Name="Title.Parent"><Value xsi:type="xsd:string">MenuStack</Value></Variable>
+    <Variable Type="string" Name="Title.Text"><Value xsi:type="xsd:string">Main Menu</Value></Variable>
+  </State>
+  <Instance><Name>MenuStack</Name><BaseType>Container</BaseType></Instance>
+  <Instance><Name>Title</Name><BaseType>Text</BaseType></Instance>
+</ScreenSave>
+```
+
+**`<Name>`** is the element's name — path-qualified for an element in a
+subfolder (`Elements/Divider`), otherwise bare (`MainMenu`). It must match the
+reference to it in the `.gumx`.
+
+**Qualified variable names.** A variable named `MenuStack.ChildrenLayout` sets
+the `ChildrenLayout` of the instance named `MenuStack`. No dot means an
+element-level value. The name before the dot must match an `<Instance>`'s
+`<Name>`.
+
+**Parenting instances.** Instances are siblings by default — all direct children
+of the element root. To nest one inside another, give the child a `Parent`
+variable whose value is the parent instance's name (`Title.Parent = MenuStack`
+above puts `Title` inside `MenuStack`, so the container's stacking layout
+arranges it). Without it, a stacking container has nothing to lay out.
+
+## Landmine: enum values are stored as integers
+
+For an enum-typed variable, the `Type` attribute holds the enum name but the
+`<Value>` holds its **underlying int** (`xsi:type="xsd:int"`), not the name.
+`WidthUnits` = `2` means `RelativeToParent`. You must know the mappings to read
+or write these correctly:
+
+### WidthUnits / HeightUnits — `DimensionUnitType`
+
+| Int | Name | Int | Name |
+|----|------|----|------|
+| 0 | Absolute | 6 | MaintainFileAspectRatio |
+| 1 | PercentageOfParent | 7 | Ratio |
+| 2 | RelativeToParent | 8 | AbsoluteMultipliedByFontScale |
+| 3 | PercentageOfSourceFile | 9 | ScreenPixel |
+| 4 | RelativeToChildren | 10 | RelativeToMaxParentOrChildren |
+| 5 | PercentageOfOtherDimension | | |
+
+### XUnits / YUnits — `PositionUnitType`
+
+One shared enum; some values apply to the X axis, some to Y. **This is not the
+`GeneralUnitType` enum you use in C# code** — on disk `XUnits`/`YUnits` are
+`PositionUnitType`. Do not copy int values between the two.
+
+| Int | Name | Axis | Int | Name | Axis |
+|----|------|:----:|----|------|:----:|
+| 0 | PixelsFromLeft | X | 5 | PixelsFromBottom | Y |
+| 1 | PixelsFromTop | Y | 6 | PixelsFromCenterX | X |
+| 2 | PercentageWidth | X | 7 | PixelsFromCenterY | Y |
+| 3 | PercentageHeight | Y | 8 | PixelsFromCenterYInverted | Y |
+| 4 | PixelsFromRight | X | 9 | PixelsFromBaseline | Y |
+
+### XOrigin, and Text `HorizontalAlignment` — `HorizontalAlignment`
+
+`0` = Left, `1` = Center, `2` = Right.
+
+### YOrigin, and Text `VerticalAlignment` — `VerticalAlignment`
+
+`0` = Top, `1` = Center, `2` = Bottom, `3` = TextBaseline.
+
+### ChildrenLayout (on a container) — `Type="ChildrenLayout"`
+
+`0` = Regular, `1` = TopToBottomStack, `2` = LeftToRightStack,
+`3` = AutoGridHorizontal, `4` = AutoGridVertical.
+
+## Landmine: two on-disk variable shapes exist
+
+Gum has written variables two ways over time — a compact **attribute form**
+(current tool output) and an expanded **element form** (older files). Both load:
+
+```xml
+<!-- attribute form -->
+<Variable Type="DimensionUnitType" Name="WidthUnits"><Value xsi:type="xsd:int">0</Value></Variable>
+<!-- element form -->
+<Variable><Type>DimensionUnitType</Type><Name>WidthUnits</Name><Value xsi:type="xsd:int">0</Value><SetsValue>true</SetsValue></Variable>
+```
+
+Do not hand-craft variables from scratch by guessing the shape. Copy the shape
+of an existing variable in the same file, or better, let the tool/`gumcli`
+write them and edit values only.
+
+## Landmine: wrong element names are dropped silently
+
+`XmlSerializer` ignores XML elements it does not recognize — it does not error.
+So `<States>` instead of `<State>`, or `<InstanceSave>` instead of `<Instance>`,
+loads as an **empty** element with no warning, and your UI is silently missing
+content. `gumcli check` is built to catch exactly this. Run it after every hand
+edit.
+
+## Bottom line
+
+Read these files freely; the tables above let you understand and sanity-check
+them. But to *write* them, prefer the Gum tool or `gumcli`, and validate with
+`gumcli check` before trusting the result. Data-model reference:
+<https://docs.flatredball.com/gum/gum-tool/gum-elements>.

gum-skills/gum-forms-controls/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: gum-forms-controls
+description: Gum Forms controls (Button, Label, TextBox, CheckBox, ListBox, StackPanel…) vs raw visuals, and the state/category styling system. Triggers: adding a button/textbox/list, WPF-style properties not working, IsVisible, styling a control, DefaultVisuals.
+---
+
+# Gum Forms Controls
+
+Forms controls are interactive UI classes whose names mirror WPF (`Button`,
+`CheckBox`, `TextBox`, …), but they are laid out and rendered by **Gum**, not
+WPF. Reach for a Forms control for anything the player clicks, types in, or
+scrolls. For non-interactive HUD/decoration, use raw visuals instead (see
+below). Docs: <https://docs.flatredball.com/gum/code/controls>.
+
+## Common controls
+
+`Button`, `ToggleButton`, `RadioButton`, `CheckBox`, `Label`, `TextBox`,
+`PasswordBox`, `ComboBox`, `ListBox`, `Slider`, `ScrollBar`, `ScrollViewer`,
+`StackPanel`, `Panel`, `Menu`, `Window`, `Splitter`.
+
+## Using a control in code
+
+```csharp
+using Gum.Forms.Controls;
+
+var button = new Button();
+button.Text = "Play";
+button.AddToRoot();               // adds it to the screen
+button.Click += (_, _) => StartGame();
+```
+
+Text-bearing controls share this shape — `new Label()`, `new TextBox()`, etc.
+all expose `.Text`. Set position/size with Gum's unit system (see
+**gum-layout**), not WPF layout.
+
+## Composing controls (parenting in code)
+
+`AddToRoot()` attaches a control to the screen. To nest one control inside
+another — buttons inside a panel, anything inside a container — call `AddChild`
+on the parent. There is **no** `.Children.Add(...)` on a Forms control.
+
+```csharp
+var menu = new StackPanel();   // stacks its children; vertical by default
+menu.Spacing = 8;              // gap between children (StackPanel.Spacing)
+menu.AddToRoot();
+
+var play = new Button { Text = "Play" };
+var quit = new Button { Text = "Quit" };
+menu.AddChild(play);           // parents the control under the panel
+menu.AddChild(quit);
+```
+
+`AddChild(child)` sets the child's visual parent; the parent's layout then
+positions it — a `StackPanel` stacks them, and any container with
+`ChildrenLayout` set arranges them. `RemoveChild` undoes it. `StackPanel`
+defaults to `Orientation.Vertical`; set `Orientation = Orientation.Horizontal`
+for a row.
+
+## Forms vs raw visuals
+
+| Need | Use |
+|------|-----|
+| Player interaction (click/type/scroll) | A Forms control |
+| Static text | `TextRuntime` |
+| Solid color block | `ColoredRectangleRuntime` |
+| Image | `SpriteRuntime` |
+| Scalable panel/border | `NineSliceRuntime` |
+| Plain layout container | `ContainerRuntime` |
+
+Raw visuals: <https://docs.flatredball.com/gum/code/standard-visuals>.
+
+## Landmine: WPF conventions do not carry over
+
+The names match WPF; the property model does not. On a Forms control:
+
+- **No** `Margin`, `Padding`, or WPF-style `HorizontalAlignment`/`VerticalAlignment`.
+  Position and size come from Gum units (`X`, `XUnits`, `Width`, `WidthUnits`, …).
+- **No** `Background`, `Foreground`, or `BorderBrush`. Color and appearance come
+  from **states** (below), not brush properties.
+- **No** `Visibility` enum. Use the `IsVisible` bool.
+- **No** WPF `Auto` sizing. A `Button` with `Width = 128` is 128 px wide
+  regardless of its text unless `WidthUnits = RelativeToChildren`. See
+  **gum-layout**.
+
+For a fuller WPF-to-Gum translation:
+<https://docs.flatredball.com/gum/code/about/for-wpf-users>.
+
+## The state / category system (how styling works)
+
+Appearance is driven by named **states** grouped into a **category** on the
+control's visual, not by per-property setters. A `Button`'s visual, for example,
+carries a category with `Enabled`, `Highlighted`, `Pushed`, `Focused`, and
+`Disabled` states; the control switches between them automatically as the player
+interacts. Each state sets a batch of variables (colors, sizes) at once.
+
+To recognize this in code: applying a state name changes the look; the control
+does this for you on hover/press/focus. To *customize* appearance you edit the
+states (in the tool, or via the styling APIs) or swap in a different visual —
+you do **not** look for a `Color` property on the control. Don't panic when you
+see categories and states; they are Gum's equivalent of a style sheet. Styling
+guide: <https://docs.flatredball.com/gum/code/styling>.
+
+## Default visuals
+
+A newly-constructed control (`new Button()`) gets a built-in default visual so
+it renders without any project. Replacing or restyling that visual is the
+styling story above. If a control looks unstyled or blank, its visual — not the
+control class — is what to inspect.