# Template Skills: `/run-ui` and `/tutorial`

## Why this note exists

This sync introduces two new template skills and a project-wide tone-block in the always-loaded `agent-start-here` rule:

- **`/run-ui`** -- new skill at `.claude/skills/run-ui/SKILL.md`. One-command path to start the project's Vite dev server on port `4300` in the background. Probes the port, branches on free/own-vite/other-holder, asks before killing a non-vite holder, polls Vite stdout for `Local:` / `ready in`, then surfaces the URL and the background shell ID. Resolves the `strictPort: true` failure mode introduced by the `2026-05-02` WorkOS hardcode train -- before this skill, port collisions were a hard manual debug.
- **`/tutorial`** -- new skill at `.claude/skills/tutorial/{SKILL,vibe-coder,technical,progress-template}.md`. Persona-aware onboarding that forks at first invocation into a `vibe-coder` track (zero technical vocabulary, agent does all the work) or a `technical` track (full SDK depth, code-first). The choice persists to `.claude/memory/profile.md` and ships a tone block applied project-wide for the rest of every session.
- **`agent-start-here.md` Project Profile section** -- the always-loaded entrypoint rule now reads `profile.md` at session start and applies the per-track tone block to ALL agent output, not just inside `/tutorial`. This is the load-bearing change that lets `/tutorial` actually flip agent behavior across the whole project.

The project-owned `CLAUDE.md` Slash Commands table has a new `/tutorial` row in the template, but `CLAUDE.md` is verify-only on `/git-sync` -- derived projects own that file and need to add the row themselves if they want it documented.

This sync moves three pieces into derived projects:

- `.claude/skills/run-ui/SKILL.md` -- new file, replace-all surface, lands automatically
- `.claude/skills/tutorial/{SKILL,vibe-coder,technical,progress-template}.md` -- new files, replace-all surface, lands automatically
- `.claude/rules/agent-start-here.md` -- replace-all surface, the Project Profile section lands automatically

## Applies to

All template-derived projects. There are no surface preconditions -- the new skills do not depend on a particular org-model shape, feature set, or workspace topology. Operations-only projects with no `ui/` will receive `/run-ui` but it will not be useful in that context (no Vite dev server to launch); leaving it installed is harmless.

`agent-start-here.md` is replace-all: any project that hand-edited that file will lose those local edits on this sync. Run `git diff .claude/rules/agent-start-here.md` after `/git-sync` and re-apply local customizations if needed -- the template version assumes no project-local changes.

## Required actions

1. Pull template changes with `/git-sync` after this train publishes so the new skills and the `agent-start-here.md` Project Profile section reach the project.

2. Optionally run `/tutorial` to set the project's persona track. The first run asks one gate question (`vibe-coder` vs `technical`) and writes the choice to `.claude/memory/profile.md`. Subsequent runs go straight to the menu. If you skip this, the agent behaves normally and prompts you to consider running `/tutorial` only when relevant.

3. If you want the `/tutorial` row visible in the project's own Slash Commands table, manually add a row to `CLAUDE.md` (project-owned, not overwritten by `/git-sync`):

   ```
   | `/tutorial` | Guided onboarding -- picks one of two tracks (vibe-coder for non-technical users, technical for developers) and walks through the menu interactively |
   ```

4. If the project hand-edited `.claude/rules/agent-start-here.md` for project-local agent behavior, diff against the new template version and re-apply those edits on top of the new Project Profile section. The replace-all behavior of this file is unchanged from prior trains.

5. Optionally run `/run-ui` at the start of UI work. It is an explicit ask to start the dev server, not an ambient hook -- there is no behavior change unless you invoke it.

## Verification

After upgrading:

- `.claude/skills/run-ui/SKILL.md` exists and is non-empty.
- `.claude/skills/tutorial/{SKILL,vibe-coder,technical,progress-template}.md` all exist and are non-empty.
- `.claude/rules/agent-start-here.md` includes a `## Project Profile` section near the top that references `.claude/memory/profile.md` and the `vibe-coder` / `technical` tracks.
- Running `/run-ui` from a UI-bearing project either starts Vite on `4300` and reports the URL, or detects a port holder and asks before proceeding.
- Running `/tutorial` for the first time asks the gate question and writes `.claude/memory/profile.md`. Running it a second time skips the question and shows the menu.
- For a project that ran `/tutorial`: the agent's tone in subsequent (non-`/tutorial`) responses reflects the chosen track per the tone block in `profile.md`. Vibe-coder track: no technical vocabulary, no slash-command surfacing. Technical track: real paths, code-first, no over-explanation.

## Not handled by /git-sync

`/git-sync` does not:

- create or update `.claude/memory/profile.md`. The file is created on first `/tutorial` invocation. If a project never runs `/tutorial`, the agent operates as if no profile exists -- normal default behavior.
- write the new `/tutorial` row into the project's own `CLAUDE.md` Slash Commands table. `CLAUDE.md` is project-owned (verify-only); the row is a manual edit if the project wants it documented.
- preserve project-local edits to `.claude/rules/agent-start-here.md`. That file is replace-all. Re-apply local customizations after the sync if any exist.
- run smoke tests for either skill. The `/tutorial` task doc explicitly defers smoke testing to a fresh-scaffold pass; `/run-ui` is exercised on first user invocation, not via sync verification.
