feat: add --raw flag to github-app-token and clean up docs

- Add --raw flag that prints only the token value (no export wrapper),
  making GH_TOKEN=$(./generate_token.sh --raw) the recommended pattern
  for AI agents and CI/CD.
- Clean up die() to only write to stderr (remove eval-safe stdout hack).
- Fix SKILL.md: correct step numbering, remove unused grep prerequisite,
  replace placeholder paths, lead with --raw usage, move eval to legacy.
- Update CLAUDE.md to reflect new --raw pattern.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

CLAUDE.md

@@ -14,12 +14,12 @@ Each skill follows this convention:
 
 ## Current Skills
 
-- **`github-app-token`** — Generates short-lived GitHub App installation access tokens. Requires `GITHUB_APP_ID`, `GITHUB_APP_INSTALLATION_ID`, and `GITHUB_APP_PEM_FILE` env vars. The script outputs an `export GH_TOKEN=...` command meant to be `eval`'d by the caller.
+- **`github-app-token`** — Generates short-lived GitHub App installation access tokens. Requires `GITHUB_APP_ID`, `GITHUB_APP_INSTALLATION_ID`, and `GITHUB_APP_PEM_FILE` env vars. Use `--raw` flag to get the token value directly (recommended for agents), or omit for legacy `eval`-based `export GH_TOKEN=...` output.
 
 ## Key Patterns
 
 - Scripts are pure bash with no external dependencies beyond standard Unix tools (`openssl`, `curl`, `jq`).
-- The `eval` output pattern: scripts print shell commands to stdout (e.g., `export VAR="value"`) so callers can `eval` the output to set variables in their environment.
+- The `--raw` output pattern (preferred): scripts with `--raw` print only the value to stdout for easy `$(...)` capture. The legacy `eval` pattern (no flag) prints shell commands like `export VAR="value"` for backward compatibility.
 - The `die()` function prints errors to stderr and exits non-zero.
 
 ## No Build/Test/Lint System

github-app-token/SKILL.md

@@ -19,30 +19,23 @@ The following environment variables MUST be set before invoking this skill:
 
 If any variable is missing, stop and tell the user which ones are required.
 
-Requires `openssl`, `curl`, `grep`, and `jq` (standard on modern environments).
+Requires `openssl`, `curl`, and `jq` (standard on modern environments).
 
 ## Steps
 
-### 1. Generate and Export Token
+### 1. Generate a Token
 
-Run the helper script and `eval` its output. This securely exports the short-lived GitHub installation access token as `GH_TOKEN` into your current process environment.
-
-**Important:** Because `eval` sets the variable in the current shell process, any commands that need `GH_TOKEN` must run in the **same shell invocation**. Chain all dependent commands together:
+The simplest approach is to use `--raw` mode, which prints only the token value. This works reliably in a single shell invocation:
 
 ```bash
-eval "$(/path/to/skills/github-app-token/scripts/generate_token.sh)" && gh api user
+GH_TOKEN=$(./github-app-token/scripts/generate_token.sh --raw) && export GH_TOKEN
 ```
 
-Do NOT run `eval` in one command and then use `GH_TOKEN` in a separate command — the variable will not persist between separate shell invocations.
+You can then use `GH_TOKEN` in subsequent commands within the same shell invocation:
 
-> [!NOTE]
-> For a CI/CD environment (like GitHub Actions), you can extract the token to pass it between steps like so:
-> `echo "GH_TOKEN=$(/path/to/skills/github-app-token/scripts/generate_token.sh | cut -d'"' -f2)" >> $GITHUB_ENV`
-
-The script will:
-1. Automatically construct a short-lived authorization assertion using your App ID and PEM key
-2. Call the GitHub API to securely exchange that for an Installation Access Token
-3. Output the `export GH_TOKEN="..."` command to set it in your environment.
+```bash
+GH_TOKEN=$(./github-app-token/scripts/generate_token.sh --raw) && export GH_TOKEN && gh api user
+```
 
 ### 2. Authenticate the gh CLI
 
@@ -51,10 +44,10 @@ With `GH_TOKEN` set (in the same shell), the `gh` CLI operates securely and with
 To both generate the token and authenticate `gh` in one go:
 
 ```bash
-eval "$(/path/to/skills/github-app-token/scripts/generate_token.sh)" && echo "${GH_TOKEN}" | gh auth login --with-token && gh auth status
+GH_TOKEN=$(./github-app-token/scripts/generate_token.sh --raw) && export GH_TOKEN && echo "${GH_TOKEN}" | gh auth login --with-token && gh auth status
 ```
 
-### 4. Cleanup
+### 3. Cleanup
 
 The installation access token expires after 1 hour. There is nothing to revoke unless you want to explicitly invalidate it early:
 
@@ -65,6 +58,18 @@ curl -s -X DELETE \
   "https://api.github.com/installation/token"
 ```
 
+## Advanced: `eval` Mode (Legacy)
+
+Without the `--raw` flag, the script outputs `export GH_TOKEN="..."` meant to be `eval`'d. This is the original behavior, preserved for backward compatibility:
+
+```bash
+eval "$(./github-app-token/scripts/generate_token.sh)" && gh api user
+```
+
+> [!NOTE]
+> For CI/CD environments (like GitHub Actions), use `--raw` to extract the token cleanly:
+> `echo "GH_TOKEN=$(./github-app-token/scripts/generate_token.sh --raw)" >> $GITHUB_ENV`
+
 ## Security Notes
 
 - Never log or echo the PEM key or installation token to stdout in production.

github-app-token/scripts/generate_token.sh

@@ -8,9 +8,17 @@
 
 set -euo pipefail
 
+# Parse flags
+RAW_MODE=false
+for arg in "$@"; do
+  case "$arg" in
+    --raw) RAW_MODE=true ;;
+    *) echo "error: unknown flag: $arg" >&2; exit 1 ;;
+  esac
+done
+
 die() {
   echo "error: $1" >&2
-  echo "return 1 2>/dev/null || false"
   exit 1
 }
 
@@ -62,5 +70,9 @@ if [[ -z "${INSTALL_TOKEN}" ]]; then
   die "failed to generate installation token. Response: ${RESPONSE}"
 fi
 
-# Output the export command so it can be eval'd by the caller
-echo "export GH_TOKEN=\"${INSTALL_TOKEN}\""
+# Output the token
+if [[ "$RAW_MODE" == true ]]; then
+  printf '%s' "${INSTALL_TOKEN}"
+else
+  echo "export GH_TOKEN=\"${INSTALL_TOKEN}\""
+fi