/forge-app-builder

name: forge-app-builder
description: Guides building, deploying, troubleshooting, and installing Atlassian Forge apps — custom extensions built with the Forge CLI (forge create, forge deploy, forge install). Use when the user wants to create a Forge app (issue panels, dashboard gadgets, Confluence macros, global pages), is encountering Forge CLI errors or deployment issues (e.g. forge install failures, environment errors), or needs help with Forge-specific concepts like resolvers, UI Kit, manifest scopes, or developer spaces. Do not use for general Jira configuration, automation rules, JQL queries, or Atlassian REST API usage outside of a Forge app context.
license: Apache-2.0
labels:
  - confluence
  - jira
  - bitbucket
  - atlassian
  - forge
maintainer: amoore
namespace: cloud

Forge App Builder

**When building a Forge app, the agent MUST complete this workflow in order. Do not skip steps. Do not substitute manual instructions for running the scripts below.**

Critical Rules

1. **Always use `forge create`** to scaffold apps — it registers the app and generates a valid app ID 2. **Never manually scaffold** — apps without valid app IDs cannot be deployed 3. **If `forge create` fails, STOP** — inform the user and provide the manual command 4. **Never ask for API tokens in chat** — direct users to run `forge login` in their terminal and enter credentials there 5. **Always ask the user to choose** when multiple options exist (developer spaces, sites) — never pick on their behalf 6. **Always ask the user for their Atlassian site URL during installation** — never try to discover it from other apps, environment variables, or any other source 7. **Always run the deploy script for deploy and install** — do not give the user only manual `forge deploy` / `forge install` commands as the primary outcome; run `scripts.deploy_forge_app.py` yourself 8. **Set `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-app-builder` on `forge` commands run for this skill** — prefix `forge` invocations with this env var: ones you run in the shell (e.g. `forge developer-spaces list`, `forge lint`) **and the interactive `forge create` command you hand the user as a fallback**. The bundled scripts set it automatically; other commands shown in this skill omit it for brevity — add it when you run them. The only exclusions are `forge login` and `forge tunnel` (user-run auth / live-dev commands).

MCP Server Prerequisites

This skill works best with the following MCP servers. The scripts and CLI workflow function without them, but the agent will lack access to up-to-date Forge documentation for template selection, module configuration, and code patterns.

| MCP Server | Required? | Purpose | | ------------- | -------------------- | ------------------------------------------------------------------------- | | **Forge MCP** | Strongly recommended | Template lookup, module discovery, manifest syntax, UI Kit/backend guides | | **ADS MCP** | Optional | Atlaskit component/token/icon lookup (Custom UI apps only) |

If MCP servers are not connected, inform the user that code guidance may be based on the model's training data and could be outdated. Recommend they verify against [developer.atlassian.com/platform/forge](https://developer.atlassian.com/platform/forge/). |

Agent Workflow

**Complete steps 0–5 in order. Run the scripts yourself; do not only instruct the user to run them.**

Step 0: Prerequisites (Install Automatically If Missing)

**Before any other steps**, call the `forge-development-guide` tool to get the current Node.js version requirement and CLI setup instructions. Then check and install prerequisites:

1. **Node.js** — Run `node -v`. If missing or below the version specified in the development guide:

• **macOS (Homebrew):** `brew install node`
• **nvm:** `nvm install <version>` then `nvm use <version>`
• **fnm:** `fnm install <version>` then `fnm use <version>`
• **Other:** [https://nodejs.org](https://nodejs.org) (LTS)

2. **Forge CLI** — Run `forge --version`. If missing:

   npm install -g @forge/cli

3. **Forge login** — Run `forge whoami`. If not logged in:

• **Never ask for or accept API tokens in chat** — tokens are sensitive; the user must enter them only in their terminal
• Direct the user to create an API token: [https://id.atlassian.com/manage/api-tokens](https://id.atlassian.com/manage/api-tokens)
• Tell the user to run `forge login` **in their own terminal** (not via the agent). The CLI will prompt for:
• Atlassian email
• API token (paste only in the terminal when prompted)
• Example message: *"You need to log in to Forge. Create an API token at [https://id.atlassian.com/manage/api-tokens](https://id.atlassian.com/manage/api-tokens), then run `forge login` in your terminal. Enter your email and token when prompted — do not paste them here."*
• After the user confirms they've logged in, retry the workflow

Install in order: Node.js first (required for npm), then Forge CLI, then login. Retry the workflow after installing.

Step 1: Discover Developer Spaces

ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-app-builder forge developer-spaces list --json

Step 2: Ask User to Choose Developer Space

**Do not proceed to Step 3 until the user has selected a developer space.** Present the list from Step 1 (names and IDs) and ask which space to use. If only one space exists, you may use it and briefly inform the user. Never pick one of multiple spaces on the user's behalf.

Step 3: Create App

All `python3 -m scripts.`* commands must be run from the skill directory (the directory containing this SKILL.md file). Derive it from the SKILL.md path provided in the system prompt. Use `python3` on macOS if `python` is not available.

Run from the skill directory. The `--director