docs: add CLAUDE.md and fix SKILL.md for cross-invocation shell usage

SKILL.md instructions now clarify that GH_TOKEN must be used in the
same shell invocation as the eval, with chained command examples.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,27 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is a **Claude Code skills repository**. Skills are reusable tools that extend Claude Code's capabilities. Each skill lives in its own top-level directory.
+
+## Skill Structure
+
+Each skill follows this convention:
+- **`<skill-name>/SKILL.md`** — Required. Contains YAML frontmatter (`name`, `description`) and usage documentation. This is the entry point Claude Code reads when invoking the skill.
+- **`<skill-name>/scripts/`** — Implementation scripts (bash). Scripts use `set -euo pipefail` and the `die()` pattern for error handling.
+
+## 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.
+
+## 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 `die()` function prints errors to stderr and exits non-zero.
+
+## No Build/Test/Lint System
+
+There is no centralized build, test, or lint tooling. Each skill is self-contained.

github-app-token/SKILL.md

@@ -25,39 +25,35 @@ Requires `openssl`, `curl`, `grep`, and `jq` (standard on modern environments).
 
 ### 1. Generate and Export 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:
+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:
 
 ```bash
-eval "$(/path/to/skills/github-app-token/scripts/generate_token.sh)"
+eval "$(/path/to/skills/github-app-token/scripts/generate_token.sh)" && gh api user
 ```
 
+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.
+
 > [!NOTE]
-> Because this uses `eval`, the token is scoped only to the current terminal session, process, or script that executes it. For a CI/CD environment (like GitHub Actions), you can extract the token to pass it between steps like so:
+> 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.
+
 ### 2. Authenticate the gh CLI
 
-With `GH_TOKEN` set, the `gh` CLI operates securely and without needing a separate authentication login for most API operations. Note that `gh auth status` may not reflect the token since it checks local config, but `gh` will respect the `GH_TOKEN` environment variable!
+With `GH_TOKEN` set (in the same shell), the `gh` CLI operates securely and without needing a separate authentication login for most API operations. Note that `gh auth status` may not reflect the token since it checks local config, but `gh` will respect the `GH_TOKEN` environment variable.
+
+To both generate the token and authenticate `gh` in one go:
 
 ```bash
-# Check that gh is working
+eval "$(/path/to/skills/github-app-token/scripts/generate_token.sh)" && echo "${GH_TOKEN}" | gh auth login --with-token && gh auth status
-gh api user
 ```
 
-*(Alternatively, to specifically configure gh auth locally, you can use: `echo "${GH_TOKEN}" | gh auth login --with-token`)*
-
-Verify it worked:
-
-```bash
-gh auth status
-```
-
-You should see authentication via `token` for `github.com`.
-
 ### 4. Cleanup
 
 The installation access token expires after 1 hour. There is nothing to revoke unless you want to explicitly invalidate it early: