From 7980dd06a0cd7416b2f1a1d40a5e4bd10b45e92d Mon Sep 17 00:00:00 2001 From: Chris Farhood Date: Thu, 26 Mar 2026 22:32:12 -0400 Subject: [PATCH] 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) --- CLAUDE.md | 27 +++++++++++++++++++++++++++ github-app-token/SKILL.md | 30 +++++++++++++----------------- 2 files changed, 40 insertions(+), 17 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..dae022b --- /dev/null +++ b/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.md`** — Required. Contains YAML frontmatter (`name`, `description`) and usage documentation. This is the entry point Claude Code reads when invoking the skill. +- **`/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. diff --git a/github-app-token/SKILL.md b/github-app-token/SKILL.md index 6194115..1379888 100644 --- a/github-app-token/SKILL.md +++ b/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 ``` -> [!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: +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] +> 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 -gh api user +eval "$(/path/to/skills/github-app-token/scripts/generate_token.sh)" && echo "${GH_TOKEN}" | gh auth login --with-token && gh auth status ``` -*(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: