/forge-app-builder

name: forge-app-builder
description: Plan, build, scaffold, or safely extend Atlassian Forge apps using current official documentation. Use for fresh Forge apps, existing-app feature work, module and manifest changes, UI Kit or Custom UI implementation, backend functions and events, Atlassian or external APIs, storage, permissions, environment configuration, distribution-affecting implementation, validation, and explicitly authorized deployment or installation; route standalone debugging and specialist reviews to their dedicated skills.
license: Apache-2.0
metadata:
  labels: "confluence,jira,bitbucket,atlassian,forge"
  maintainer: amoore
  namespace: cloud

Forge App Builder

Route each request through only the branches and capability gates it needs. Keep platform facts live and keep local guidance focused on safe decisions.

Preserve these invariants

1. Retrieve current official Forge guidance before committing to platform syntax, modules, APIs, scopes, limits, runtimes, packages, lifecycle status, or CLI flags. 2. Register every new deployable app with `forge create`; never hand-build an app identity or replace a failed creation with an unregistered scaffold. 3. Inspect an existing app and its repository instructions before planning or editing it. Preserve unrelated user changes. 4. Never request or accept credentials in chat. Use the relevant interactive CLI or secure configuration flow. 5. Never accept Forge terms or billing consent, deploy, install, upgrade, promote, set a production variable, or change a live site without explicit authorization and a confirmed target. 6. Validate every manifest change against the exact current reference and with `forge lint`. 7. Use least privilege and avoid unnecessary egress, privileged backend operations, and migrations. 8. Prefix Forge CLI commands run for this skill with `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-app-builder`; exclude user-run `forge login` and `forge tunnel`.

Route the primary intent

Choose one primary route before loading implementation guidance:

| Intent | Route | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | Architecture, feasibility, or implementation plan only | Read [references/plan-only.md](references/plan-only.md); stop before mutations | | Create a deployable app | Read [references/create-new-app.md](references/create-new-app.md) | | Add or change behavior in an existing app | Read [references/extend-existing-app.md](references/extend-existing-app.md) | | Known error, failed command, blank UI, logs, or unexpected behavior | Route to `forge-debugger` | | Broad pre-deploy or release-readiness review | Route to `forge-app-review` | | Deep security review or static analysis | Route to `forge-security-review` | | Cost or platform-consumption optimization | Route to `forge-cost-optimizer` | | Teamwork Graph connector | Route to `forge-connector` |

Continue here when diagnosis or review is incidental to active build work. If the route is unclear, inspect the workspace before asking the user.

Ground the selected route

Read [references/documentation-routing.md](references/documentation-routing.md) when current platform detail is needed. Use Forge MCP as the first preference whenever it is available. Discover its current capabilities by purpose rather than assuming permanent tool names, and call the narrowest relevant capability before relying on web documentation or remembered platform knowledge. Use focused official Atlassian documentation when MCP is unavailable, fails, or lacks the exact coverage needed, and for critical verification.

Call the general Forge development guide when broad orientation is useful. Do not call it merely to satisfy a ritual when the task needs only one known leaf reference. Retrieve the exact module, manifest property, endpoint, scope, or CLI page before relying on it.

Activate capability gates conditionally

Load only the references implicated by the requested outcome and observed code:

| Trigger | Read | | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | Select or add an extension point or module | [references/module-selection.md](references/module-selection.md) | | Implement or change UI Kit | [references/ui-kit.md](references/ui-kit.md) | | Implement or change Custom UI or `Frame` | [references/custom-ui.md](references/custom-ui.md) | | Add resolvers, functions, events, schedules, queues, web triggers, app REST APIs, realtime, or runtime services | [references/backend-and-events.md](references/backend-and-events.md)