Back to Details

forge-app-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Forge App Builder

Forge 应用构建器

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.
构建Forge应用时，代理必须按顺序完成以下工作流，不得跳过步骤，不得用手动说明替代运行以下脚本。

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
  1. **始终使用
    forge create
    **来生成应用脚手架——它会注册应用并生成有效的应用ID
  2. 切勿手动搭建脚手架——没有有效应用ID的应用无法部署
  3. 如果
    forge create
    失败，请停止操作    ——告知用户并提供手动命令
  4. 切勿在聊天中索要API令牌——引导用户在终端中运行
    forge login
    并在那里输入凭据
  5. 当存在多个选项（开发者空间、站点）时，始终让用户选择——切勿代为选择
  6. 安装期间始终向用户索要Atlassian站点URL——切勿尝试从其他应用、环境变量或任何其他来源获取该URL
  7. 部署和安装时始终运行部署脚本——不要仅向用户提供手动
    forge deploy
    / 
    forge install
    命令作为主要操作；请自行运行
    scripts.deploy_forge_app.py

MCP Server Prerequisites

MCP服务器前置条件

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 ServerRequired?Purpose
Forge MCPStrongly recommendedTemplate lookup, module discovery, manifest syntax, UI Kit/backend guides
ADS MCPOptionalAtlaskit 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. |
本技能在搭配以下MCP服务器使用时效果最佳。即使没有这些服务器，脚本和CLI工作流仍可运行，但代理将无法获取最新的Forge文档以进行模板选择、模块配置和代码模式参考。
MCP服务器是否需要？用途
Forge MCP强烈推荐模板查找、模块发现、清单语法、UI Kit/后端指南
ADS MCP可选Atlaskit组件/令牌/图标查找（仅适用于Custom UI应用）
如果未连接MCP服务器，请告知用户代码指导可能基于模型的训练数据，可能已过时。建议他们前往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.
按顺序完成步骤0–5。请自行运行脚本；不要仅指导用户运行脚本。

Step 0: Prerequisites (Install Automatically If Missing)

步骤0：前置条件（缺失时自动安装）

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 (LTS)
  1. Forge CLI — Run 
    forge --version
    . If missing:
bash
 npm install -g @forge/cli
  1. 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
  • 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, 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.
在执行任何其他步骤之前，调用
forge-development-guide
工具获取当前Node.js版本要求和CLI设置说明。然后检查并安装前置条件：
  1. Node.js — 运行
    node -v
    。如果缺失或版本低于开发指南中指定的版本：
  • macOS（Homebrew）： 
    brew install node
  • nvm： 
    nvm install <version>
    然后 
    nvm use <version>
  • fnm： 
    fnm install <version>
    然后 
    fnm use <version>
  • 其他： https://nodejs.org（LTS版本）
  1. Forge CLI — 运行
    forge --version
    。如果缺失：
bash
 npm install -g @forge/cli
  1. Forge登录 — 运行
    forge whoami
    。如果未登录：
  • 切勿在聊天中索要或接收API令牌——令牌属于敏感信息；用户必须仅在自己的终端中输入
  • 引导用户创建API令牌：https://id.atlassian.com/manage/api-tokens
  • 告知用户在自己的终端中运行
    forge login
    （而非通过代理）。CLI将提示输入：
    • Atlassian邮箱
    • API令牌（仅在终端提示时粘贴）
  • 示例消息："您需要登录Forge。请前往https://id.atlassian.com/manage/api-tokens创建API令牌，然后在终端中运行
    forge login
    。提示时输入您的邮箱和令牌——请勿在此处粘贴。"
  • 用户确认登录后，重新执行工作流
安装顺序：先安装Node.js（npm的必备条件），然后安装Forge CLI，最后登录。安装完成后重新执行工作流。

Step 1: Discover Developer Spaces

步骤1：发现开发者空间

bash
forge developer-spaces list --json
bash
forge developer-spaces list --json

Step 2: Ask User to Choose Developer Space

步骤2：让用户选择开发者空间

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.
**在用户选择开发者空间之前，请勿进入步骤3。**展示步骤1中的列表（名称和ID）并询问用户使用哪个空间。如果只有一个空间，您可以直接使用并简要告知用户。当存在多个空间时，切勿代为选择。

Step 3: Create App

步骤3：创建应用

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 
--directory
flag sets the parent directory under which the app folder (named after 
--name
) will be created. The script 
cd
s into that directory before running 
forge create
, so the app appears as a subdirectory (e.g. 
<parent-directory>/<app-name>/
). If omitted, the app is created under the current directory.
bash
python3 -m scripts.create_forge_app \
  --template <template> \
  --name <app-name> \
  --dev-space-id <selected-id> \
  --directory <parent-directory>
To find the right template for the user's needs:
  • Call 
    list-forge-modules
    to identify the appropriate module type
  • Call 
    search-forge-docs
    with a query like "template for " to find the matching template name
Validate a template: 
python3 -m scripts.list_templates --validate <name>
List all templates: 
python3 -m scripts.list_templates --list
所有
python3 -m scripts.
*命令必须从技能目录（包含本SKILL.md文件的目录）运行。从系统提示中提供的SKILL.md路径推导该目录。如果macOS中
python
不可用，请使用
python3
。
从技能目录运行。
--directory
标志设置应用文件夹（以
--name
命名）将创建于其中的父目录。脚本会先切换到该目录，然后运行
forge create
，因此应用将作为子目录出现（例如
<parent-directory>/<app-name>/
）。如果省略该标志，应用将创建于当前目录下。
bash
python3 -m scripts.create_forge_app \
  --template <template> \
  --name <app-name> \
  --dev-space-id <selected-id> \
  --directory <parent-directory>
为用户需求选择合适的模板：
  • 调用
    list-forge-modules
    确定合适的模块类型
  • 调用
    search-forge-docs
    并使用类似"template for "的查询语句查找匹配的模板名称
验证模板：
python3 -m scripts.list_templates --validate <name>
列出所有模板：
python3 -m scripts.list_templates --list

Step 4: Customize Code

步骤4：自定义代码

After 
forge create
succeeds:
bash
cd <app-name>
npm install
forge create
成功后：
bash
cd <app-name>
npm install

UI Kit vs Custom UI — Choose the Right Tools

UI Kit vs Custom UI — 选择合适的工具

Before writing any UI code, determine which approach the app uses. Getting this wrong causes import errors and broken builds.
  • UI Kit (most 
    forge create
    templates): manifest uses 
    render: native
    or code imports from 
    @forge/react
    . Use 
    forge-ui-kit-developer-guide
    as the ONLY UI reference. Do NOT suggest 
    @atlaskit/
    * imports — they won't work.
  • Custom UI: manifest has 
    resource
    pointing to a 
    static/
    directory. Use ADS MCP tools (
    ads_plan
    , 
    ads_get_components
    , 
    ads_get_all_icons
    ) for component discovery. Do NOT use 
    forge-ui-kit-developer-guide
    — it describes a different API.
在编写任何UI代码之前，请确定应用使用的方式。选择错误会导致导入错误和构建失败。
  • UI Kit（大多数
    forge create
    模板）：清单使用
    render: native
    或代码从
    @forge/react
    导入。仅使用
    forge-ui-kit-developer-guide
    作为UI参考。请勿建议使用
    @atlaskit/
    *导入——它们无法正常工作。
  • Custom UI：清单包含指向
    static/
    目录的
    resource
    。使用ADS MCP工具（
    ads_plan
    、
    ads_get_components
    、
    ads_get_all_icons
    ）进行组件发现。请勿使用
    forge-ui-kit-developer-guide
    ——它描述的是不同的API。

Knowledge tools for implementation

实现用知识工具

  • forge-ui-kit-developer-guide
    — Frontend components (UI Kit only)
  • ads_plan
    / 
    ads_get_components
    — Component and token lookup (Custom UI only)
  • forge-backend-developer-guide
    — Backend resolvers and APIs
  • forge-app-manifest-guide
    — Manifest configuration
  • search-forge-docs
    — Search for specific APIs or props
  • forge-ui-kit-developer-guide
    — 前端组件（仅适用于UI Kit）
  • ads_plan
    / 
    ads_get_components
    — 组件和令牌查找（仅适用于Custom UI）
  • forge-backend-developer-guide
    — 后端解析器和API
  • forge-app-manifest-guide
    — 清单配置
  • search-forge-docs
    — 搜索特定API或属性

Step 5: Deploy and Install (run the deploy script)

步骤5：部署和安装（运行部署脚本）

You MUST run the deploy script — do not only paste manual 
forge deploy
/ 
forge install
commands for the user to run. Execute the script from the skill directory.
  • If you have the user's Atlassian site URL (e.g. they provided it earlier or in the request), run in one go:
bash
python3 -m scripts.deploy_forge_app \
  --app-dir <app-directory> \
  --site <site-url> \
  --product <jira|confluence>
  • If you do not have the site URL yet: run deploy only, then ask for the site, then run again to install:
bash
undefined
您必须运行部署脚本——不要仅粘贴手动
forge deploy
/ 
forge install
命令让用户运行。从技能目录执行脚本。
  • 如果您已有用户的Atlassian站点URL（例如用户之前或在请求中提供过），一次性运行：
bash
python3 -m scripts.deploy_forge_app \
  --app-dir <app-directory> \
  --site <site-url> \
  --product <jira|confluence>
  • 如果您还没有站点URL：先仅运行部署，然后询问用户站点URL，再再次运行以完成安装：
bash
undefined

1) Deploy only

1) 仅部署

python3 -m scripts.deploy_forge_app
--app-dir <app-directory>
--product <jira|confluence>
--deploy-only
python3 -m scripts.deploy_forge_app
--app-dir <app-directory>
--product <jira|confluence>
--deploy-only

2) Ask the user: "What is your Atlassian site URL (e.g. yourcompany.atlassian.net)?"

2) 询问用户："您的Atlassian站点URL是什么（例如yourcompany.atlassian.net）？"

3) After they reply, run again with their site to complete install

3) 用户回复后，使用他们提供的站点再次运行以完成安装

python3 -m scripts.deploy_forge_app
--app-dir <app-directory>
--site <site-url>
--product <jira|confluence>
--skip-deps

**Always ask the user for their site URL** when needed for install; never try to discover it. If scopes changed from a previous install, add `--upgrade` to the install (or run the script again with `--site` and the script will handle it; for manual upgrade use `forge install ... --upgrade`).
python3 -m scripts.deploy_forge_app
--app-dir <app-directory>
--site <site-url>
--product <jira|confluence>
--skip-deps

**当安装需要时，始终向用户索要站点URL**——切勿尝试自行获取。如果作用域与之前的安装相比发生变化，请在安装时添加`--upgrade`（或再次运行带`--site`的脚本，脚本会自动处理；手动升级请使用`forge install ... --upgrade`）。

Cross-product installation

跨产品安装

When an app uses scopes from multiple products (e.g. a Confluence macro that also reads Jira data), the deploy script automatically detects the required products from the manifest scopes and installs on all of them. The 
--product
flag sets the primary product; the script adds any additional products found in the scopes.
If you need to install manually, run 
forge install
once per product:
bash
forge install --non-interactive --site <site-url> --product confluence -e development
forge install --non-interactive --site <site-url> --product jira -e development
当应用使用多个产品的作用域时（例如同时读取Jira数据的Confluence宏），部署脚本会自动检测清单作用域中所需的产品并在所有相关产品上安装。
--product
标志设置主产品；脚本会添加作用域中发现的所有其他产品。
如果需要手动安装，请为每个产品运行一次
forge install
：
bash
forge install --non-interactive --site <site-url> --product confluence -e development
forge install --non-interactive --site <site-url> --product jira -e development

Handling 
forge create
Failures

处理
forge create
失败

When 
forge create
fails, never attempt workarounds or manual scaffolding.
ErrorAction
Prerequisites missing (Node.js, Forge CLI)Run Step 0 install commands, then retry
"Prompts can not be meaningfully rendered"Ask user to run 
forge create
in an interactive terminal
"No developer spaces found"Direct user to https://developer.atlassian.com/console/
"directory already exists"A folder named 
<app-name>
already exists inside the parent directory. Choose a different name or remove the existing folder
Network/auth issues, not logged inDirect user to https://id.atlassian.com/manage/api-tokens, then run 
forge login
in their terminal
Any other errorShow error, ask user for guidance
Example response when it fails:
forge create needs an interactive terminal. Please run:

  forge create --template jira-dashboard-gadget my-app-name

Once created, let me know and I'll help customize it.
当
forge create
失败时，切勿尝试变通方法或手动搭建脚手架。
错误操作
前置条件缺失（Node.js、Forge CLI）运行步骤0的安装命令，然后重试
"Prompts can not be meaningfully rendered"让用户在交互式终端中运行
forge create
"No developer spaces found"引导用户前往https://developer.atlassian.com/console/
"directory already exists"父目录中已存在名为
<app-name>
的文件夹。请选择其他名称或删除现有文件夹
网络/认证问题、未登录引导用户前往https://id.atlassian.com/manage/api-tokens，然后在终端中运行
forge login
其他任何错误显示错误，询问用户的指导
失败时的示例回复：
forge create需要交互式终端。请运行：

  forge create --template jira-dashboard-gadget my-app-name

创建完成后，请告知我，我会帮助您自定义它。

Module Selection

模块选择

Call 
list-forge-modules
for a comprehensive, up-to-date list of all available modules organized by product. Then use 
search-forge-docs
with the module name for configuration details and YAML examples.
调用
list-forge-modules
获取按产品分类的所有可用模块的全面、最新列表。然后使用
search-forge-docs
并传入模块名称以获取配置详情和YAML示例。

Scripts

脚本

ScriptPurpose
scripts/create_forge_app.py
Create app with dev space selection and template validation. 
--directory
sets the parent dir (script cd's into it). Run: 
python3 -m scripts.create_forge_app
scripts/list_templates.py
List/validate all Forge templates from Atlassian registry. Run: 
python3 -m scripts.list_templates
scripts/deploy_forge_app.py
Deploy and install app (prerequisites check, npm install, lint, deploy, install). Auto-detects cross-product scopes and installs on all required products. Run: 
python3 -m scripts.deploy_forge_app
脚本用途
scripts/create_forge_app.py
结合开发者空间选择和模板验证创建应用。
--directory
设置父目录（脚本会切换到该目录）。运行：
python3 -m scripts.create_forge_app
scripts/list_templates.py
列出/验证Atlassian注册表中的所有Forge模板。运行：
python3 -m scripts.list_templates
scripts/deploy_forge_app.py
部署和安装应用（前置条件检查、npm安装、代码检查、部署、安装）。自动检测跨产品作用域并在所有所需产品上安装。运行：
python3 -m scripts.deploy_forge_app

Completion checklist

完成检查清单

Before considering the workflow done, confirm:
  • User selected developer space when more than one existed (or only one existed)
  • App was created via 
    create_forge_app
    (or user ran 
    forge create
    after a failure)
  • Code was customized and 
    npm install
    run in the app directory
  • Deploy script was executed by the agent (not only manual commands given to the user)
  • If install was needed, user was asked for site URL and the script was run with 
    --site
    (or user provided site and install completed)
  • If the app uses cross-product scopes (e.g. Confluence app reading Jira data), it was installed on all required products (the deploy script handles this automatically)
在认为工作流完成之前，请确认：
  • 当存在多个开发者空间时，用户已选择（或仅存在一个空间）
  • 应用是通过
    create_forge_app
    创建的（或用户在失败后运行了
    forge create
    ）
  • 代码已自定义且在应用目录中运行了
    npm install
  • 代理已执行部署脚本（而非仅向用户提供手动命令）
  • 如果需要安装，已向用户索要站点URL并使用
    --site
    运行了脚本（或用户提供了站点且安装已完成）
  • 如果应用使用跨产品作用域（例如读取Jira数据的Confluence应用），已在所有所需产品上安装（部署脚本会自动处理此操作）

Common agent mistakes (avoid these)

代理常见错误（请避免）

  • Picking a developer space when multiple exist — always ask the user to choose.
  • Skipping the deploy script — giving only "run 
    forge deploy
    and 
    forge install
    " instructions instead of running 
    deploy_forge_app.py
    yourself.
  • Not asking for site URL — when install is required, ask the user for their Atlassian site URL; do not guess or skip install.
  • Proceeding to create app before user chooses a developer space — wait for their selection when there are multiple spaces.
  • 当存在多个开发者空间时代为选择——始终让用户选择。
  • 跳过部署脚本——仅提供"运行
    forge deploy
    和
    forge install
    "的说明，而非自行运行
    deploy_forge_app.py
    。
  • 不索要站点URL——当需要安装时，向用户索要Atlassian站点URL；请勿猜测或跳过安装。
  • 用户选择开发者空间前就创建应用——当存在多个空间时，等待用户选择。

Troubleshooting

故障排查

For CLI commands, debugging techniques, and common error patterns, call 
forge-development-guide
. For quick checks:
  • Not logged in / auth failed: Create API token at id.atlassian.com/manage/api-tokens, then run 
    forge login
    in your terminal (never paste token in chat)
  • App not appearing after install: Check 
    forge logs -e development --limit 50
    , verify manifest with 
    forge lint
    , re-install with 
    --upgrade
    if scopes changed
  • "forge: command not found": 
    npm install -g @forge/cli
如需CLI命令、调试技巧和常见错误模式，请调用
forge-development-guide
。快速检查项：
  • 未登录/认证失败：前往id.atlassian.com/manage/api-tokens创建API令牌，然后在终端中运行
    forge login
    （切勿在聊天中粘贴令牌）
  • 安装后应用未显示：检查
    forge logs -e development --limit 50
    ，使用
    forge lint
    验证清单，如果作用域已更改，请使用
    --upgrade
    重新安装
  • "forge: command not found"：运行
    npm install -g @forge/cli