@aholbreich/agent-skills 0.1.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@aholbreich/agent-skills",
+  "version": "0.1.0",
+  "description": "Handcrafted Agent Skills for browser-authenticated Jira and Confluence ingestion, LLM wiki workflows, and developer automation.",
+  "license": "MIT",
+  "type": "commonjs",
+  "keywords": [
+    "pi-package",
+    "agent-skills",
+    "agent-skill",
+    "agentskills",
+    "skills.sh",
+    "claude-code",
+    "codex",
+    "open-claw",
+    "llm",
+    "jira",
+    "confluence",
+    "atlassian",
+    "browser-automation",
+    "llm-wiki"
+  ],
+  "homepage": "https://github.com/aholbreich/agent-skills#readme",
+  "bugs": {
+    "url": "https://github.com/aholbreich/agent-skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aholbreich/agent-skills.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "agent-skills": "bin/agent-skills.js",
+    "jira-browser-fetch": "skills/jira-browser-fetch/scripts/jira-browser-fetch.js",
+    "confluence-browser-fetch": "skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js"
+  },
+  "pi": {
+    "skills": [
+      "skills"
+    ]
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "README.md",
+    "COMPATIBILITY.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
+  ],
+  "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"
+  }
+}

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

@@ -0,0 +1,114 @@
+---
+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.
+---
+
+# 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.
+
+## Safety
+
+- Never ask users to paste Confluence cookies or API tokens into chat.
+- Prefer browser automation so secrets remain in the local Chrome profile.
+- Treat fetched pages and attachments as confidential.
+- This skill is read-only: do not create, edit, delete, or move Confluence pages.
+
+## Script
+
+```bash
+scripts/confluence-browser-fetch.js <URL|PAGE-ID> [...] [options]
+```
+
+Important options:
+
+```bash
+--site URL               Atlassian site, e.g. https://example.atlassian.net
+--raw-dir DIR            output raw directory
+--space KEY              Confluence space key for --title search
+--title TITLE            resolve and fetch page by exact title
+--cql CQL                search Confluence and fetch matching pages
+--descendants            fetch descendant pages
+--max-search-results N   limit CQL result fetches
+--max-attachment-size S  skip attachment files larger than S (default 5mb; use unlimited to disable)
+--force                  re-fetch even when local page version is current
+--no-skip-unchanged      disable version/timestamp skip check
+--retries N              retry transient HTTP failures
+--request-timeout SEC    per-request timeout
+--no-attachments         skip attachments
+--no-browser-html        skip rendered browser HTML
+```
+
+## Typical Workflow
+
+1. If the user gives a Confluence URL, run the script directly with that URL.
+2. If the user gives a title, ask for the space key or use `--cql`.
+3. Show the command before running it.
+4. If Chrome opens, ask the user to complete SSO in that browser window.
+5. Verify saved files.
+6. If this is an LLM wiki ingest, process the saved `raw/confluence/...` material into `wiki/` per the project `AGENTS.md`.
+
+Example:
+
+```bash
+scripts/confluence-browser-fetch.js \
+  "https://example.atlassian.net/wiki/spaces/ABC/pages/123456/Page+Title" \
+  --site https://example.atlassian.net \
+  --raw-dir ./raw
+```
+
+Fetch a page and all descendants:
+
+```bash
+scripts/confluence-browser-fetch.js \
+  123456 \
+  --site https://example.atlassian.net \
+  --raw-dir ./raw \
+  --descendants
+```
+
+Fetch by CQL:
+
+```bash
+scripts/confluence-browser-fetch.js \
+  --site https://example.atlassian.net \
+  --raw-dir ./raw \
+  --cql 'space = ABC and type = page and text ~ "billing"'
+```
+
+## Output Layout
+
+```text
+raw/confluence/<SPACE>/<PAGE-ID>-<slug>/
+├── page.json          # Confluence REST content with storage/view HTML and metadata
+├── page.storage.html  # Confluence storage format
+├── page.view.html     # REST-rendered view body
+├── page.browser.html  # browser page HTML, if enabled
+├── metadata.json      # fetch metadata
+├── attachments.json   # attachment manifest, including skipped large-file references
+└── attachments/       # downloaded attachments under max-size threshold
+```
+
+A run manifest is written to:
+
+```text
+raw/confluence-browser-fetch-run.json
+```
+
+## Installation / PATH
+
+Use directly by path, or install a symlink:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf ~/.pi/agent/skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js ~/.local/bin/confluence-browser-fetch
+```
+
+## References
+
+- [Usage reference](references/usage.md)
+- [Distribution guide](references/distribution.md)

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

@@ -0,0 +1,110 @@
+# Distribution Guide
+
+This skill follows Pi / Agent Skills layout:
+
+```text
+confluence-browser-fetch/
+├── SKILL.md
+├── scripts/
+│   └── confluence-browser-fetch.js
+└── references/
+    ├── usage.md
+    └── distribution.md
+```
+
+## Install for Current User
+
+```bash
+mkdir -p ~/.pi/agent/skills
+cp -a confluence-browser-fetch ~/.pi/agent/skills/
+```
+
+Pi discovers it automatically on next start.
+
+Optional command symlink:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf ~/.pi/agent/skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js ~/.local/bin/confluence-browser-fetch
+```
+
+## Install in a Project Repository
+
+```bash
+mkdir -p .pi/skills
+cp -a confluence-browser-fetch .pi/skills/
+git add .pi/skills/confluence-browser-fetch
+git commit -m "Add Confluence browser fetch Pi skill"
+```
+
+## Distribute as a Tarball
+
+From the parent directory:
+
+```bash
+tar -czf confluence-browser-fetch-skill.tar.gz confluence-browser-fetch
+```
+
+Install from tarball:
+
+```bash
+mkdir -p ~/.pi/agent/skills
+tar -xzf confluence-browser-fetch-skill.tar.gz -C ~/.pi/agent/skills
+```
+
+## Distribute as a Git Repository
+
+Consumers can copy the skill:
+
+```bash
+git clone <repo-url>
+cp -a <repo>/confluence-browser-fetch ~/.pi/agent/skills/
+```
+
+or reference a checkout in Pi settings:
+
+```json
+{
+  "skills": ["/path/to/repo/confluence-browser-fetch"]
+}
+```
+
+## npm/package.json Distribution
+
+Pi can discover package skills from `skills/` directories or `pi.skills` entries in `package.json`.
+
+Example package layout:
+
+```text
+my-pi-skills/
+├── package.json
+└── skills/
+    └── confluence-browser-fetch/
+        ├── SKILL.md
+        ├── scripts/confluence-browser-fetch.js
+        └── references/
+```
+
+Minimal package metadata:
+
+```json
+{
+  "name": "my-pi-skills",
+  "version": "1.0.0",
+  "private": true,
+  "pi": {
+    "skills": ["skills/confluence-browser-fetch"]
+  }
+}
+```
+
+## Validation Checklist
+
+- Directory name matches frontmatter name: `confluence-browser-fetch`.
+- `SKILL.md` has `name` and `description`.
+- No cookies, API tokens, or secrets are committed.
+- Script is executable:
+
+```bash
+chmod +x scripts/confluence-browser-fetch.js
+```

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

@@ -0,0 +1,161 @@
+# Confluence Browser Fetch Usage
+
+## Why Browser Fetch?
+
+Confluence Cloud pages are often behind Microsoft/SSO. API-token Basic auth may be disabled or inconvenient. Browser fetch works by:
+
+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.
+
+No cookie or API token needs to be pasted into chat.
+
+## Requirements
+
+- Node.js 22+.
+- Google Chrome or Chromium.
+- Access to the Confluence page with the logged-in account.
+
+Check:
+
+```bash
+node --version
+which google-chrome || which chromium || which chromium-browser
+```
+
+If Chrome has a different path:
+
+```bash
+CHROME=/path/to/chrome scripts/confluence-browser-fetch.js 123456
+```
+
+## Common Commands
+
+Fetch one page by URL:
+
+```bash
+scripts/confluence-browser-fetch.js \
+  'https://example.atlassian.net/wiki/spaces/ABC/pages/123456/Page+Title' \
+  --site https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw
+```
+
+Fetch one page by page ID:
+
+```bash
+scripts/confluence-browser-fetch.js 123456 \
+  --site https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw
+```
+
+Fetch a page and descendants:
+
+```bash
+scripts/confluence-browser-fetch.js 123456 \
+  --site https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw \
+  --descendants
+```
+
+Fetch by exact title in a space:
+
+```bash
+scripts/confluence-browser-fetch.js \
+  --site https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw \
+  --space ABC \
+  --title 'Architecture Overview'
+```
+
+Fetch by CQL:
+
+```bash
+scripts/confluence-browser-fetch.js \
+  --site https://example.atlassian.net \
+  --raw-dir /path/to/wiki/raw \
+  --cql 'space = ABC and type = page and text ~ "invoice"'
+```
+
+Use shorter wait when already logged in:
+
+```bash
+CONFLUENCE_FETCH_WAIT_SEC=15 scripts/confluence-browser-fetch.js 123456 --raw-dir ./raw
+```
+
+Re-fetch everything even when versions match:
+
+```bash
+scripts/confluence-browser-fetch.js 123456 --descendants --force --raw-dir ./raw
+```
+
+Skip attachment downloads above a threshold while still recording references in `attachments.json`:
+
+```bash
+scripts/confluence-browser-fetch.js 123456 --descendants --raw-dir ./raw --max-attachment-size 10mb
+```
+
+Default max attachment download size is `5mb`. Use `--max-attachment-size unlimited` to download all attachments.
+
+By default, pages with matching local `metadata.json` Confluence `version.number` and `version.when` are skipped. This avoids re-downloading unchanged page HTML and attachments during large tree fetches.
+
+## Environment Variables
+
+| Variable | Meaning |
+|---|---|
+| `CONFLUENCE_SITE` | Default Atlassian site, e.g. `https://example.atlassian.net` |
+| `CONFLUENCE_RAW_DIR` | Default output raw directory |
+| `CONFLUENCE_CHROME_DEBUG_PORT` | Chrome DevTools port, default `9224` |
+| `CONFLUENCE_FETCH_WAIT_SEC` | Wait timeout, default `900` |
+| `CONFLUENCE_MAX_SEARCH_RESULTS` | Max CQL pages, default `200` |
+| `CONFLUENCE_MAX_ATTACHMENT_SIZE` / `CONFLUENCE_MAX_ATTACHMENT_BYTES` | Max attachment download size, default `5mb`; skipped files are listed in `attachments.json` |
+| `CONFLUENCE_RETRIES` | Retry count for transient HTTP errors, default `3` |
+| `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 |
+
+## Output Files
+
+For each page:
+
+- `page.json` — REST content with body.storage, body.view, space, ancestors, labels, version, history.
+- `page.storage.html` — Confluence storage XHTML.
+- `page.view.html` — REST-rendered HTML body.
+- `page.browser.html` — full browser HTML shell/page.
+- `attachments.json` — manifest, including skipped large-file references with URL, file size, and reason.
+- `attachments/` — files downloaded via Confluence attachment links under the max-size threshold.
+- `metadata.json` — fetch metadata and source URLs.
+
+## Troubleshooting
+
+### `no Atlassian cookies yet`
+
+Complete SSO in the Chrome window opened by the script.
+
+### `Page failed HTTP 404`
+
+The authenticated user cannot see the page, or the page ID/site is wrong.
+
+### URL cannot be resolved
+
+Provide the numeric page ID from a URL like:
+
+```text
+/wiki/spaces/ABC/pages/123456/Page+Title
+/wiki/pages/viewpage.action?pageId=123456
+```
+
+Tiny links may not expose the page ID; open them in the browser and copy the expanded URL.
+
+### CQL returns too many pages
+
+Use `--max-search-results N` or a narrower query.
+
+### DevTools port already in use
+
+Use another port:
+
+```bash
+scripts/confluence-browser-fetch.js 123456 --port 9334
+```