@aholbreich/agent-skills 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,12 +1,18 @@
 # Changelog
 
-## Unreleased
+## 0.5.0 - 2026-05-07
 
 Added:
 
+- `confluence-browser-fetch` now verifies an authenticated Confluence REST session before fetching pages, avoiding false positives from Atlassian login-page cookies.
+- `jira-browser-fetch` now verifies an authenticated Jira REST session before issue, JQL, or backlog fetches, avoiding false positives from Atlassian login-page cookies.
 - `jira-browser-fetch --backlog URL|BOARD_ID` to fetch all issues from a Jira Software board backlog through the authenticated browser session.
 - Backlog manifests at `raw/jira-board-<board-id>-backlog.json` and a `backlogs` section in `raw/jira-browser-fetch-run.json`.
 - Documentation examples for natural-language user requests that should invoke the skills.
+- Recommended `npx skills add aholbreich/agent-skills -g` cross-agent install path, plus collision/update guidance for Pi and project-local overrides.
+- CI/package dry-run scripts that use `npm pack --dry-run` for compatibility with older local pnpm launchers.
+- `agent-skills install --skill NAME` and `--pick` to install only selected bundled skills from the fallback npx installer.
+- Browser fetchers now auto-detect common Chromium-compatible browsers (Chrome, Chromium, Brave, Edge, Vivaldi) instead of only trying `/usr/bin/google-chrome` unless `CHROME` is set.
 
 ## 0.1.0 - 2026-05-06
 

package/COMPATIBILITY.md

@@ -4,96 +4,119 @@ This package is designed as a pure [Agent Skills](https://agentskills.io/) packa
 
 Each bundled skill is a directory containing `SKILL.md` plus scripts and references. The frontmatter follows the Agent Skills conventions: required `name` and `description`, directory name matching the skill name, lowercase hyphenated names, and optional `license`/`compatibility` metadata.
 
-## Compatibility matrix
-
-| Tool / Harness | Status | Install method |
-|---|---:|---|
-| Pi | Supported and tested | `pi install npm:@aholbreich/agent-skills` or `npx @aholbreich/agent-skills --target pi` |
-| Claude Code | Compatible Agent Skills layout | `npx @aholbreich/agent-skills --target claude` or copy `skills/*` into Claude's skills directory |
-| OpenAI Codex | Compatible Agent Skills layout | `npx @aholbreich/agent-skills --target codex` or copy `skills/*` into Codex's skills directory |
-| OpenClaw / generic Agent Skills harnesses | Compatible Agent Skills layout | `npx @aholbreich/agent-skills --target agents` or copy `skills/*` into `.agents/skills` / configured skills directory |
-| Any Agent Skills-compatible tool | Compatible layout | Copy each folder under `skills/` into the tool's configured skills directory |
+## Recommended installer
 
-## Install commands
-
-### Generic Agent Skills default
+For cross-agent installation, prefer the open Skills CLI:
 
 ```bash
-npx @aholbreich/agent-skills
+npx skills add aholbreich/agent-skills -g
 ```
 
-This installs to `~/.agents/skills` and is equivalent to:
+The Skills CLI discovers `skills/*/SKILL.md`, supports many agent clients, and symlinks agent-specific installs to a managed source by default. Use `--copy` only when symlinks are not supported.
+
+Useful variants:
 
 ```bash
-npx @aholbreich/agent-skills --target agents
+npx skills add aholbreich/agent-skills --list
+npx skills add aholbreich/agent-skills              # project-local/team install
+npx skills add aholbreich/agent-skills -g -y        # non-interactive global install
+npx skills update -g                                # update global skills installed by the Skills CLI
+npx skills list -g                                  # list global skills
 ```
 
-### Pi global
+## Compatibility matrix
 
-```bash
-pi install npm:@aholbreich/agent-skills
-```
+| Tool / Harness | Status | Recommended install method |
+|---|---:|---|
+| Pi | Supported and tested | `pi install npm:@aholbreich/agent-skills` for Pi-managed package updates, or `npx skills add aholbreich/agent-skills -g` for cross-agent installs |
+| Claude Code | Compatible Agent Skills layout | `npx skills add aholbreich/agent-skills -g --agent claude-code` |
+| OpenAI Codex | Compatible Agent Skills layout | `npx skills add aholbreich/agent-skills -g --agent codex` |
+| OpenClaw / generic Agent Skills harnesses | Compatible Agent Skills layout | `npx skills add aholbreich/agent-skills -g` or install to `.agents/skills` |
+| Any Agent Skills-compatible tool | Compatible layout | Copy or symlink each folder under `skills/` into the tool's configured skills directory |
+
+## Pi-native install commands
 
-or:
+Pi can install this repository as a Pi package directly from npm:
 
 ```bash
-npx @aholbreich/agent-skills --target pi
+pi install npm:@aholbreich/agent-skills
 ```
 
-### Pi project-local
+Project-local Pi package install:
 
 ```bash
 pi install -l npm:@aholbreich/agent-skills
 ```
 
-or:
+Temporary Pi run without installing:
 
 ```bash
-npx @aholbreich/agent-skills --target project
+pi -e npm:@aholbreich/agent-skills
 ```
 
-### Claude Code
+## Package fallback installer
+
+The npm package also ships a small dependency-free installer for environments where the Skills CLI is not available:
 
 ```bash
-npx @aholbreich/agent-skills --target claude
+npx @aholbreich/agent-skills
 ```
 
-Project-local Claude-style install:
+This installs to `~/.agents/skills` and is equivalent to:
 
 ```bash
-npx @aholbreich/agent-skills --target project-claude
+npx @aholbreich/agent-skills --target agents
 ```
 
-### Codex
+Other targets:
 
 ```bash
+npx @aholbreich/agent-skills --target pi
+npx @aholbreich/agent-skills --target claude
 npx @aholbreich/agent-skills --target codex
+npx @aholbreich/agent-skills --target project
+npx @aholbreich/agent-skills --target project-agents
+npx @aholbreich/agent-skills install --dir /path/to/skills
 ```
 
-Project-local Codex-style install:
+Select one or more skills with `--skill`, or use the interactive picker:
 
 ```bash
-npx @aholbreich/agent-skills --target project-codex
+npx @aholbreich/agent-skills install --skill jira-browser-fetch
+npx @aholbreich/agent-skills install --skill jira-browser-fetch --skill confluence-browser-fetch
+npx @aholbreich/agent-skills install --pick
 ```
 
-### Generic `.agents/skills`
+This fallback copies files. For symlinked, multi-agent installs, prefer `npx skills add aholbreich/agent-skills`.
 
-```bash
-npx @aholbreich/agent-skills --target agents
-```
+## Collision behavior
 
-Project-local generic install:
+Agent Skills are identified by their `name` frontmatter. If the same skill name exists in more than one discovered location, agents apply their own precedence rules.
 
-```bash
-npx @aholbreich/agent-skills --target project-agents
+Common precedence pattern:
+
+1. Project-local skills override user/global skills.
+2. User/global skills override bundled/system skills.
+3. Duplicate names are not merged.
+
+Pi example:
+
+```text
+.pi/skills/jira-browser-fetch/SKILL.md
 ```
 
-### Custom skills directory
+shadows:
 
-```bash
-npx @aholbreich/agent-skills install --dir /path/to/skills
+```text
+~/.nvm/.../@aholbreich/agent-skills/skills/jira-browser-fetch/SKILL.md
 ```
 
+That is useful for intentional repo-specific overrides, but it also means package updates may not affect the active skill in that repository. If you see a collision warning, choose one source of truth:
+
+- Keep the project-local skill if the repository intentionally customizes it.
+- Remove the project-local copy if you want the package/global install to be active.
+- Re-run the installer/update command for the install method that owns the active copy.
+
 ## Discoverability
 
 The package is tagged for discovery with npm keywords including:
@@ -106,7 +129,11 @@ The package is tagged for discovery with npm keywords including:
 - `claude-code`
 - `codex`
 
-After publishing to npm, tools and indexes that crawl npm packages for Agent Skills-compatible packages, such as skills registries, should be able to discover the package from its package metadata and conventional `skills/` directory.
+The repository is also compatible with the Skills CLI GitHub shorthand:
+
+```bash
+npx skills add aholbreich/agent-skills --list
+```
 
 If a registry requires manual submission, use:
 
@@ -114,6 +141,7 @@ If a registry requires manual submission, use:
 Package: @aholbreich/agent-skills
 Repository: https://github.com/aholbreich/agent-skills
 Skills directory: skills/
+Install command: npx skills add aholbreich/agent-skills -g
 ```
 
 ## Compliance checks in this repo
@@ -129,6 +157,6 @@ That includes:
 - JavaScript syntax checks.
 - Unit tests.
 - Skill frontmatter compliance checks.
-- `pnpm pack --dry-run` package content check.
+- `npm pack --dry-run` package content check.
 
 The compliance tests are intentionally local and dependency-free; they validate the parts of the Agent Skills structure that matter for broad tool compatibility.

package/README.md

@@ -15,49 +15,80 @@ This repository is a pure skills package. It currently contains browser-authenti
 
 This repository follows the Agent Skills directory convention: each skill lives under `skills/<skill-name>/SKILL.md` with matching frontmatter.
 
-Supported install targets:
+Recommended install paths:
 
-| Target | Command |
+| Use case | Command |
 |---|---|
-| Pi | `pi install npm:@aholbreich/agent-skills` |
-| Pi via npx | `npx @aholbreich/agent-skills --target pi` |
-| Claude Code-style global skills | `npx @aholbreich/agent-skills --target claude` |
-| Codex-style global skills | `npx @aholbreich/agent-skills --target codex` |
-| OpenClaw / generic `.agents/skills` | `npx @aholbreich/agent-skills --target agents` |
-| Project-local generic skills | `npx @aholbreich/agent-skills --target project-agents` |
+| Cross-agent wizard (recommended) | `npx skills add aholbreich/agent-skills -g` |
+| Pi package-managed install | `pi install npm:@aholbreich/agent-skills` |
+| Project-local/team skills | `npx skills add aholbreich/agent-skills` |
+| Package fallback without the aggregator | `npx @aholbreich/agent-skills` |
 
-See [`COMPATIBILITY.md`](COMPATIBILITY.md) for details.
+See [`COMPATIBILITY.md`](COMPATIBILITY.md) for details, including collision behavior.
 
 ## Requirements
 
 - Node.js `>=22`.
-- Google Chrome or Chromium.
+- A Chromium-compatible browser: Chrome, Chromium, Brave, Edge, or Vivaldi.
 - Access to the Jira/Confluence site in the browser account you use.
 - Pi, or any Agent Skills-compatible harness, if you want skill discovery.
 
 No npm runtime dependencies are required.
 
-## Install with Pi
+## Recommended install with the Skills CLI
 
-From GitHub:
+For most users, use the open `skills` installer. It discovers the skills in this repository, prompts for compatible agents, and symlinks agent-specific installs to a single managed source by default.
+
+Global/user install:
 
 ```bash
-pi install git:github.com/aholbreich/agent-skills
+npx skills add aholbreich/agent-skills -g
 ```
 
 Project-local install, useful for teams:
 
 ```bash
-pi install -l git:github.com/aholbreich/agent-skills
+npx skills add aholbreich/agent-skills
+```
+
+List available skills without installing:
+
+```bash
+npx skills add aholbreich/agent-skills --list
+```
+
+Non-interactive examples:
+
+```bash
+npx skills add aholbreich/agent-skills -g --skill '*' -y
+npx skills add aholbreich/agent-skills -g --agent claude-code --agent codex --skill jira-browser-fetch -y
+```
+
+Use `--copy` only when symlinks are not supported in your environment.
+
+## Pi-native install
+
+If you only use Pi and want Pi to manage package updates, install the npm package directly:
+
+```bash
+pi install npm:@aholbreich/agent-skills
+```
+
+Project-local Pi package install, useful for teams that already standardize on Pi packages:
+
+```bash
+pi install -l npm:@aholbreich/agent-skills
 ```
 
 Try without installing:
 
 ```bash
-pi -e git:github.com/aholbreich/agent-skills
+pi -e npm:@aholbreich/agent-skills
 ```
 
-## One-shot install with npx
+## Package fallback with npx
+
+If you cannot use the `skills` aggregator, this package also ships a small installer. It copies bundled skills into a selected skills directory.
 
 Install bundled skills into the generic Agent Skills directory `~/.agents/skills`:
 
@@ -65,24 +96,27 @@ Install bundled skills into the generic Agent Skills directory `~/.agents/skills
 npx @aholbreich/agent-skills
 ```
 
-This is equivalent to:
+Install for a specific target:
 
 ```bash
-npx @aholbreich/agent-skills --target agents
+npx @aholbreich/agent-skills install --target agents
+npx @aholbreich/agent-skills install --target claude
+npx @aholbreich/agent-skills install --target codex
+npx @aholbreich/agent-skills install --target project
 ```
 
-Install into a project-local `.pi/skills` directory:
+Install only selected skills:
 
 ```bash
-npx @aholbreich/agent-skills install --target project
+npx @aholbreich/agent-skills install --skill jira-browser-fetch
+npx @aholbreich/agent-skills install --skill confluence-browser-fetch
+npx @aholbreich/agent-skills install --skill jira-browser-fetch --target project
 ```
 
-Install for Claude Code, Codex, or generic Agent Skills harnesses:
+Or use the dependency-free interactive picker:
 
 ```bash
-npx @aholbreich/agent-skills install --target claude
-npx @aholbreich/agent-skills install --target codex
-npx @aholbreich/agent-skills install --target agents
+npx @aholbreich/agent-skills install --pick
 ```
 
 Overwrite existing installed skill directories:
@@ -97,6 +131,18 @@ List bundled skills:
 npx @aholbreich/agent-skills list
 ```
 
+## Collision and update notes
+
+Avoid installing the same skill into multiple locations for the same agent unless you intentionally want one copy to shadow another. Most agents give project-local skills priority over user/global skills.
+
+For example, in Pi a project skill at `.pi/skills/jira-browser-fetch/SKILL.md` shadows the same skill installed from `npm:@aholbreich/agent-skills`. In that case `pi update` updates the package, but the active project-local copy remains unchanged.
+
+Recommended rule of thumb:
+
+- Cross-agent users: prefer `npx skills add aholbreich/agent-skills -g`.
+- Pi-only users: prefer `pi install npm:@aholbreich/agent-skills`.
+- Team/repo-specific overrides: commit project-local skills intentionally and update them intentionally.
+
 ## Manual install
 
 ```bash

package/SECURITY.md

@@ -8,10 +8,11 @@ These skills are local automation tools. They can fetch potentially sensitive Ji
 
 The Jira and Confluence fetchers:
 
-1. launch or reuse Chrome/Chromium with a dedicated local profile,
+1. launch or reuse a Chromium-compatible browser with a dedicated local profile,
 2. let you complete normal Atlassian SSO in the browser,
 3. read Atlassian cookies through the local Chrome DevTools protocol,
-4. call Atlassian REST endpoints with those cookies.
+4. verify those cookies represent an authenticated Jira/Confluence REST session,
+5. call Atlassian REST endpoints with those cookies.
 
 They do **not** require you to paste API tokens or cookies into chat.
 

package/bin/agent-skills.js

@@ -5,6 +5,7 @@ const fs = require('fs');
 const fsp = require('fs/promises');
 const os = require('os');
 const path = require('path');
+const readline = require('readline/promises');
 
 const packageRoot = path.resolve(__dirname, '..');
 const sourceSkillsDir = path.join(packageRoot, 'skills');
@@ -27,6 +28,11 @@ function usage() {
 
 Install this package's Agent Skills into a local skills directory.
 
+Recommended cross-agent installer:
+  npx skills add aholbreich/agent-skills -g
+
+This fallback installer copies files for environments where the Skills CLI is unavailable.
+
 Commands:
   install                 Install skills (default command)
   list                    List bundled skills
@@ -36,11 +42,16 @@ Commands:
 Options for install:
   --target NAME           pi | agents | claude | codex | openclaw | project | project-agents | project-claude | project-codex (default: agents)
   --dir PATH              Custom skills directory, overrides --target
+  --skill NAME            Install only selected skill(s); repeatable, comma-separated, or '*' for all
+  --pick                  Interactively choose which bundled skills to install
   --force                 Overwrite existing skill directories
   --dry-run               Show what would be copied without writing
 
 Examples:
+  npx skills add aholbreich/agent-skills -g
   npx @aholbreich/agent-skills
+  npx @aholbreich/agent-skills install --skill jira-browser-fetch
+  npx @aholbreich/agent-skills install --pick
   npx @aholbreich/agent-skills install --target agents --force
   npx @aholbreich/agent-skills install --target pi --force
   npx @aholbreich/agent-skills install --target project
@@ -74,16 +85,72 @@ async function copyDir(src, dest) {
   await fsp.cp(src, dest, { recursive: true, force: true, errorOnExist: false });
 }
 
+function addSkillFilters(filters, value) {
+  if (!value) throw new Error('--skill requires a skill name');
+  for (const item of String(value).split(',')) {
+    const skill = item.trim();
+    if (skill) filters.push(skill);
+  }
+}
+
+function selectSkills(allSkills, filters) {
+  if (!filters.length || filters.includes('*')) return allSkills;
+  const known = new Set(allSkills);
+  const selected = [...new Set(filters)];
+  const unknown = selected.filter(skill => !known.has(skill));
+  if (unknown.length) {
+    throw new Error(`Unknown skill(s): ${unknown.join(', ')}. Available: ${allSkills.join(', ')}`);
+  }
+  return selected.sort();
+}
+
+function parsePickedSkills(answer, allSkills) {
+  const value = String(answer || '').trim();
+  if (!value || value === '*') return allSkills;
+  const selected = [];
+  for (const raw of value.split(',')) {
+    const token = raw.trim();
+    if (!token) continue;
+    if (/^\d+$/.test(token)) {
+      const index = Number(token) - 1;
+      if (index < 0 || index >= allSkills.length) throw new Error(`Invalid skill number: ${token}`);
+      selected.push(allSkills[index]);
+    } else {
+      selected.push(token);
+    }
+  }
+  return selectSkills(allSkills, selected);
+}
+
+async function pickSkills(allSkills) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('--pick requires an interactive terminal; use --skill NAME for non-interactive installs');
+  }
+  console.log('Bundled skills:');
+  allSkills.forEach((skill, index) => console.log(`  ${index + 1}) ${skill}`));
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question('Install which skills? Enter numbers/names separated by commas, or blank for all: ');
+    return parsePickedSkills(answer, allSkills);
+  } finally {
+    rl.close();
+  }
+}
+
 async function install(args) {
   let target = 'agents';
   let customDir = '';
   let force = false;
   let dryRun = false;
+  let pick = false;
+  const skillFilters = [];
 
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--target') target = args[++i];
     else if (a === '--dir') customDir = args[++i];
+    else if (a === '--skill' || a === '-s') addSkillFilters(skillFilters, args[++i]);
+    else if (a === '--pick') pick = true;
     else if (a === '--force') force = true;
     else if (a === '--dry-run') dryRun = true;
     else if (a === '-h' || a === '--help') { usage(); return; }
@@ -93,11 +160,15 @@ async function install(args) {
   if (!customDir && !TARGETS[target]) {
     throw new Error(`Unknown target '${target}'. Valid targets: ${Object.keys(TARGETS).join(', ')}`);
   }
+  if (pick && skillFilters.length) {
+    throw new Error('Use either --pick or --skill, not both');
+  }
 
   const destRoot = path.resolve(expandHome(customDir || TARGETS[target]));
-  const skills = await listSkills();
+  const allSkills = await listSkills();
+  const skills = pick ? await pickSkills(allSkills) : selectSkills(allSkills, skillFilters);
 
-  console.log(`Installing ${skills.length} skill(s) to ${destRoot}`);
+  console.log(`Installing ${skills.length} of ${allSkills.length} skill(s) to ${destRoot}`);
   if (dryRun) console.log('Dry run: no files will be written.');
 
   if (!dryRun) await fsp.mkdir(destRoot, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aholbreich/agent-skills",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Handcrafted Agent Skills for browser-authenticated Jira and Confluence ingestion, LLM wiki workflows, and developer automation.",
   "license": "MIT",
   "type": "commonjs",
@@ -42,10 +42,10 @@
   "scripts": {
     "check": "node --check bin/agent-skills.js && node --check skills/jira-browser-fetch/scripts/jira-browser-fetch.js && node --check skills/jira-browser-fetch/scripts/lib.js && node --check skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js && node --check skills/confluence-browser-fetch/scripts/lib.js",
     "test": "node --test",
-    "ci": "pnpm run check && pnpm test && pnpm pack --dry-run",
-    "pack:dry": "pnpm pack --dry-run",
-    "prepack": "pnpm run check",
-    "prepublishOnly": "pnpm run check && pnpm test"
+    "ci": "npm run check && npm test && npm pack --dry-run",
+    "pack:dry": "npm pack --dry-run",
+    "prepack": "npm run check",
+    "prepublishOnly": "npm run check && npm test"
   },
   "pi": {
     "skills": [

package/skills/confluence-browser-fetch/SKILL.md

@@ -2,14 +2,14 @@
 name: confluence-browser-fetch
 description: Fetch Confluence Cloud pages through an authenticated Chrome browser session when API tokens do not work, especially with Microsoft/SSO. Use to archive Confluence page JSON, storage/view HTML, browser HTML, attachments, CQL search results, or page descendants into a raw wiki folder.
 license: MIT
-compatibility: Agent Skills standard. Tested with Pi; installable into Claude Code, Codex, OpenClaw/generic .agents skills directories. Requires Node.js 22+ with built-in fetch/WebSocket and Google Chrome/Chromium with remote debugging. No npm dependencies.
+compatibility: Agent Skills standard. Tested with Pi; installable into Claude Code, Codex, OpenClaw/generic .agents skills directories. Requires Node.js 22+ with built-in fetch/WebSocket and a Chromium-compatible browser with remote debugging (Chrome, Chromium, Brave, Edge, or Vivaldi). No npm dependencies.
 ---
 
 # Confluence Browser Fetch
 
 Use this skill when a user wants Confluence pages ingested into an LLM wiki `raw/` folder and normal Atlassian API-token auth is unavailable or inconvenient due to SSO.
 
-The script opens/reuses Chrome with a dedicated profile, lets the user complete SSO once, extracts Atlassian cookies via Chrome DevTools, and fetches Confluence REST data plus rendered page HTML and attachments.
+The script opens/reuses Chrome with a dedicated profile, lets the user complete SSO once, extracts Atlassian cookies via Chrome DevTools, verifies they represent an authenticated Confluence REST session, and fetches Confluence REST data plus rendered page HTML and attachments.
 
 ## Safety
 

package/skills/confluence-browser-fetch/references/usage.md

@@ -7,24 +7,25 @@ Confluence Cloud pages are often behind Microsoft/SSO. API-token Basic auth may
 1. Launching Chrome with a dedicated user profile.
 2. Letting the user complete normal SSO.
 3. Reading Atlassian cookies through local Chrome DevTools.
-4. Calling Confluence REST endpoints with those cookies.
+4. Verifying those cookies represent an authenticated Confluence REST session.
+5. Calling Confluence REST endpoints with those cookies.
 
 No cookie or API token needs to be pasted into chat.
 
 ## Requirements
 
 - Node.js 22+.
-- Google Chrome or Chromium.
+- A Chromium-compatible browser: Chrome, Chromium, Brave, Edge, or Vivaldi.
 - Access to the Confluence page with the logged-in account.
 
 Check:
 
 ```bash
 node --version
-which google-chrome || which chromium || which chromium-browser
+which google-chrome || which chromium || which chromium-browser || which brave-browser || which microsoft-edge
 ```
 
-If Chrome has a different path:
+The script auto-detects common Chromium-compatible browsers. If yours has a different path:
 
 ```bash
 CHROME=/path/to/chrome scripts/confluence-browser-fetch.js 123456
@@ -113,7 +114,7 @@ By default, pages with matching local `metadata.json` Confluence `version.number
 | `CONFLUENCE_REQUEST_TIMEOUT_SEC` | Per-request timeout, default `60` |
 | `CONFLUENCE_SKIP_UNCHANGED` | Set to `0` to disable default skip-unchanged behavior |
 | `CONFLUENCE_CHROME_PROFILE` | Dedicated Chrome profile dir |
-| `CHROME` | Chrome executable path |
+| `CHROME` / `CHROMIUM` | Browser executable path override |
 
 ## Output Files
 
@@ -129,13 +130,17 @@ For each page:
 
 ## Troubleshooting
 
-### `no Atlassian cookies yet`
+### `no Atlassian cookies yet` / `not authenticated yet`
 
-Complete SSO in the Chrome window opened by the script.
+Complete SSO in the Chrome window opened by the script. Login-page cookies are not enough; the script waits until a Confluence REST session probe succeeds.
+
+### `Could not verify authenticated Confluence session`
+
+The browser did not reach an authenticated Confluence REST session before `--wait` expired. Complete SSO, confirm you can open the target Confluence site in that browser profile, then rerun or increase `--wait`.
 
 ### `Page failed HTTP 404`
 
-The authenticated user cannot see the page, or the page ID/site is wrong.
+After authentication is verified, this usually means the authenticated user cannot see the page, or the page ID/site is wrong.
 
 ### URL cannot be resolved
 

package/skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
+const fs = require('fs');
 const fsp = require('fs/promises');
 const os = require('os');
 const path = require('path');
@@ -115,8 +116,50 @@ async function waitDevtools() {
   throw new Error('Chrome DevTools endpoint did not start');
 }
 
+function isExecutable(file) {
+  try { fs.accessSync(file, fs.constants.X_OK); return true; } catch { return false; }
+}
+
+function resolveBrowserCandidate(candidate) {
+  if (!candidate) return null;
+  if (candidate.includes(path.sep)) return isExecutable(candidate) ? candidate : null;
+  for (const dir of String(process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const full = path.join(dir, candidate);
+    if (isExecutable(full)) return full;
+  }
+  return null;
+}
+
+function findBrowserExecutable() {
+  const candidates = [
+    process.env.CHROME,
+    process.env.CHROMIUM,
+    'google-chrome',
+    'google-chrome-stable',
+    'chromium',
+    'chromium-browser',
+    'brave-browser',
+    'brave',
+    'microsoft-edge',
+    'microsoft-edge-stable',
+    'vivaldi',
+    'vivaldi-stable',
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Vivaldi.app/Contents/MacOS/Vivaldi',
+  ];
+  for (const candidate of candidates) {
+    const resolved = resolveBrowserCandidate(candidate);
+    if (resolved) return resolved;
+  }
+  throw new Error('Could not find a Chromium-compatible browser. Install Chrome/Chromium/Brave/Edge/Vivaldi or set CHROME=/path/to/browser.');
+}
+
 function launchChrome(url) {
-  const chrome = process.env.CHROME || '/usr/bin/google-chrome';
+  const browser = findBrowserExecutable();
   const args = [
     `--remote-debugging-port=${opts.port}`,
     '--remote-debugging-address=127.0.0.1',
@@ -126,13 +169,15 @@ function launchChrome(url) {
     '--no-default-browser-check',
     url,
   ];
-  const child = spawn(chrome, args, { detached: true, stdio: 'ignore' });
+  console.log(`Launching browser: ${browser}`);
+  const child = spawn(browser, args, { detached: true, stdio: 'ignore' });
+  child.on('error', err => console.error(`Failed to launch browser ${browser}: ${err.message}`));
   child.unref();
 }
 
 async function ensureBrowser(openUrl) {
   if (!(await devtoolsReady())) {
-    console.log(`Opening Chrome with reusable profile: ${opts.profileDir}`);
+    console.log(`Opening Chromium-compatible browser with reusable profile: ${opts.profileDir}`);
     launchChrome(openUrl || wikiBase);
   } else {
     console.log(`Reusing Chrome DevTools on port ${opts.port}`);
@@ -246,6 +291,30 @@ async function fetchJson(url, cookie) {
   return { ...result, json };
 }
 
+async function verifyConfluenceSession(cookie) {
+  if (!cookie) return { ok: false, message: 'no Atlassian cookies yet' };
+
+  const probes = [
+    `${wikiBase}/rest/api/user/current`,
+    `${wikiBase}/rest/api/space?limit=1`,
+  ];
+
+  for (const url of probes) {
+    const result = await fetchJson(url, cookie);
+    if (result.status === 200 && result.json) return { ok: true, url };
+    if (result.status === 401 || result.status === 403) {
+      return { ok: false, message: `not authenticated yet (${result.status} from ${url})` };
+    }
+    if (result.status === 302 || result.status === 303) {
+      return { ok: false, message: `still redirected to login (${result.status} from ${url})` };
+    }
+    if (result.status === 404) continue;
+    return { ok: false, message: `session probe HTTP ${result.status} from ${url}` };
+  }
+
+  return { ok: false, message: 'could not verify Confluence session' };
+}
+
 async function getCookieWithWait(openUrl) {
   await ensureBrowser(openUrl || wikiBase);
   console.log(`If prompted in Chrome, complete SSO for: ${openUrl || wikiBase}`);
@@ -254,14 +323,19 @@ async function getCookieWithWait(openUrl) {
   while (Date.now() < deadline) {
     try {
       const cookie = await getCookieHeader();
-      if (cookie) return cookie;
-      last = 'no Atlassian cookies yet';
+      const session = await verifyConfluenceSession(cookie);
+      if (session.ok) {
+        process.stdout.write('\n');
+        console.log(`Authenticated Confluence session verified via ${session.url}`);
+        return cookie;
+      }
+      last = session.message;
     } catch (e) { last = e.message; }
     process.stdout.write(`\r${new Date().toLocaleTimeString()} ${last.padEnd(120).slice(0, 120)}`);
     await sleep(3000);
   }
   process.stdout.write('\n');
-  throw new Error(`Could not get browser cookies. Last result: ${last}`);
+  throw new Error(`Could not verify authenticated Confluence session. Last result: ${last}`);
 }
 
 function cqlQuote(s) {

package/skills/jira-browser-fetch/SKILL.md

@@ -2,14 +2,14 @@
 name: jira-browser-fetch
 description: Fetch Jira issue raw data through an authenticated Chrome browser session when jira-cli/API tokens do not work, especially with Microsoft/SSO. Use to archive Jira issues, Jira Software board backlogs, JQL result sets, linked tickets, rendered HTML/XML, remote links, and attachments into a raw wiki folder.
 license: MIT
-compatibility: Agent Skills standard. Tested with Pi; installable into Claude Code, Codex, OpenClaw/generic .agents skills directories. Requires Node.js 22+ with built-in fetch/WebSocket and Google Chrome/Chromium with remote debugging. No npm dependencies.
+compatibility: Agent Skills standard. Tested with Pi; installable into Claude Code, Codex, OpenClaw/generic .agents skills directories. Requires Node.js 22+ with built-in fetch/WebSocket and a Chromium-compatible browser with remote debugging (Chrome, Chromium, Brave, Edge, or Vivaldi). No npm dependencies.
 ---
 
 # Jira Browser Fetch
 
 Use this skill when Jira API-token authentication fails or the organization uses Microsoft/SSO and the user wants Jira issues, Jira Software board backlogs, or JQL result sets archived into a local raw/wiki folder.
 
-The bundled script opens/reuses Chrome with a dedicated profile, lets the user complete SSO once, extracts Jira cookies via Chrome DevTools, and fetches Jira REST/HTML/XML/attachments into a raw directory.
+The bundled script opens/reuses Chrome with a dedicated profile, lets the user complete SSO once, extracts Jira cookies via Chrome DevTools, verifies they represent an authenticated Jira REST session, and fetches Jira REST/HTML/XML/attachments into a raw directory.
 
 ## Safety
 

package/skills/jira-browser-fetch/references/usage.md

@@ -7,13 +7,14 @@ Some Jira Cloud organizations use Microsoft/SSO and block or break API-token Bas
 1. Launching Chrome with a dedicated user profile.
 2. Letting the user complete normal SSO in Chrome.
 3. Reading Jira cookies through the local Chrome DevTools protocol.
-4. Calling Jira REST endpoints with those cookies.
+4. Verifying those cookies represent an authenticated Jira REST session.
+5. Calling Jira REST endpoints with those cookies.
 
 No token or cookie needs to be pasted into chat.
 
 ## Requirements
 
-- Linux/macOS with Chrome or Chromium.
+- Linux/macOS with a Chromium-compatible browser: Chrome, Chromium, Brave, Edge, or Vivaldi.
 - Node.js 22+.
 - Network access to the Jira site.
 
@@ -21,10 +22,10 @@ Check:
 
 ```bash
 node --version
-which google-chrome || which chromium || which chromium-browser
+which google-chrome || which chromium || which chromium-browser || which brave-browser || which microsoft-edge
 ```
 
-If Chrome has a different path:
+The script auto-detects common Chromium-compatible browsers. If yours has a different path:
 
 ```bash
 CHROME=/path/to/chrome scripts/jira-browser-fetch.js PROJ-123
@@ -125,7 +126,7 @@ Default max attachment download size is `5mb`. Use `--max-attachment-size unlimi
 | `JIRA_MAX_SEARCH_RESULTS` | Max issues added per JQL or backlog search, default `1000` |
 | `JIRA_MAX_ATTACHMENT_SIZE` / `JIRA_MAX_ATTACHMENT_BYTES` | Max attachment download size, default `5mb`; skipped files are listed in `attachments.json` |
 | `JIRA_CHROME_PROFILE` | Dedicated Chrome profile dir |
-| `CHROME` | Chrome executable path |
+| `CHROME` / `CHROMIUM` | Browser executable path override |
 
 ## Example user requests
 
@@ -139,17 +140,21 @@ Agents should invoke this skill for requests such as:
 
 ## Troubleshooting
 
-### `no Jira cookies yet`
+### `no Atlassian cookies yet` / `not authenticated yet`
 
-Complete SSO in the Chrome window opened by the script.
+Complete SSO in the Chrome window opened by the script. Login-page cookies are not enough; the script waits until a Jira REST session probe succeeds.
+
+### `Could not verify authenticated Jira session`
+
+The browser did not reach an authenticated Jira REST session before `--wait` expired. Complete SSO, confirm you can open the target Jira site in that browser profile, then rerun or increase `--wait`.
 
 ### `HTTP 404 Issue does not exist or you do not have permission`
 
 The session works, but the account cannot see the issue or the key is not a Jira issue.
 
-### Chrome does not open
+### Browser does not open
 
-Set the executable path:
+The script tries `CHROME`, `CHROMIUM`, then common Chrome/Chromium/Brave/Edge/Vivaldi executable names and macOS app paths. If auto-detection fails, set the executable path:
 
 ```bash
 CHROME=/usr/bin/chromium scripts/jira-browser-fetch.js PROJ-123

package/skills/jira-browser-fetch/scripts/jira-browser-fetch.js

@@ -128,8 +128,50 @@ async function waitDevtools() {
   throw new Error('Chrome DevTools endpoint did not start');
 }
 
+function isExecutable(file) {
+  try { fs.accessSync(file, fs.constants.X_OK); return true; } catch { return false; }
+}
+
+function resolveBrowserCandidate(candidate) {
+  if (!candidate) return null;
+  if (candidate.includes(path.sep)) return isExecutable(candidate) ? candidate : null;
+  for (const dir of String(process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const full = path.join(dir, candidate);
+    if (isExecutable(full)) return full;
+  }
+  return null;
+}
+
+function findBrowserExecutable() {
+  const candidates = [
+    process.env.CHROME,
+    process.env.CHROMIUM,
+    'google-chrome',
+    'google-chrome-stable',
+    'chromium',
+    'chromium-browser',
+    'brave-browser',
+    'brave',
+    'microsoft-edge',
+    'microsoft-edge-stable',
+    'vivaldi',
+    'vivaldi-stable',
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Vivaldi.app/Contents/MacOS/Vivaldi',
+  ];
+  for (const candidate of candidates) {
+    const resolved = resolveBrowserCandidate(candidate);
+    if (resolved) return resolved;
+  }
+  throw new Error('Could not find a Chromium-compatible browser. Install Chrome/Chromium/Brave/Edge/Vivaldi or set CHROME=/path/to/browser.');
+}
+
 function launchChrome(url) {
-  const chrome = process.env.CHROME || '/usr/bin/google-chrome';
+  const browser = findBrowserExecutable();
   const args = [
     `--remote-debugging-port=${opts.port}`,
     '--remote-debugging-address=127.0.0.1',
@@ -139,7 +181,9 @@ function launchChrome(url) {
     '--no-default-browser-check',
     url,
   ];
-  const child = spawn(chrome, args, { detached: true, stdio: 'ignore' });
+  console.log(`Launching browser: ${browser}`);
+  const child = spawn(browser, args, { detached: true, stdio: 'ignore' });
+  child.on('error', err => console.error(`Failed to launch browser ${browser}: ${err.message}`));
   child.unref();
 }
 
@@ -223,21 +267,57 @@ async function fetchJson(url, cookie, accept) {
   return { ...result, json };
 }
 
+async function verifyJiraSession(cookie) {
+  if (!cookie) return { ok: false, message: 'no Atlassian cookies yet' };
+
+  const probes = [
+    `${opts.server}/rest/api/3/myself`,
+    `${opts.server}/rest/api/2/myself`,
+  ];
+
+  for (const url of probes) {
+    const result = await fetchJson(url, cookie, 'application/json');
+    if (result.status === 200 && result.json && (result.json.accountId || result.json.name || result.json.key || result.json.displayName)) {
+      return { ok: true, url };
+    }
+    if (result.status === 200) {
+      const kind = result.json ? 'unexpected JSON response' : (/html/i.test(result.contentType) ? 'login page' : 'non-JSON response');
+      return { ok: false, message: `not authenticated yet (${kind} from ${url})` };
+    }
+    if (result.status === 401 || result.status === 403) {
+      return { ok: false, message: `not authenticated yet (${result.status} from ${url})` };
+    }
+    if (result.status === 302 || result.status === 303) {
+      return { ok: false, message: `still redirected to login (${result.status} from ${url})` };
+    }
+    if (result.status === 404) continue;
+    return { ok: false, message: `session probe HTTP ${result.status} from ${url}` };
+  }
+
+  return { ok: false, message: 'could not verify Jira session' };
+}
+
 async function getCookieWithWait(openUrl) {
   await ensureBrowser(openUrl || `${opts.server}/`);
+  console.log(`If prompted in Chrome, complete SSO for: ${openUrl || opts.server}`);
   const deadline = Date.now() + opts.waitSec * 1000;
   let last = '';
   while (Date.now() < deadline) {
     try {
       const cookie = await getCookieHeader();
-      if (cookie) return cookie;
-      last = 'no Jira cookies yet';
+      const session = await verifyJiraSession(cookie);
+      if (session.ok) {
+        process.stdout.write('\n');
+        console.log(`Authenticated Jira session verified via ${session.url}`);
+        return cookie;
+      }
+      last = session.message;
     } catch (e) { last = e.message; }
     process.stdout.write(`\r${new Date().toLocaleTimeString()} ${last.padEnd(120).slice(0, 120)}`);
     await sleep(3000);
   }
   process.stdout.write('\n');
-  throw new Error(`Could not get Jira browser cookies. Last result: ${last}`);
+  throw new Error(`Could not verify authenticated Jira session. Last result: ${last}`);
 }
 
 async function searchJql(jql) {
@@ -271,21 +351,16 @@ async function searchJql(jql) {
   return [...new Set(found)];
 }
 
-async function fetchBacklogPageWithWait(url) {
+async function fetchBacklogPageWithWait(url, cookie) {
   const deadline = Date.now() + opts.waitSec * 1000;
   let last = '';
   while (Date.now() < deadline) {
     try {
-      const cookie = await getCookieHeader();
-      if (!cookie) {
-        last = 'no Jira cookies yet';
-      } else {
-        const result = await fetchJson(url, cookie, 'application/json');
-        if (result.status === 200 && result.json && Array.isArray(result.json.issues)) return result.json;
-        last = `HTTP ${result.status} ${(result.text || '').slice(0, 180).replace(/\s+/g, ' ')}`;
-      }
+      const result = await fetchJson(url, cookie, 'application/json');
+      if (result.status === 200 && result.json && Array.isArray(result.json.issues)) return result.json;
+      last = `HTTP ${result.status} ${(result.text || '').slice(0, 180).replace(/\s+/g, ' ')}`;
     } catch (e) { last = e.message; }
-    process.stdout.write(`\r${new Date().toLocaleTimeString()} waiting for authenticated Jira backlog session: ${last.padEnd(120).slice(0, 120)}`);
+    process.stdout.write(`\r${new Date().toLocaleTimeString()} waiting for Jira backlog access: ${last.padEnd(120).slice(0, 120)}`);
     await sleep(3000);
   }
   process.stdout.write('\n');
@@ -294,8 +369,7 @@ async function fetchBacklogPageWithWait(url) {
 
 async function searchBacklog(input) {
   const backlog = parseBacklogInput(input, opts.server);
-  await ensureBrowser(backlog.browseUrl);
-  console.log(`If prompted in Chrome, complete SSO for: ${backlog.browseUrl}`);
+  const cookie = await getCookieWithWait(backlog.browseUrl);
   console.log(`Waiting up to ${opts.waitSec}s for Jira backlog access...`);
 
   const found = [];
@@ -305,7 +379,7 @@ async function searchBacklog(input) {
   while (found.length < opts.maxSearchResults) {
     const limit = Math.min(pageSize, opts.maxSearchResults - found.length);
     const url = backlogApiUrl(opts.server, backlog.boardId, startAt, limit);
-    const page = await fetchBacklogPageWithWait(url);
+    const page = await fetchBacklogPageWithWait(url, cookie);
     const keys = issueKeysFromAgilePage(page);
     for (const key of keys) found.push(key);
     console.log(`Fetched backlog page board=${backlog.boardId} startAt=${startAt}, issues=${keys.length}${typeof page.total === 'number' ? `, total=${page.total}` : ''}`);
@@ -426,7 +500,7 @@ async function downloadAttachments(issueJson, cookie, outDir) {
 
 async function ensureBrowser(browseUrl) {
   if (!(await devtoolsReady())) {
-    console.log(`Opening Chrome with reusable profile: ${opts.profileDir}`);
+    console.log(`Opening Chromium-compatible browser with reusable profile: ${opts.profileDir}`);
     launchChrome(browseUrl);
   } else {
     console.log(`Reusing Chrome DevTools on port ${opts.port}`);
@@ -443,32 +517,11 @@ async function fetchIssue(issue) {
   const remoteLinksUrl = `${opts.server}/rest/api/3/issue/${issue}/remotelink`;
   const xmlUrl = `${opts.server}/si/jira.issueviews:issue-xml/${issue}/${issue}.xml`;
 
-  await ensureBrowser(browseUrl);
-  console.log(`If prompted in Chrome, complete SSO for: ${browseUrl}`);
-  console.log(`Waiting up to ${opts.waitSec}s for Jira session...`);
-
-  const deadline = Date.now() + opts.waitSec * 1000;
-  let last = '';
-  let cookie = '';
-  let rest = null;
-
-  while (Date.now() < deadline) {
-    try {
-      cookie = await getCookieHeader();
-      if (cookie) {
-        rest = await fetchText(restUrl, cookie, 'application/json');
-        const body = rest.text || '';
-        if (rest.status === 200 && body.includes(`"key":"${issue}"`)) break;
-        last = `HTTP ${rest.status} ${body.slice(0, 110).replace(/\s+/g, ' ')}`;
-      } else last = 'no Jira cookies yet';
-    } catch (e) { last = e.message; }
-    process.stdout.write(`\r${new Date().toLocaleTimeString()} ${last.padEnd(120).slice(0, 120)}`);
-    await sleep(3000);
-  }
-  process.stdout.write('\n');
+  const cookie = await getCookieWithWait(browseUrl);
 
-  if (!rest || rest.status !== 200 || !rest.text.includes(`"key":"${issue}"`)) {
-    throw new Error(`Could not fetch ${issue}. Last result: ${last}`);
+  const rest = await fetchJson(restUrl, cookie, 'application/json');
+  if (rest.status !== 200 || !rest.json || rest.json.key !== issue) {
+    throw new Error(`Could not fetch ${issue}. HTTP ${rest.status}: ${(rest.text || '').slice(0, 300).replace(/\s+/g, ' ')}`);
   }
 
   await fsp.writeFile(path.join(outDir, 'issue.json'), rest.text);