@gerdloos/npm-trusts-github-skill 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install -g npm@latest
+      - run: npm publish --access public

package/README.md

@@ -0,0 +1,15 @@
+# setup-npm-trusts-github-skill
+
+A skill that teaches an LLM how to set up npm trusted publishing (OIDC) with GitHub Actions.
+
+## Install on Pi
+
+```bash
+pi install npm:@gerdloos/npm-trusts-github-skill
+```
+
+## Usage
+
+In Pi: `/skill:npm-trusts-github`
+
+The agent will guide you through setting up automated npm publishing — no tokens, no 2FA prompts, just git tags → GitHub Actions → npm.

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@gerdloos/npm-trusts-github-skill",
+  "version": "1.0.0",
+  "description": "A skill that teaches an LLM how to set up npm trusted publishing with GitHub Actions",
+  "keywords": ["pi-package", "npm", "publish", "workflow"],
+  "license": "MIT",
+  "pi": {
+    "skills": ["./skills"]
+  }
+}

package/skills/npm-trusts-github/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: npm-trusts-github
+description: >
+  Set up npm trusted publishing (OIDC) with GitHub Actions — no tokens, no 2FA
+  prompts. Teaches the agent how to create package.json, write publish.yml,
+  configure trusted publisher on npmjs.com, wire git-tag-driven releases, and
+  troubleshoot common failures. Trigger when a user asks to publish an npm
+  package automatically from GitHub, set up CI/CD for npm, use OIDC to avoid
+  npm tokens, or wire a GitHub repo to auto-publish on every git tag.
+---
+
+# npm trusts GitHub — Trusted Publishing Setup
+
+Wires a GitHub repo to auto-publish to npm on every git tag via OIDC trusted
+publishing. No long-lived tokens, no 2FA prompts, no manual rotation.
+
+## Before starting
+
+Read `defaults.json` in this skill directory. It contains the user's preferred
+npm scope, npm org, and GitHub account. If a field is empty or contains a
+placeholder (`<Fill default here ... or leave empty>`), ask the user for that
+value. The user can edit `defaults.json` at any time.
+
+- **npmScope**: your npm username with `@` (e.g. `@alice`). Scope and org are
+  alternatives — fill one, leave the other empty. If both are empty, packages
+  are unscoped.
+- **npmOrg**: an optional npm organization name (e.g. `mycompany`). Creates
+  packages under `@mycompany/` instead of `@yourname/`.
+- **githubAccount**: your GitHub username for repo URLs and trusted publisher.
+
+Prefer values the user provides in conversation over the config file.
+
+## Reference documents
+
+All in `references/` relative to this SKILL.md. Load on demand.
+
+| File | When to load |
+|---|---|
+| `references/quick-start.md` | User wants the full step-by-step with placeholders filled in |
+| `references/publish.yml` | User needs the GitHub Actions workflow template |
+| `references/setup-guide.md` | User needs detailed explanations of each step |
+| `references/troubleshooting.md` | User hits an error |
+| `references/example-hello.md` | User wants a worked example (the hello-world package) |
+
+## Core concept
+
+The pipeline:
+
+```
+git push --follow-tags → GitHub Action detects v* tag → npm publish via OIDC
+```
+
+No npm login, no token secrets, no 2FA codes. The GitHub Action exchanges a
+short-lived OIDC identity token for publish rights. Provenance is signed
+automatically.
+
+## Troubleshooting quick reference
+
+| Error | Cause | Fix |
+|---|---|---|
+| `ENEEDAUTH` | npm too old (< 11.5.1) | `npm install -g npm@latest` in workflow |
+| `E404` | Trusted publisher config typo OR package never manually published | Re-check fields on npmjs.com; do one manual publish |
+| `EOTP` | Token-based path is being used instead of OIDC | Remove `NODE_AUTH_TOKEN` and `--provenance` |
+
+Full guide: `references/troubleshooting.md`.

package/skills/npm-trusts-github/defaults.json

@@ -0,0 +1,17 @@
+{
+  "_comment": "==========================================================\n  DEFAULTS CONFIG — setup-npm-publish skill\n  Fill in your values below. Leave a field empty (empty string)\n  or keep its placeholder, and the LLM will ask you for it\n  when needed.\n==========================================================",
+
+  "npmScope": "<Fill default here like @your-username or leave empty>",
+
+  "_npmScope_explanation": "Your npm scope is just the @account part — not the full\n  package name. Example: in @alice/utils, the scope is @alice,\n  and 'utils' is the project name (chosen at npm init time).\n  Every npm account automatically gets a scope matching its\n  username.\n\n  When you publish with a scope, your package name only needs\n  to be unique within that scope — @alice/utils and @bob/utils\n  can both exist without conflict.\n\n  If you also fill in npmOrg, leave this empty. The org name\n  becomes the scope instead.\n\n  If both are empty, packages are unscoped (global namespace,\n  e.g. 'utils' instead of '@alice/utils'). Unscoped names\n  must be globally unique — first come, first served.\n\n  Fill in like: @your-username",
+
+  "_scopeOrOrg_note": "npmScope and npmOrg are alternatives, not layers. If you fill in npmOrg, leave npmScope empty (and vice versa). The org name becomes the scope. If both are empty, packages are unscoped (global namespace).",
+
+  "npmOrg": "<Fill default here like org-name without @ or leave empty>",
+
+  "_npmOrg_explanation": "An npm organization is a shared namespace you create at\n  npmjs.com/org/create. It's free. The org gets its own scope\n  (e.g. @mycompany). Multiple people can publish under it.\n\n  This field is OPTIONAL. Leave empty if you don't have an org\n  or don't want to publish under one.\n\n  When to use an org:\n  - You want packages under @mycompany/ instead of @yourname/\n  - Multiple maintainers need publish access\n  - You want organizational branding separate from your\n    personal account\n\n  If you set this, the LLM uses @<npmOrg>/ as the scope\n  instead of your personal scope. Your personal account must\n  own or be a member of the org.\n\n  Fill in like: mycompany (no @ prefix — just the name)",
+
+  "githubAccount": "<Fill default here like account-name or leave empty>",
+
+  "_githubAccount_explanation": "Your GitHub username. Used for:\n  - Repo URLs: git@github.com:<account>/<repo>.git\n  - Trusted publisher config on npmjs.com\n\n  Fill in like: alice"
+}

package/skills/npm-trusts-github/references/example-hello.md

@@ -0,0 +1,78 @@
+# Worked Example — @gerdloos/pi-skill-hello
+
+This is the real package that this skill's setup was battle-tested against.
+Follow this walkthrough to see the full flow in action.
+
+## Final state
+
+| Piece | Value |
+|---|---|
+| npm package | `@gerdloos/pi-skill-hello` ([view](https://www.npmjs.com/package/@gerdloos/pi-skill-hello)) |
+| GitHub repo | `<github-account>/pi-skill-hello` (private) |
+| Workflow | `.github/workflows/publish.yml` |
+| Trusted publisher | Configured on npm package settings |
+| npm org (available) | `<org-name>` under your npm account |
+
+## Package contents
+
+```
+pi-skill-hello/
+├── package.json              # name: @gerdloos/pi-skill-hello
+├── README.md
+├── .github/workflows/
+│   └── publish.yml           # triggers on v* tags, id-token: write
+├── skills/
+│   └── hello/
+│       ├── SKILL.md          # Agent Skills spec — says "Hello npm! 🎉"
+│       └── scripts/
+│           └── hello.sh
+```
+
+## Errors we hit and how we fixed them
+
+### 1. `EOTP` — one-time password required
+**When:** First attempt with a "Publish" type granular token.
+**Why:** The token required 2FA for every publish. GitHub Actions can't enter OTPs.
+**Fix:** Switched to trusted publishing (OIDC). Deleted the token entirely.
+
+### 2. `E404` — package not in registry (after trusted publisher config)
+**When:** After configuring the trusted publisher on npmjs.com.
+**Why:** Had `--provenance` flag and `NODE_AUTH_TOKEN` in the workflow.
+These triggered the old token-based code path, which overrode the OIDC flow.
+**Fix:** Removed `--provenance` flag and `NODE_AUTH_TOKEN` env var.
+
+### 3. `ENEEDAUTH` — need auth
+**When:** After removing token and flags.
+**Why:** npm version on the runner was too old (< 11.5.1). OIDC wasn't recognized.
+**Fix:** Added `npm install -g npm@latest` step before `npm publish`.
+
+### 4. `E404` again — trusted publisher mismatch
+**When:** After all workflow fixes.
+**Why:** The `registry-url` in `setup-node` was creating an `.npmrc` with an
+empty `_authToken` line, which blocked the OIDC flow.
+**Fix:** Moved to passing `--registry https://registry.npmjs.org` in the
+publish command instead of relying on `setup-node`'s `registry-url`.
+(Later re-added `registry-url` once we understood that the issue was npm version,
+not the registry config.)
+
+### 5. Final working state
+- `registry-url` in setup-node (creates registry config)
+- No `NODE_AUTH_TOKEN` env var (OIDC handles auth)
+- No `--provenance` flag (automatic with trusted publishing)
+- `npm install -g npm@latest` (ensures npm ≥ 11.5.1)
+- `id-token: write` at root permissions level
+- Bare `npm publish --access public`
+
+## The exact publish.yml that works
+
+See `references/publish.yml` in this skill directory.
+
+## How to replicate for your own project
+
+1. Copy the `publish.yml` into your project
+2. Replace `@gerdloos` with your scope in `package.json`
+3. Create the GitHub repo, push code
+4. Manually publish once: `npm login && npm publish --access public`
+5. Configure trusted publisher on npmjs.com
+6. `npm version patch && git push --follow-tags`
+7. Watch `github.com/your-username/your-repo/actions`

package/skills/npm-trusts-github/references/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install -g npm@latest
+      - run: npm publish --access public

package/skills/npm-trusts-github/references/quick-start.md

@@ -0,0 +1,102 @@
+# Quick Start
+
+Follow these steps to wire up your first package. Replace `<npmScope>`,
+`<githubAccount>`, and `<my-pkg>` with values from `defaults.json` or user
+answers.
+
+## 1. Create the package
+
+```bash
+mkdir <my-pkg> && cd <my-pkg>
+npm init --scope=<npmScope>
+```
+
+## 2. Write code
+
+Add your source files. Create a README.
+
+## 3. Add the GitHub Actions workflow
+
+```bash
+mkdir -p .github/workflows
+```
+
+Copy the workflow template from `references/publish.yml` into
+`.github/workflows/publish.yml`. The template is ready to use — it includes
+the correct permissions, npm upgrade step, and bare publish command.
+
+## 4. Commit and push to GitHub
+
+Create a repo on GitHub (public or private — Actions works on both).
+
+```bash
+git init
+git add -A
+git commit -m "Initial commit"
+git remote add origin git@github.com:<githubAccount>/<my-pkg>.git
+git branch -M main
+git push -u origin main
+```
+
+## 5. Publish manually once
+
+This establishes the package on npm. The trusted publisher can publish new
+versions of an existing package, but cannot create a brand-new one.
+
+```bash
+npm login
+npm publish --access public
+```
+
+Verify: `https://www.npmjs.com/package/<npmScope>/<my-pkg>`
+
+## 6. Configure trusted publisher on npm
+
+1. Go to `https://www.npmjs.com/package/<npmScope>/<my-pkg>/access`
+2. Scroll to **Trusted Publisher** → click **GitHub Actions**
+3. Fill in:
+
+| Field | Value |
+|---|---|
+| Organization or user | `<githubAccount>` |
+| Repository | `<my-pkg>` |
+| Workflow filename | `publish.yml` |
+| Environment name | leave empty |
+| Allowed actions | `npm publish` |
+
+**Warning:** npm does NOT validate this form on save. Triple-check every field.
+
+4. Click **Save**
+
+## 7. Restrict token access (recommended)
+
+On the same page, under **Publishing access**, select:
+**"Require two-factor authentication and disallow tokens"**.
+
+Trusted publishers bypass this restriction. This blocks any leaked API tokens
+from publishing to your package.
+
+## 8. Push a tag and publish
+
+```bash
+npm version patch
+git push --follow-tags
+```
+
+Watch the workflow run: `https://github.com/<githubAccount>/<my-pkg>/actions`
+
+Once green, the package is live on npm with cryptographic provenance.
+
+## Releasing future versions
+
+```bash
+# Make changes, commit, push
+git add -A && git commit -m "changes"
+git push
+
+# When ready to release:
+npm version patch       # or minor, or major
+git push --follow-tags
+```
+
+No login. No tokens. No npm CLI on release day. The Action handles everything.

package/skills/npm-trusts-github/references/setup-guide.md

@@ -0,0 +1,137 @@
+# Setup Guide — npm Trusted Publishing with GitHub Actions
+
+## What you're building
+
+A pipeline where `git push --follow-tags` on your machine triggers a GitHub
+Action that publishes your package to npm — with cryptographic provenance,
+no long-lived tokens, no 2FA prompts.
+
+## Prerequisites
+
+- npm account (creates personal scope `@your-username`)
+- GitHub account
+- Node.js ≥ 22 and npm ≥ 11.5.1 on your local machine
+
+## Step 1: Create the npm package locally
+
+```bash
+mkdir my-package && cd my-package
+
+# With personal scope:
+npm init --scope=@your-username
+
+# Or with org scope (if you created an org on npmjs.com):
+npm init --scope=@your-org
+
+# Or unscoped:
+npm init
+```
+
+The `name` field in `package.json` now reads `@your-username/my-package`.
+This is what users will `npm install`.
+
+Write your code. Add a README.
+
+## Step 2: Add the GitHub Actions workflow
+
+Create `.github/workflows/publish.yml`. The template is in `references/publish.yml`
+in this skill directory. Copy it verbatim — it has the correct permissions,
+npm upgrade step, and a bare `npm publish` command (no `--provenance`, no auth token).
+
+Key requirements in the workflow:
+- `permissions: id-token: write` at root level (not per-job)
+- `npm install -g npm@latest` before publish (trusted publishing needs ≥ 11.5.1)
+- `npm publish --access public` — bare, no extra flags
+- Triggers on tags matching `v*`
+
+## Step 3: Create the GitHub repo and push
+
+Create a repo on GitHub (public or private — Actions works on both, 2,000 free
+minutes/month for private repos).
+
+```bash
+git init
+git add -A
+git commit -m "Initial commit"
+git remote add origin git@github.com:your-username/my-package.git
+git branch -M main
+git push -u origin main
+```
+
+## Step 4: Publish the package manually ONCE
+
+This establishes the package on npm. The trusted publisher needs a package to
+publish *to* — it can't create a new package from scratch.
+
+```bash
+npm login                # prompts for username, password, 2FA if enabled
+npm publish --access public
+```
+
+Verify: `https://www.npmjs.com/package/@your-username/my-package`
+
+## Step 5: Configure the trusted publisher on npm
+
+1. Go to `https://www.npmjs.com/package/@your-username/my-package/access`
+2. Scroll to **Trusted Publisher**
+3. Click **GitHub Actions**
+4. Fill in:
+
+| Field | Value |
+|---|---|
+| Organization or user | Your GitHub username (case-sensitive) |
+| Repository | Your repo name (case-sensitive) |
+| Workflow filename | `publish.yml` (filename only, no path) |
+| Environment name | Leave empty |
+| Allowed actions | `npm publish` |
+
+**Critical:** npm does NOT validate this form on save. Every field must match
+exactly — a single typo produces an opaque `E404` error later.
+
+5. Click **Save**
+
+## Step 6: Restrict token access (optional, recommended)
+
+On the same page, under **Publishing access**, select:
+**"Require two-factor authentication and disallow tokens"**
+
+Trusted publishers bypass this check. It blocks any leaked API tokens from
+publishing to your package.
+
+## Step 7: Push a tag and watch it publish
+
+```bash
+npm version patch          # bumps version, creates git tag v1.x.x
+git push --follow-tags     # pushes code + tag, triggers the Action
+```
+
+Watch the workflow run: `https://github.com/your-username/my-package/actions`
+
+Once green, your package is live on npm with provenance.
+
+## Releasing future versions
+
+```bash
+# Make changes, commit, push as usual
+git add -A && git commit -m "changes"
+git push
+
+# When ready to release:
+npm version patch          # or minor, or major
+git push --follow-tags
+```
+
+That's it. No login, no tokens, no npm CLI on release day. The Action handles
+everything.
+
+## Organization-scoped packages
+
+If publishing under an org (`@myorg/pkg`):
+
+1. Create the org at `npmjs.com/org/create` (free)
+2. Publish the first version manually as org owner
+3. Configure trusted publisher on the org package's settings page
+4. The GitHub repo can be under your personal account or the org — no coupling
+
+Multiple maintainers: add them as org members on npm, and as repo collaborators
+on GitHub. Anyone who pushes a tag can trigger a publish.

package/skills/npm-trusts-github/references/troubleshooting.md

@@ -0,0 +1,109 @@
+# Troubleshooting — npm Trusted Publishing
+
+## Error: `ENEEDAUTH` — "need auth"
+
+**Full message:**
+```
+npm error code ENEEDAUTH
+npm error need auth This command requires you to be logged in
+```
+
+**Cause:** npm version too old for OIDC trusted publishing, or OIDC environment
+not detected.
+
+**Fix:** Add a step BEFORE `npm publish`:
+```yaml
+- run: npm install -g npm@latest
+```
+
+Trusted publishing requires npm ≥ 11.5.1. The default npm on `ubuntu-latest`
+runners is older and doesn't support OIDC.
+
+---
+
+## Error: `E404` — "not in this registry"
+
+**Full message:**
+```
+npm error code E404
+npm error 404 Not Found - PUT https://registry.npmjs.org/@scope%2fpackage
+npm error 404  '@scope/package@x.y.z' is not in this registry.
+```
+
+**Causes (check both):**
+
+1. **Typo in trusted publisher config.** The GitHub owner, repo name, or workflow
+   filename on npmjs.com doesn't match exactly (case-sensitive). npm doesn't
+   validate this form on save — it only fails at publish time.
+
+   Fix: go to npmjs.com → package → Settings → Access → Trusted Publisher.
+   Re-enter all fields carefully. Check:
+   - GitHub username case (e.g., `my-github-user` not `My-Github-User`)
+   - Repo name exactly as on GitHub
+   - Workflow filename is just `publish.yml`, not `.github/workflows/publish.yml`
+
+2. **Package never manually published.** The trusted publisher can publish new
+   versions of an existing package, but can't create a brand-new package.
+
+   Fix: `npm login && npm publish --access public` from your laptop once.
+
+---
+
+## Error: `EOTP` — "one-time password required"
+
+**Full message:**
+```
+npm error code EOTP
+npm error This operation requires a one-time password from your authenticator.
+```
+
+**Cause:** The workflow is using an old token-based publish path instead of
+OIDC trusted publishing. This happens when `NODE_AUTH_TOKEN` is set or when
+`--provenance` is passed as a flag.
+
+**Fix:**
+- Remove `NODE_AUTH_TOKEN` env var from the workflow
+- Remove `--provenance` flag from `npm publish` (provenance is automatic with OIDC)
+- The workflow's `npm publish` line should be bare: `npm publish --access public`
+
+Background: `--provenance` triggers the old provenance code path which expects
+a token. With trusted publishers, provenance signing is automatic — the flag
+is not only unnecessary but harmful.
+
+---
+
+## Symptom: Provenance signed successfully but package not published
+
+**What you see:** The workflow log shows "Provenance statement published to
+transparency log" followed by a publish error.
+
+**Cause:** Same as EOTP above — `--provenance` flag was passed, which signs the
+provenance but then routes publish auth through the token path. The token isn't
+set (or is wrong), so the publish fails even though provenance worked.
+
+**Fix:** Remove `--provenance` from the `npm publish` command.
+
+---
+
+## Symptom: Workflow never triggers
+
+**Check:**
+- Tag format: must match `v*` (e.g., `v1.0.0`, `v1.0.1`). `npm version patch`
+  creates these automatically.
+- Did you push with `--follow-tags`? `git push` alone doesn't push tags.
+- Run `git tag -l` to see local tags. Run `git ls-remote --tags origin` to see
+  remote tags.
+
+## Symptom: Actions tab shows no workflow at all
+
+The workflow file must be exactly at `.github/workflows/publish.yml` (not
+`.github/workflows/publish.yaml`, not `.github/publish.yml`).
+
+## General debugging
+
+1. Go to `github.com/you/repo/actions` → click the failing run → expand the
+   `publish` step → read the full log
+2. Check the trusted publisher config on npmjs.com for typos
+3. Verify `npm --version` in the workflow log is ≥ 11.5.1
+4. Try a manual publish from your laptop to confirm the package is healthy:
+   `npm publish --access public`