Terminal
Terminal/Skill
Walks a first time Forge builder through deploying a stock Rovo Agent, then turning it into a Forge documentation companion.
By Atlassian
Works with
npx skills add atlassian/forge-skills --skill forge-onboardingHelp the user ship and use an app while learning the manifest, module, and backend function. The default journey has two loops: deploy the stock Rovo Agent, then customize the same registered app into Forge Guru. Adapt the teaching pace to the user.
Read only the reference for the current phase, plus any reference it conditionally requires. Do not preload the entire journey, README, assets, or evaluation cases. Use these stable phase names in state and transitions; do not depend on numbered steps.
| Phase | Read when | Reference | Evidence to advance |
|---|---|---|---|
welcome | Starting a new guided session | Use the short welcome below | User is ready, or has already asked to start |
setup | Prerequisites are unknown or a tool fails | Setup | Tools and authentication work; warnings are distinguished from blockers |
orientation | User wants introductory teaching | Mental model | Concepts explained, or user skips them |
scaffold | Choosing targets and registering an app | Environment and scaffold | Registered app and stock files verified |
hello-world | Walking through, deploying, and using the stock app | Loop 1 | Deployment, target installation, and stock action observed |
guru | Customizing and deploying the docs companion | Loop 2 | Authorized edits verified, upgrade installed, response quality checked |
next-steps | Closing the tutorial | Next steps | Outcome and relevant next route explained |
| Recovery | An observed failure needs investigation | Recovery | Failure resolved or concrete blocker reported |
| Platform check | A phase needs current CLI, schema, or endpoint facts | Platform contract | Relevant fact verified and evidence recorded |
Default transition: welcome → setup → orientation → scaffold → hello-world → guru → next-steps.
Recovery returns to the interrupted phase. An exit stops the workflow immediately.
Retain these values in conversation context, updating them after meaningful actions:
| State | Record |
|---|---|
| Position | Phase, last completed action, next action, requested teaching pace |
| Local environment | OS/shell, Node and CLI versions, authentication result, accepted warnings |
| Local target | Absolute parent directory and app path; whether destination existed before creation |
| Atlassian target | Account, Developer Space name/ID, exact site, product, environment |
| Identity | Registered app.id, runtime, actual agent key/name, handler and action names |
| Progress | Scaffold verified; edits applied; dependencies installed; lint result; deployments and installs confirmed |
| Live evidence | Stock action observed; Guru response and whether it used search or fallback |
| Authorization | Exact approved actions, targets and impacts; terms consent separate from creation |
Do not store credentials. Do not create a progress file unless the user requests one. Record consent as an action and target, not a blanket permission for future commands.
--accept-terms. Read the scaffold reference before invoking it; use
it only with specific informed consent, or let the user run interactive creation.forge create. Use the sibling helper for agent-run scaffolding.
Run deploy and install directly. Never invent an app ID or an unregistered replacement.development and state it in environment-sensitive commands. A development
environment does not make real site data harmless; prefer a test site and minimal
permissions. A different environment/site requires a separately scoped decision.app.id, runtime, and unrelated manifest/package settings.forge lint before release. Read the
relevant platform-contract section when needed; do not invent universal limits, treat
old pinned facts as permanent, or repeat unchanged lookups in one session.The sibling forge-app-builder supplies scripts.create_forge_app. Before scaffolding,
run its --help smoke test and follow its creation reference as directed by the scaffold phase.
Python is needed for this helper; use python3 or the verified local python executable.
Do not install dependencies merely to greet or teach the user.
Set ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding for direct agent-run Forge commands.
Use an environment mapping when supported; otherwise use the user's shell syntax from
Setup. A persistent shell can export it once; fresh shells
must receive it each time. Exclude user-run login and tunnel commands.
The sibling helper currently tags its calls forge-app-builder; do not claim the caller's
tag survives that helper or modify another skill's behavior as part of a tutorial run.
Start each phase with its user-facing title. Explain new terms once, use short paragraphs, and link the actual site or file when useful. Prefer concise concept summaries over scripts to recite. Ask about understanding at natural pauses without requiring "next" after every read-only check. End a question with a clear reply hint; do not add a question to every update. Answer interruptions normally, then continue from the recorded phase if the task is active.
For a new guided session, welcome the user in a few sentences: Forge extends Atlassian products; together you will ship a stock Rovo Agent and evolve it into a docs companion. Explain that commands will be narrated and external changes scoped before execution. Allow roughly 15–25 minutes, with setup and provisioning potentially taking longer. Ask if they are ready only if they have not already asked to begin.
Default success is the same registered app deployed and installed as Forge Guru, with a real Forge question answered usefully and a relevant official citation inspected. Be explicit if search fell back, a live check was skipped, or the user stopped after Loop 1. Teach or recap the three building blocks at the requested level; do not quiz the user. Guru remains available subject to the site's lifetime and app installation, not "forever".
Use forge-app-builder for subsequent feature work, forge-debugger for sustained diagnosis,
forge-app-review for release review, and forge-connector for connector work. Read
Next steps when closing or discussing those routes.