Add forge-onboarding skill

Guided end-to-end onboarding for first-time Forge developers.
Two-loop arc: deploy a stock Hello World Rovo Agent (Loop 1),
then customize it into "Forge Guru" — a personal Forge
companion that answers Forge questions from the official docs
(Loop 2). Hands the user off to the four-stage "Build and launch
your Forge app" doc when done.

Delegates all app-mutation forge CLI calls to forge-app-builder.

Author: rnelson2-dotcom

skills/forge-onboarding/README.md

@@ -0,0 +1,131 @@
+# Forge Onboarding Skill
+
+The **first guided experience for someone new to Atlassian Forge**, optimized for AI-native development. Takes a first-time builder from zero to a running Rovo Agent — **Forge Guru**, a permanent Forge development companion that lives on their dev site and answers Forge questions live from the official developer docs.
+
+Use this skill for your **first** Forge app. For everything after that, use `forge-app-builder`.
+
+## What Makes This Different
+
+The artifact you build is **something you keep using**, not a throwaway hello-world. Forge Guru stays on your dev site forever and answers real Forge questions:
+
+- *"What can I build with Forge?"*
+- *"Which Forge module should I use for [my idea]?"*
+- *"How do I add something to a Jira issue?"*
+- *"How do I call the Jira REST API from a Forge resolver?"*
+- *"What's the difference between UI Kit and Custom UI?"*
+
+Each answer is generated by searching Atlassian's official developer documentation live and citing the exact page — no hallucination.
+
+## ⏱ How Long This Takes
+
+- **~15 minutes** if your environment is already set up (Node.js 22+, Forge CLI, `forge login` done, developer site with Rovo enabled)
+- **~25 minutes** if the skill needs to install Node, install the Forge CLI, and provision a fresh developer site along the way
+
+Per-step time estimates appear in each section header inside the skill so users can pace themselves.
+
+## What This Skill Walks Through
+
+Progressive disclosure — one stage at a time. The onboarding is structured as a **two-loop arc**: first ship a real, minimal, working Hello World Rovo Agent end-to-end (so the user's first Forge experience is a working app they understand and can chat with), then evolve that same app into Forge Guru (so the throwaway feeling of hello-world becomes a keep-forever tool).
+
+Users see section titles (e.g. *"Deploy your first Forge app"*, *"See Hello World live"*) — the step numbers below are for internal reference only.
+
+**Setup:**
+
+0. **Welcome & frame** — Introduce Forge Guru by name in the very first line, sketch the two-loop shape of the onboarding (Set up → Loop 1 → Loop 2 → What next), and set the expectation that today's artifact is a keep-forever tool.
+1. **Set up your local machine** — Verify (and install, with permission) Node.js, the Forge CLI, and `forge login`. This is the *local* half of setup — the tools on your machine. The *Atlassian* half comes later in Step 4.
+2. **The AI-native Forge app mental model** — The four concepts of every Forge app, presented as a scannable table: **manifest**, **modules & extension points**, **the Context Moat (Teamwork Graph + MCP)**, and **backend (actions & resolvers)**. Includes a 6-step "what actually happens when you chat with a Rovo Agent" walkthrough.
+3. **Meet Forge Guru** — Purely conceptual: introduce the specific agent we're building (what it is, what you'll be able to ask it, what it's built from, why it's worth keeping). No user inputs collected here.
+4. **Set up your Atlassian environment** — A super-step with three symmetric micro-beats, each in its own visible section so no beat disappears into narration. This is the *Atlassian* half of setup — where the app will live, who will own it, and where it'll run. The *local* half was handled in Step 1.
+   - **4a — Choose where your Forge agent will live** (working directory on disk).
+   - **4b — Pick a Developer Space to register the app in** (introduces what a Developer Space is, then queries the user's via `forge developer-spaces list --json` and lets them pick).
+   - **4c — Pick the Atlassian dev site where the app will be installed** (moved out of the pre-loop flow so it sits alongside the other two "what does the scaffold need to know?" questions; user can bring their own URL or run `forge site provision` for a free demo site with Rovo pre-activated).
+
+**Loop 1 — ship a stock Hello World Rovo Agent:**
+
+5. **Scaffold your Rovo Agent** — Delegate to the **`forge-app-builder`** skill's non-interactive helper (`scripts.create_forge_app --template rovo-agent-rovo --name forge-guru`) to scaffold a stock Hello World Rovo Agent from the official template. A short teaching beat at the end of this step reinforces how `forge create` names things: the `--name` flag locks three names to the same value at once — the folder on disk (`forge-guru/`), the app's immutable ID in the Developer Console (`forge-guru`), and the Rovo Agent's display name (`Forge Guru`). The name doesn't change again — Loop 2 only customizes what Guru *does*, not what it's called.
+6. **Take a look at what the scaffold gave us** — Two messages, one per file. Chat carries a compact concept summary (what the file is for, what blocks it contains, how the pieces connect, cross-referenced to Step-3 concepts). Each message ends with the exact path to the file on disk so a curious user can open it in their editor to see the syntax. **No files are modified in this step** — the on-disk scaffold stays exactly as `forge create` produced it until Step 9.
+7. **Deploy your first Forge app** — Delegate to `scripts.deploy_forge_app`, which runs `forge deploy` + `forge install` in one non-interactive call (with `npm install` handled automatically as part of deploy). Explicit user confirmation required. First Forge deploy of the user's career — celebrate it.
+8. **See Hello World live on your dev site** — Click-by-click instructions for opening Rovo, finding the agent, and chatting with it. First confidence beat — the user sees their own code respond in Rovo.
+
+**Loop 2 — turn the same app into Forge Guru:**
+
+9. **Turn Hello World into Forge Guru** — Two per-file confirm-gates, one for `manifest.yml` and one for `src/index.js`. Chat carries a compact **change list** (what's changing and why, cross-referenced to Step-3 concepts) — not a full target-file paste. Escape hatch: if the user says *"show me the file"* the agent pastes the full target YAML/JS from the pinned reference. On confirm, files are overwritten with **clean, production-shaped Guru code** (short 2-line header + code) so the app now looks like a real Forge app. **The `src/index.js` gate also updates `package.json`** as an inline side-effect — the new Guru handler imports `@forge/api`, which the stock scaffold may not declare as a dependency, so the agent adds it and tells the user in the same message. All pinned target-file YAML in the skill is hard-wrapped so every source line is ≤160 characters — this keeps the redeploy in Step 10 from failing `forge lint`.
+10. **Redeploy — this time as Forge Guru** — Same `scripts.deploy_forge_app` helper, second time. `forge deploy` picks up the new `@forge/api` dependency automatically as part of its install-and-deploy pipeline. The daily-rhythm beat — the user sees that iterating on a Forge app is just *edit → redeploy → see it live*.
+11. **See Forge Guru live** — Same shape as Step 8, but this time the user asks Guru a real Forge question and gets back an answer with a cited doc link.
+12. **What next — the rest of your Forge journey** — Framed around Atlassian's official [*Build and launch your Forge app*](https://developer.atlassian.com/platform/forge/build-and-launch-your-forge-app/) doc: the user just finished the guided *Build* stage; here's the map for *Prepare to publish*, *Distribute*, and *Grow*. Includes a *"Get inspired"* section that points at three open-source Forge apps on [atlassian-labs/forge-inspired](https://github.com/atlassian-labs/forge-inspired) (Sprint Ready Agent, Smart Workflow Follow-up, Team Pulse Board), plus specialist skills routed to the stage where they help (`forge-security-review` / `forge-app-review` / `forge-cost-optimizer` under *Prepare to publish*; `forge-app-builder` / `forge-connector` / `forge-debugger` for continuing to build). Guru is the "one Rovo chat away" CTA.
+
+## Design Principles
+
+- **Outcome over information** — every step moves the user toward a Guru they'll keep using.
+- **Progressive disclosure** — one stage at a time, confirm success before advancing.
+- **AI guides, not hides** — the skill actively performs setup where possible, narrating what it's doing and why.
+- **Make the first success visible** — deploying isn't the win; asking Guru a real question and getting a cited answer is.
+- **Build a keep-forever artifact** — the tutorial's output is genuinely useful on day 2, day 20, and day 200.
+- **Verify everything against the Forge MCP** — never rely on remembered CLI commands, module names, or manifest properties.
+
+## Prerequisites
+
+The skill handles missing prerequisites for you (with permission), but if you want to prep manually:
+
+- **Node.js 22+** — `node -v` (the skill will install via `nvm` if missing)
+- **Forge CLI** — `npm install -g @forge/cli@latest` (the skill will install if missing; needs a version that supports Rovo Agent templates)
+- **An Atlassian account** — needed for `forge login`
+- **Rovo activated on the target site** — free demo sites from `forge site provision` have Rovo enabled by default
+
+## Installation
+
+This skill ships inside the **[Forge Skills](https://github.com/atlassian/forge-skills)** plugin bundle (`skills/forge-onboarding/`). Install that repo as a plugin in your editor or CLI to get the skill plus the Forge MCP configuration — the skill assumes the Forge MCP is available for verification lookups.
+
+See the [forge-skills README](https://github.com/atlassian/forge-skills/blob/main/README.md) for Cursor, Claude Code, Gemini, Codex, and Copilot CLI setup.
+
+### Sibling skill dependency
+
+This onboarding skill is a **thin, guided wrapper** around the `forge-app-builder` skill's helper scripts. Every step that actually mutates the Forge platform is delegated to `forge-app-builder` rather than reimplemented here:
+
+| `forge-app-builder` helper | Used in | What it does |
+|---|---|---|
+| `scripts.create_forge_app` | Step 5 (Scaffold your Rovo Agent) | Non-interactive `forge create` — registers a new app, drops the starter project, bypasses the interactive template picker |
+| `scripts.deploy_forge_app` | Step 7 (Deploy Hello World) and Step 10 (Redeploy as Forge Guru) | Non-interactive `forge deploy` + `forge install` in one call — invoked twice, once per loop of the arc |
+| `scripts.list_templates` | Step 5 (fallback path) | Validates the Rovo Agent template name if the CLI ever renames it |
+
+The onboarding skill only invokes read-only Forge CLI commands directly — `forge --version`, `forge whoami`, `forge site provision`, `forge developer-spaces list`, `forge install list`, `forge logs`. Everything else routes through the helpers above.
+
+Both skills ship together in the [Forge Skills](https://github.com/atlassian/forge-skills) plugin bundle, so installing the bundle covers you. **If you're symlinking or hand-copying skills individually, install `forge-app-builder` alongside `forge-onboarding`** — otherwise Step 5 (Scaffold) will stop with a dependency-check error and ask you to install the sibling skill before continuing.
+
+## How to Trigger
+
+In your agent chat, use any of these phrases:
+
+- "Onboard me to Forge"
+- "Build my first Rovo Agent"
+- "Build my first AI app in Atlassian"
+- "Forge hello world" / "Rovo agent hello world"
+- "I want to build an agent that lives in Jira/Confluence"
+- "I've never used Forge before, walk me through it"
+
+## When NOT to Use
+
+This skill is only for **first-time** Forge users. Once you have Guru running, route to the appropriate specialist skill:
+
+| Situation                                         | Skill                    |
+| ------------------------------------------------- | ------------------------ |
+| Extending an existing Forge app                   | `forge-app-builder`      |
+| Debugging a broken deploy or Agent               | `forge-debugger`         |
+| Pre-release review                                | `forge-app-review`       |
+| Security review or static analysis                | `forge-security-review`  |
+| Cost / consumption optimization                   | `forge-cost-optimizer`   |
+| Teamwork Graph connector (ingest external data)  | `forge-connector`        |
+
+## Scripts
+
+This skill has no scripts of its own — it's purely instructional so the user sees each command as it runs and understands the mechanics. Every step that mutates Forge state delegates to a `forge-app-builder` helper: `scripts.create_forge_app` for the scaffold (Step 5), and `scripts.deploy_forge_app` for deploy + install — invoked twice, once for the stock Hello World in Step 7 and again for Forge Guru in Step 10. See the [Sibling skill dependency](#sibling-skill-dependency) section above.
+
+## See Also
+
+- [Forge documentation](https://developer.atlassian.com/platform/forge/)
+- [Rovo modules overview](https://developer.atlassian.com/platform/forge/manifest-reference/modules/rovo-index/)
+- [`rovo:agent` manifest reference](https://developer.atlassian.com/platform/forge/manifest-reference/modules/rovo-agent/)
+- [Build a Rovo Agent hello world app](https://developer.atlassian.com/platform/forge/build-a-hello-world-rovo-agent/)
+- [Runtime egress permissions](https://developer.atlassian.com/platform/forge/runtime-egress-permissions/)
+- [Forge CLI reference](https://developer.atlassian.com/platform/forge/cli-reference/)
+- [Provision a demo development site](https://developer.atlassian.com/platform/forge/provision-a-demo-development-site/)