refactor(skill): extract capability reference into references/capabilities.md (#15)

Moves the capability field list, the per-field comparison policy
(must-match / suggested-default / user-controlled), and the Appium-runtime
opt-in special-case handling out of `SKILL.md` and into a new
`references/capabilities.md`. Closes #5.

Per Anthropic's progressive-disclosure convention for skills, the main
SKILL.md should be orchestration-shaped ("how to think about the task")
and detail content should live in `references/` ("the specific values to
use"). Reference content is loaded on-demand by Claude when the topic
becomes relevant, rather than on every skill invocation.

Changes:

  Before: SKILL.md = 152 lines (capability list + comparison rules inline)
  After:  SKILL.md = 137 lines (-15)
          references/capabilities.md = 57 lines (new)

The two `references/capabilities.md` link-references in SKILL.md use the
relative path `references/capabilities.md` (sibling subdirectory).

The existing `references/templates/appium.ejs` is unchanged and still
resolved by `scripts/render-capabilities.js` — `pnpm test` confirms the
8 render-capabilities test cases still pass against the template.

Validate + test pass:

  $ pnpm run validate
  All checks passed.

  $ pnpm test
  Test Files  2 passed (2)
  Tests       22 passed (22)

Signed-off-by: Jeremy Longshore <jeremy@intentsolutions.io>
Co-authored-by: Jeremy Longshore <jeremy@intentsolutions.io>

Author: jeremylongshore

skills/run-automation-suite/SKILL.md

@@ -64,21 +64,10 @@ Detect the language and runtime from the file extension:
 | `.cs` / `.csproj` | .NET | `dotnet test` |
 | `.java` | Java | `mvn test` or `java -cp ...` |
 
-Read the script file and extract key capabilities from the source code:
-
-- `platformName` (Android / iOS)
-- `udid` (hardcoded or parameterized)
-- `app` (app URL or kobiton-store reference)
-- `sessionName`, `sessionDescription`
-- `automationName` (UiAutomator2, XCUITest, etc.)
-- `browserName` (if browser-based test)
-- `deviceOrientation`
-- Any `kobiton:*` vendor extensions (especially `kobiton:runtime`)
+Read the script file and extract key capabilities from the source code. The full field list, the Appium-runtime opt-in special case, and the per-field comparison policy live in [`references/capabilities.md`](references/capabilities.md).
 
 Identify how the UDID is passed into the script (CLI argument, environment variable, or hardcoded) so it can be overridden with the selected device.
 
-**Appium runtime:** Check if the script contains `'kobiton:runtime': 'appium'` or equivalent. If it does NOT, do not inject it — the default Kobiton runtime will be used. Only if the user explicitly asks to use the Appium runtime should you suggest adding `'kobiton:runtime': 'appium'` to the script's capabilities.
-
 **Validate capabilities:** After parsing the script, run the render script to generate the correct capabilities for the selected device and app:
 
 ```
@@ -94,11 +83,7 @@ node skills/run-automation-suite/scripts/render-capabilities.js \
 
 For web testing, replace `--app <app>` with `--browserName <browser> --testingType web`.
 
-Compare the JSON output against the parsed script capabilities:
-
-- **Must-match** (`platformName`, `platformVersion`, `appium:udid`, `appium:deviceName`, `appium:app`/`browserName`, `appium:automationName`): If different, show what will change and edit the script automatically. These must match the selected device/app.
-- **Suggested defaults** (`kobiton:sessionName`, `kobiton:sessionDescription`, `kobiton:deviceOrientation`, `kobiton:captureScreenshots`, `appium:noReset`, `appium:fullReset`): If different or missing, show the diff and ask the user before changing. The user may have intentionally set different values.
-- **User-controlled**: Any capabilities in the user's script that are not in the rendered output — leave untouched. Never inject or modify `kobiton:runtime` unless the user explicitly asks.
+Apply the per-field comparison policy from [`references/capabilities.md`](references/capabilities.md) to reconcile the rendered output against the parsed script capabilities (must-match → auto-edit, suggested-default → ask, user-controlled → leave untouched).
 
 ### 4. Confirm & execute
 

skills/run-automation-suite/references/capabilities.md

@@ -0,0 +1,57 @@
+# Capabilities reference
+
+This document is the reference for the capability fields the `run-automation-suite` skill parses from local Appium test scripts and reconciles against Kobiton device-cloud requirements.
+
+The skill body in `SKILL.md` orchestrates the parsing flow; this reference catalogs the field set, the per-field comparison policy, and the Appium-runtime special-case handling. Loaded on-demand by Claude when capability-detail context is needed; not loaded as part of the default skill body.
+
+## Capability fields parsed from the user's script
+
+The skill extracts the following capability values from the test script source code:
+
+| Field | Notes |
+|---|---|
+| `platformName` | Android / iOS |
+| `udid` | hardcoded or parameterized |
+| `app` | app URL or kobiton-store reference |
+| `sessionName`, `sessionDescription` | Kobiton session metadata |
+| `automationName` | UiAutomator2, XCUITest, etc. |
+| `browserName` | if browser-based test |
+| `deviceOrientation` | portrait / landscape |
+| Any `kobiton:*` vendor extensions | especially `kobiton:runtime` (see special-case section below) |
+
+The skill identifies how the UDID is passed into the script (CLI argument, environment variable, or hardcoded) so it can be overridden with the device the user selected in workflow Step 2.
+
+## Per-field comparison policy after rendering
+
+After running `scripts/render-capabilities.js`, the skill compares the rendered JSON capabilities against the parsed script capabilities and applies one of three policies per field:
+
+### Must-match (auto-edit)
+
+Fields: `platformName`, `platformVersion`, `appium:udid`, `appium:deviceName`, `appium:app` / `browserName`, `appium:automationName`.
+
+If different from the rendered output: show what will change and edit the script automatically. These must match the selected device and app — divergence will break the run.
+
+### Suggested defaults (ask first)
+
+Fields: `kobiton:sessionName`, `kobiton:sessionDescription`, `kobiton:deviceOrientation`, `kobiton:captureScreenshots`, `appium:noReset`, `appium:fullReset`.
+
+If different from the rendered output or missing: show the diff and ask the user before changing. The user may have intentionally set different values.
+
+### User-controlled (leave untouched)
+
+Any capabilities in the user's script that are not in the rendered output. Never inject or modify `kobiton:runtime` unless the user explicitly asks (see special-case below).
+
+## Appium runtime — special-case handling
+
+Check if the script contains `'kobiton:runtime': 'appium'` or equivalent.
+
+- If it does **NOT**, do not inject it. The default Kobiton runtime will be used.
+- Only if the user explicitly asks to use the Appium runtime should `'kobiton:runtime': 'appium'` be added to the script's capabilities.
+
+This is a deliberate opt-in — silent injection of `kobiton:runtime` would change which test runner Kobiton dispatches and may produce surprising results for users who were relying on the default.
+
+## Related references
+
+- `references/templates/appium.ejs` — the EJS template `render-capabilities.js` consumes to emit the rendered capabilities JSON
+- `scripts/render-capabilities.js` — the renderer (the only runtime code in this skill); reads the template, applies CLI flags + defaults, emits JSON
+- `scripts/render-capabilities.test.js` — vitest suite for the renderer