| name | stacklight-setup |
| description | Guide the user through configuring StackLight providers (Vercel, Cloudflare Pages, GitHub Actions/PR, Netlify, Railway, Fly.io, Xcode Cloud, TestFlight). Use when the user says things like "set up StackLight", "configure StackLight", "help me add a new provider", "fill in StackLight settings", or asks how to wire up credentials for any supported service. The skill reads providers.schema.json, collects missing credentials, validates them, and writes a local config JSON the user can reference while entering values in the Settings window. |
StackLight Setup
This skill turns a configuration conversation into structured work: the agent reads a schema, probes the environment for existing credentials, asks the user only for what's missing, validates each credential, and emits a JSON file summarizing the result.
Inputs
- Schema:
.Codex/skills/stacklight-setup/providers.schema.json — the single source of truth for which fields each provider needs. Never hard-code field names; always read this file.
- Validator:
.Codex/skills/stacklight-setup/scripts/validate.sh <provider> <json-config> — returns exit 0 on success, non-zero with a short error on failure.
- Output:
./.stacklight-config.json in the repo root (gitignored). This is a reference the user will manually paste into Settings → StackLight, because secrets must land in macOS Keychain via the UI.
Workflow
Execute these steps in order. Do not skip steps.
1. Load the schema
Read .Codex/skills/stacklight-setup/providers.schema.json. The providers object is authoritative — every field, secret flag, required flag, and test endpoint comes from here.
2. Pick providers
Ask the user which providers they want to enable using AskUserQuestion. Offer all keys from providers.schema.json plus a free-form "other" option. If the user previously mentioned specific services in the conversation, pre-check those.
3. Probe the environment for each enabled provider
Before asking the user for a value, check (in order) whether it already exists:
| Field pattern | Check these sources |
|---|
github.token | gh auth token (if gh installed), then $GITHUB_TOKEN, then ~/.netrc |
vercel.token | $VERCEL_TOKEN, then ~/.local/share/com.vercel.cli/auth.json |
cloudflare.token | $CLOUDFLARE_API_TOKEN, then $CF_API_TOKEN |
cloudflare.accountId | $CLOUDFLARE_ACCOUNT_ID, then wrangler whoami output |
netlify.token | $NETLIFY_AUTH_TOKEN, then ~/.netlify/config.json |
railway.token | $RAILWAY_TOKEN, then ~/.railway/config.json |
flyio.token | $FLY_API_TOKEN, then fly auth token |
github.repos | git remote -v of the current repo; offer that owner/repo first |
asc.* (Apple) | Never auto-detect — always ask the user; .p8 paths are user-specific |
Run the detection commands with Bash. Do not print secret values back to the user; confirm presence as (detected ✓).
4. Ask for the rest — one round only
Use a single AskUserQuestion call with one question per still-missing field. Set multiSelect: false on all of them and keep the question text short. For fields marked secret: true, add the suffix (will be stored in macOS Keychain) to the question so the user knows the final destination.
5. Validate each provider
For every provider the user enabled, call:
.Codex/skills/stacklight-setup/scripts/validate.sh <provider> <path-to-partial-json>
The validator uses only curl and jq. On non-zero exit, report the error message back to the user and re-ask just the failing fields. Do not continue until every selected provider validates, unless the user explicitly says "skip validation for ".
6. Write ./.stacklight-config.json
Emit a file with this shape (example):
{
"generatedAt": "2026-04-15T12:00:00Z",
"providers": {
"vercel": { "vercel.token": "***", "vercel.teamId": "" },
"githubPR": { "github.token": "***", "github.pr.repos": ["owner/repo"] }
}
}
Redact secrets as *** when printing to chat, but write the real values to the file. Also append .stacklight-config.json to .gitignore if not already present.
7. Tell the user what to do in the UI
Output a short bullet list:
- Launch StackLight (▲ in menu bar → Settings).
- For each provider in the config JSON, open that tab, paste the fields listed under its key, click Save, then Test.
- Note that credentials listed as
credentialSharedWith in the schema (e.g. Xcode Cloud ↔ TestFlight, GitHub Actions ↔ GitHub PR) only need to be entered once.
Rules
- Never invent field keys. If the schema does not define a key, do not ask for it.
- Never commit
.stacklight-config.json. Always verify/update .gitignore.
- Never echo secrets back to the user in plain text after collection — use
*** or the last 4 characters only.
- Prefer one batch of questions. Users dislike being drip-fed prompts. Gather everything you know first, then ask once.
- Shared credentials. When two providers share a key (see
credentialSharedWith), collect it once and reuse.
asc.privateKey (Xcode Cloud). Ask the user for a file path, then read the .p8 file contents and strip PEM headers before writing to the config (mirror the provider's own strippedKey logic in XcodeCloudProvider.swift).
When to update this skill
If a new provider is added to Sources/StackLight/Providers/, update providers.schema.json to add its entry. The fields must mirror the Swift settingsFields() method exactly — that is the contract.
