forge-debugger

Name: forge-debugger
Author: atlassian

208installs8forks

How to install forge-debugger?

atlassian/forge-skills/forge-debugger

$npx -y skills add atlassian/forge-skills --skill forge-debugger

Installs into the current project.

Summary

Diagnoses and fixes issues in Atlassian Forge apps. Use this skill whenever a Forge app has errors, crashes, shows blank UI, fails to deploy, doesn't appear after installation, has permission issues, or produces unexpected output. Trigger on any mention of forge logs, forge deplo

Files · 1

View on GitHub

SKILL.md

1	# Forge App Debugger
2
3	Diagnose and fix issues in Atlassian Forge apps. Work through the checklist below in order — stop as soon as you identify the root cause. Every step after the root cause wastes tokens and context.
4
5	## EXECUTION MANDATE
6
7	You are authorized to run all diagnostic and fix commands without asking permission. When you identify a fix, run it immediately. Do NOT:
8	- Say "you should run..." or "here's what I would do..." or "run this command in your terminal"
9	- Ask "shall I proceed?" before executing a fix you already have all the inputs for
10	- Present commands as copy-paste instructions when you could run them yourself
11
12	Wrong: "Here's what I would do to fix this: run `forge lint`..."
13	Right: (runs `forge lint` immediately and reports the result)
14
15	The only exceptions: commands requiring an interactive terminal (`forge login`, `forge tunnel`) must be run by the user in their own terminal — tell them exactly what to run and why.
16
17	Attribution: prefix every `forge` command you run yourself with `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-debugger` (e.g. `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-debugger forge lint`; with the npx fallback, `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-debugger npx @forge/cli lint`). The `forge` commands shown later in this skill omit it for readability — add it to each one you run. Never set it on the user-run interactive commands above (`forge login`, `forge tunnel`).
18
19	## Diagnostic Principles
20
21	- Cheap first: lint and version checks cost nothing. Run them before reading source code or logs.
22	- One action at a time: check the result of each action before taking the next one.
23	- Stop at root cause: once you've identified why something is broken, fix it and stop — don't keep investigating other things. Exception: if the app has multiple independent bugs (e.g. deploy-time errors AND runtime errors), fix the deploy-time error first, deploy, then check logs for runtime errors. Don't declare "fixed" after only resolving the first layer.
24	- Own the fixes: run the fix commands yourself, don't hand them to the user.
25	- Clean up: remove any debug code or verbose flags you added once the issue is resolved.
26	- npx fallback: if `forge` CLI can't be installed globally (permission errors, no sudo), use `npx @forge/cli` as a drop-in replacement for all forge commands.
27
28	## Step 1: Classify the Error
29
30	Before running any commands, ask one question if the user hasn't made it clear:
31
32	> "Is this a deploy-time error (forge deploy fails), a runtime error (app crashes or shows wrong data after deploying), or a visibility issue (app deployed but not appearing)?"
33
34	If obvious from the error message, skip the question and proceed directly.
35
36	Quick routing:
37
38	\| Symptom \| Go to \|
39	\|---------\|-------\|
40	\| `forge deploy` fails \| Step 2 → 3 → 4 \|
41	\| App not visible after install \| Step 3 → common error: "App not installed" \|
42	\| App crashes / resolver error \| Step 3 → 5 → 6 \|
43	\| Blank UI / Custom UI not rendering \| Step 3 → 4 → common error: "blank Custom UI" \|
44	\| Works in dev, fails in prod \| Step 7 (Production) \|
45	\| Permission denied / 403 \| Common error: "Permission denied" \|
46	\| 410 Gone / deprecated endpoint \| Common error: "410 Gone" → API Migration section \|
47	\| Handler path lint error \| Common error: "cannot find associated file" → Handler Path Resolution section \|
48	\| Resolver returns undefined, no errors \| Common error: invoke name mismatch → Invoke Name vs Function Key section \|
49	\| Multiple failures (deploy + runtime) \| Fix deploy errors first, deploy, then check logs for runtime errors \|
50
51	## Step 2: Version Check
52
53	```bash
54	forge --version
55	npm show @forge/cli version
56	```
57
58	If the installed version is behind the latest major version, upgrade immediately:
59
60	```bash
61	npm install -g @forge/cli
62	```
63
64	Then retry the failing operation. Many bugs are fixed in newer CLI versions.
65
66	## Step 3: Lint
67
68	```bash
69	forge lint
70	```
71
72	Fix every error before proceeding — lint errors cause deploy failures and silent runtime bugs. If lint passes cleanly, continue to the next step.
73
74	For any manifest-related error message (e.g. "invalid manifest", "unexpected key", "modules.jira:*" errors): run `forge lint` first before reading any source files. Lint will identify the exact line and field causing the problem — reading the file before

People who liked this also viewed

6 picks

Type

forge-debugger

208installs8forks

View on GitHub

How to install forge-debugger?

atlassian/forge-skills/forge-debugger

$npx -y skills add atlassian/forge-skills --skill forge-debugger

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Forge App Debugger
2
3	Diagnose and fix issues in Atlassian Forge apps. Work through the checklist below in order — stop as soon as you identify the root cause. Every step after the root cause wastes tokens and context.
4
5	## EXECUTION MANDATE
6
7	You are authorized to run all diagnostic and fix commands without asking permission. When you identify a fix, run it immediately. Do NOT:
8	- Say "you should run..." or "here's what I would do..." or "run this command in your terminal"
9	- Ask "shall I proceed?" before executing a fix you already have all the inputs for
10	- Present commands as copy-paste instructions when you could run them yourself
11
12	Wrong: "Here's what I would do to fix this: run `forge lint`..."
13	Right: (runs `forge lint` immediately and reports the result)
14
15	The only exceptions: commands requiring an interactive terminal (`forge login`, `forge tunnel`) must be run by the user in their own terminal — tell them exactly what to run and why.
16
17	Attribution: prefix every `forge` command you run yourself with `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-debugger` (e.g. `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-debugger forge lint`; with the npx fallback, `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-debugger npx @forge/cli lint`). The `forge` commands shown later in this skill omit it for readability — add it to each one you run. Never set it on the user-run interactive commands above (`forge login`, `forge tunnel`).
18
19	## Diagnostic Principles
20
21	- Cheap first: lint and version checks cost nothing. Run them before reading source code or logs.
22	- One action at a time: check the result of each action before taking the next one.
23	- Stop at root cause: once you've identified why something is broken, fix it and stop — don't keep investigating other things. Exception: if the app has multiple independent bugs (e.g. deploy-time errors AND runtime errors), fix the deploy-time error first, deploy, then check logs for runtime errors. Don't declare "fixed" after only resolving the first layer.
24	- Own the fixes: run the fix commands yourself, don't hand them to the user.
25	- Clean up: remove any debug code or verbose flags you added once the issue is resolved.
26	- npx fallback: if `forge` CLI can't be installed globally (permission errors, no sudo), use `npx @forge/cli` as a drop-in replacement for all forge commands.
27
28	## Step 1: Classify the Error
29
30	Before running any commands, ask one question if the user hasn't made it clear:
31
32	> "Is this a deploy-time error (forge deploy fails), a runtime error (app crashes or shows wrong data after deploying), or a visibility issue (app deployed but not appearing)?"
33
34	If obvious from the error message, skip the question and proceed directly.
35
36	Quick routing:
37
38	\| Symptom \| Go to \|
39	\|---------\|-------\|
40	\| `forge deploy` fails \| Step 2 → 3 → 4 \|
41	\| App not visible after install \| Step 3 → common error: "App not installed" \|
42	\| App crashes / resolver error \| Step 3 → 5 → 6 \|
43	\| Blank UI / Custom UI not rendering \| Step 3 → 4 → common error: "blank Custom UI" \|
44	\| Works in dev, fails in prod \| Step 7 (Production) \|
45	\| Permission denied / 403 \| Common error: "Permission denied" \|
46	\| 410 Gone / deprecated endpoint \| Common error: "410 Gone" → API Migration section \|
47	\| Handler path lint error \| Common error: "cannot find associated file" → Handler Path Resolution section \|
48	\| Resolver returns undefined, no errors \| Common error: invoke name mismatch → Invoke Name vs Function Key section \|
49	\| Multiple failures (deploy + runtime) \| Fix deploy errors first, deploy, then check logs for runtime errors \|
50
51	## Step 2: Version Check
52
53	```bash
54	forge --version
55	npm show @forge/cli version
56	```
57
58	If the installed version is behind the latest major version, upgrade immediately:
59
60	```bash
61	npm install -g @forge/cli
62	```
63
64	Then retry the failing operation. Many bugs are fixed in newer CLI versions.
65
66	## Step 3: Lint
67
68	```bash
69	forge lint
70	```
71
72	Fix every error before proceeding — lint errors cause deploy failures and silent runtime bugs. If lint passes cleanly, continue to the next step.
73
74	For any manifest-related error message (e.g. "invalid manifest", "unexpected key", "modules.jira:*" errors): run `forge lint` first before reading any source files. Lint will identify the exact line and field causing the problem — reading the file before

People who liked this also viewed

6 picks

Type