gw-triage/skills/setup/SKILL.md

name, description

name	description
setup	Use when configuring the Jira API credentials for gw-triage — first-time setup, an "allegato saltato" warning from triage, missing or expired JIRA_EMAIL/JIRA_API_TOKEN, or replacing a revoked token. Triggers on /gw-triage:setup, "configura il token", "gli allegati non funzionano".

Setup — token API Jira guidato

You guide the user through creating a Jira API token and storing it so the triage skill can attach screenshots to issues.

All interaction with the user happens in Italian. This file is English for precision; never quote it to the user.

The only consumer of the token is the triage skill (its curl attachment call), which runs inside Claude Code. Credentials therefore go in the env block of ~/.claude/settings.json — Claude Code injects them into every session, regardless of the user's shell. Never touch shell profiles.

Keep the token out of replies and displayed commands. Refer to it as "il token" and never repeat its value. Never inline a literal token on a shell command line — it ends up in the transcript and the process list. Shell variables may be passed as unexpanded $VAR references; literal values (pasted or read from a file) go through the temp netrc file described in Step 0.3.

Step 0 — Check existing configuration

1. Run test -n "$JIRA_EMAIL" && test -n "$JIRA_API_TOKEN" && echo session || echo unset.

2. Read ~/.claude/settings.json (if it exists) and note whether env.JIRA_EMAIL / env.JIRA_API_TOKEN are present.

3. If credentials exist in either place, verify them. The check call is

   curl -s -o /dev/null -w "%{http_code}" \
     <credentials> \
     https://growingway.atlassian.net/rest/api/3/myself
   

   (host = the site in ${CLAUDE_PLUGIN_ROOT}/config/routing.json, without the scheme). For <credentials>:

   • session env vars set → -u "$JIRA_EMAIL:$JIRA_API_TOKEN", with the $ references left unexpanded for the shell to fill in — never substitute the values yourself.

   • literal values (from settings.json or a paste) → use the Write tool to create a netrc file in the session scratchpad directory:

     machine growingway.atlassian.net
     login <email>
     password <token>
     

     chmod 600 it and pass --netrc-file <path> instead of -u. Delete this file before the skill ends, whatever the outcome.

   Result:

   • 200 → tell the user (Italian) the token already works and ask whether they want to replace it anyway. If not, stop.
   • anything else → tell them the stored token no longer works (probably expired or revoked) and continue.

Step 1 — Token creation (user, in the browser)

Print in Italian, compactly:

1. Apri https://id.atlassian.com/manage-profile/security/api-tokens (login con l'account Atlassian aziendale).
2. Create API token → nome gw-triage → scegli la scadenza → copia subito il token (viene mostrato una volta sola).
3. Incolla qui email aziendale e token (vanno bene anche su due righe).

Add one line: il token verrà salvato in chiaro in ~/.claude/settings.json sul suo computer, quindi non condividere né il file né questa conversazione.

End the turn and wait. If the reply contains only one of the two values, ask for the missing one. If the user can't create the token (no permission, page unreachable), stop and suggest asking whoever manages the Atlassian accounts.

Step 2 — Verify before saving

Run the Step 0.3 check with the pasted values — literals, so via the temp netrc file, never -u on the command line.

• 200 → proceed to Step 3.
• 401/403 → wrong email or token (a common cause: copied with a trailing space or truncated). Ask the user to re-copy and re-paste, then verify again; stop after the third failed verification overall and suggest creating a fresh token.
• Anything else (timeout, DNS) → network problem, not credentials: report it and stop; the pasted token stays valid for a later retry.

Step 3 — Save to settings.json

Update ~/.claude/settings.json with Read + Edit/Write (never shell text-mangling):

• File missing → create it containing only {"env": {"JIRA_EMAIL": "<email>", "JIRA_API_TOKEN": "<token>"}}.
• Valid JSON → add or overwrite the two keys inside the existing env object (create the object if absent). Preserve every other key untouched.
• Invalid JSON → do NOT overwrite; show the user the parse error and stop.

Leftover check: old installs configured the shell profile instead. Run fish -c 'set -U' 2>/dev/null | grep -i jira and grep -l JIRA_API_TOKEN ~/.config/fish/config.fish ~/.config/fish/conf.d/*.fish ~/.zshrc ~/.bashrc ~/.zprofile ~/.profile 2>/dev/null. If anything turns up, tell the user (Italian) to remove it so it can't shadow the new token (fish: set -e JIRA_EMAIL; set -e JIRA_API_TOKEN; altrimenti togliere gli export dal file indicato).

Step 4 — Report

Delete the temp netrc file if one was created.

In Italian: token verificato e salvato. Vale dalle prossime sessioni di Claude Code — quelle già aperte vanno riavviate prima che l'allegato automatico funzioni. Per sostituirlo o dopo una revoca basta rilanciare /gw-triage:setup.