@aholbreich/agent-skills 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 - 2026-05-06
+
+Initial public package structure.
+
+Added:
+
+- `jira-browser-fetch` skill for browser-authenticated Jira issue/JQL/linked-ticket fetches.
+- `confluence-browser-fetch` skill for browser-authenticated Confluence page/CQL/descendant fetches.
+- Default 5 MiB attachment download cap with skipped-file references in `attachments.json`.
+- Confluence skip-unchanged behavior based on page version metadata.
+- Retry and timeout options for Confluence fetches.
+- Pi package metadata, README, security policy, and CI syntax checks.
+- Node built-in unit tests for helper logic and CLI smoke/error paths.
+- `agent-skills` installer CLI for `npx @aholbreich/agent-skills` one-shot installs.
+- Default npx target is the generic Agent Skills location `~/.agents/skills`.

package/COMPATIBILITY.md

@@ -0,0 +1,134 @@
+# Compatibility
+
+This package is designed as a pure [Agent Skills](https://agentskills.io/) package.
+
+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 |
+
+## Install commands
+
+### Generic Agent Skills default
+
+```bash
+npx @aholbreich/agent-skills
+```
+
+This installs to `~/.agents/skills` and is equivalent to:
+
+```bash
+npx @aholbreich/agent-skills --target agents
+```
+
+### Pi global
+
+```bash
+pi install npm:@aholbreich/agent-skills
+```
+
+or:
+
+```bash
+npx @aholbreich/agent-skills --target pi
+```
+
+### Pi project-local
+
+```bash
+pi install -l npm:@aholbreich/agent-skills
+```
+
+or:
+
+```bash
+npx @aholbreich/agent-skills --target project
+```
+
+### Claude Code
+
+```bash
+npx @aholbreich/agent-skills --target claude
+```
+
+Project-local Claude-style install:
+
+```bash
+npx @aholbreich/agent-skills --target project-claude
+```
+
+### Codex
+
+```bash
+npx @aholbreich/agent-skills --target codex
+```
+
+Project-local Codex-style install:
+
+```bash
+npx @aholbreich/agent-skills --target project-codex
+```
+
+### Generic `.agents/skills`
+
+```bash
+npx @aholbreich/agent-skills --target agents
+```
+
+Project-local generic install:
+
+```bash
+npx @aholbreich/agent-skills --target project-agents
+```
+
+### Custom skills directory
+
+```bash
+npx @aholbreich/agent-skills install --dir /path/to/skills
+```
+
+## Discoverability
+
+The package is tagged for discovery with npm keywords including:
+
+- `pi-package`
+- `agent-skills`
+- `agent-skill`
+- `agentskills`
+- `skills.sh`
+- `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.
+
+If a registry requires manual submission, use:
+
+```text
+Package: @aholbreich/agent-skills
+Repository: https://github.com/aholbreich/agent-skills
+Skills directory: skills/
+```
+
+## Compliance checks in this repo
+
+CI runs:
+
+```bash
+pnpm run ci
+```
+
+That includes:
+
+- JavaScript syntax checks.
+- Unit tests.
+- Skill frontmatter compliance checks.
+- `pnpm 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/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Thanks for improving this skill collection.
+
+## Development setup
+
+Requirements:
+
+- Node.js 22+
+- Chrome/Chromium for manual end-to-end testing
+- Pi if you want to test skill discovery
+
+Run checks and tests:
+
+```bash
+pnpm run check
+pnpm test
+pnpm run ci
+```
+
+## Skill guidelines
+
+- Keep skills self-contained under `skills/<skill-name>/`.
+- `SKILL.md` frontmatter `name` must match the directory name.
+- Prefer no runtime dependencies. If dependencies are needed, add them to `package.json`.
+- Do not commit fetched `raw/` data, browser profiles, cookies, tokens, customer data, or logs.
+- Keep scripts read-only unless the skill is explicitly meant to modify external systems.
+- Document safety assumptions in the skill and in `SECURITY.md` if relevant.
+
+## Testing browser fetchers
+
+Use a test Atlassian site or non-confidential page/issue when possible.
+
+```bash
+./skills/jira-browser-fetch/scripts/jira-browser-fetch.js PROJ-123 \
+  --server https://example.atlassian.net \
+  --raw-dir ./raw-test
+
+./skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js 123456 \
+  --site https://example.atlassian.net \
+  --raw-dir ./raw-test
+```
+
+Then delete local test exports before committing.
+
+## Release checklist
+
+1. `pnpm run ci`
+2. update `CHANGELOG.md`
+3. bump `package.json` version
+4. commit changes
+5. tag release, e.g. `v0.1.0`
+6. push tag

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Holbreich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+# Agent Skills
+
+Handcrafted [Agent Skills](https://agentskills.io/) for developer and LLM-wiki workflows. The package is intentionally a pure skills package with broad compatibility across Pi, Claude Code, Codex, OpenClaw/generic `.agents` setups, and other Agent Skills-compatible harnesses.
+
+This repository is a pure skills package. It currently contains browser-authenticated Atlassian fetchers that work well when Jira/Confluence API-token authentication is unavailable because an organization uses Microsoft/SSO.
+
+## Skills
+
+| Skill | Purpose |
+|---|---|
+| [`jira-browser-fetch`](skills/jira-browser-fetch/) | Fetch Jira issue JSON, rendered HTML/XML, linked/referenced issues, JQL result sets, and attachments through an authenticated Chrome session. |
+| [`confluence-browser-fetch`](skills/confluence-browser-fetch/) | Fetch Confluence page JSON, storage/view HTML, browser HTML, descendants, CQL result sets, and attachments through an authenticated Chrome session. |
+
+## Compatibility
+
+This repository follows the Agent Skills directory convention: each skill lives under `skills/<skill-name>/SKILL.md` with matching frontmatter.
+
+Supported install targets:
+
+| Target | 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` |
+
+See [`COMPATIBILITY.md`](COMPATIBILITY.md) for details.
+
+## Requirements
+
+- Node.js `>=22`.
+- Google Chrome or Chromium.
+- 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
+
+From GitHub:
+
+```bash
+pi install git:github.com/aholbreich/agent-skills
+```
+
+Project-local install, useful for teams:
+
+```bash
+pi install -l git:github.com/aholbreich/agent-skills
+```
+
+Try without installing:
+
+```bash
+pi -e git:github.com/aholbreich/agent-skills
+```
+
+## One-shot install with npx
+
+Install bundled skills into the generic Agent Skills directory `~/.agents/skills`:
+
+```bash
+npx @aholbreich/agent-skills
+```
+
+This is equivalent to:
+
+```bash
+npx @aholbreich/agent-skills --target agents
+```
+
+Install into a project-local `.pi/skills` directory:
+
+```bash
+npx @aholbreich/agent-skills install --target project
+```
+
+Install for Claude Code, Codex, or generic Agent Skills harnesses:
+
+```bash
+npx @aholbreich/agent-skills install --target claude
+npx @aholbreich/agent-skills install --target codex
+npx @aholbreich/agent-skills install --target agents
+```
+
+Overwrite existing installed skill directories:
+
+```bash
+npx @aholbreich/agent-skills install --target agents --force
+```
+
+List bundled skills:
+
+```bash
+npx @aholbreich/agent-skills list
+```
+
+## Manual install
+
+```bash
+git clone https://github.com/aholbreich/agent-skills.git
+mkdir -p ~/.pi/agent/skills
+cp -a agent-skills/skills/* ~/.pi/agent/skills/
+```
+
+Optional command symlinks:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf ~/.pi/agent/skills/jira-browser-fetch/scripts/jira-browser-fetch.js ~/.local/bin/jira-browser-fetch
+ln -sf ~/.pi/agent/skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js ~/.local/bin/confluence-browser-fetch
+```
+
+## npm-style command use from checkout
+
+From this repository:
+
+```bash
+pnpm run check
+./skills/jira-browser-fetch/scripts/jira-browser-fetch.js --help
+./skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js --help
+```
+
+If installed globally via npm, the package exposes:
+
+```bash
+agent-skills
+jira-browser-fetch
+confluence-browser-fetch
+```
+
+## Jira examples
+
+Fetch one issue:
+
+```bash
+jira-browser-fetch PROJ-123 \
+  --server https://example.atlassian.net \
+  --raw-dir ./raw
+```
+
+Fetch linked/referenced tickets too:
+
+```bash
+jira-browser-fetch PROJ-123 \
+  --server https://example.atlassian.net \
+  --raw-dir ./raw \
+  --connected \
+  --scan-text \
+  --depth 1
+```
+
+Fetch all issues assigned to the current Jira user:
+
+```bash
+jira-browser-fetch \
+  --server https://example.atlassian.net \
+  --raw-dir ./raw \
+  --assignee-me
+```
+
+Fetch a JQL result set:
+
+```bash
+jira-browser-fetch \
+  --server https://example.atlassian.net \
+  --raw-dir ./raw \
+  --jql 'assignee = currentUser() ORDER BY updated DESC'
+```
+
+## Confluence examples
+
+Fetch one page by URL:
+
+```bash
+confluence-browser-fetch \
+  '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
+confluence-browser-fetch 123456 \
+  --site https://example.atlassian.net \
+  --raw-dir ./raw \
+  --descendants
+```
+
+Fetch by CQL:
+
+```bash
+confluence-browser-fetch \
+  --site https://example.atlassian.net \
+  --raw-dir ./raw \
+  --cql 'space = ABC and type = page and text ~ "billing"'
+```
+
+## Attachment size limits
+
+Both fetchers default to skipping attachment downloads larger than `5mb`. Skipped files are still referenced in `attachments.json` with filename, URL, size, and reason.
+
+```bash
+jira-browser-fetch PROJ-123 --server https://example.atlassian.net --max-attachment-size 1mb
+confluence-browser-fetch 123456 --site https://example.atlassian.net --max-attachment-size 10mb
+```
+
+Disable the limit:
+
+```bash
+--max-attachment-size unlimited
+```
+
+## Output and LLM wiki use
+
+The tools are designed to populate a wiki `raw/` folder. They do not synthesize pages themselves. A typical LLM wiki workflow is:
+
+1. fetch Jira/Confluence sources into `raw/`,
+2. treat `raw/` as immutable evidence,
+3. synthesize durable notes into `wiki/`,
+4. cite raw paths from wiki pages.
+
+## Security
+
+Read [`SECURITY.md`](SECURITY.md). Do not commit fetched `raw/` exports or browser profiles.
+
+## Development
+
+Run syntax checks and tests:
+
+```bash
+pnpm run check
+pnpm test
+pnpm run ci
+```
+
+Tests use Node's built-in test runner and cover pure helper logic plus CLI smoke/error paths. Package validation is intentionally lightweight because the scripts have no runtime npm dependencies.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

package/SECURITY.md

@@ -0,0 +1,42 @@
+# Security Policy
+
+## Read this before installing or running
+
+These skills are local automation tools. They can fetch potentially sensitive Jira and Confluence data into your filesystem.
+
+## Browser authentication model
+
+The Jira and Confluence fetchers:
+
+1. launch or reuse Chrome/Chromium 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.
+
+They do **not** require you to paste API tokens or cookies into chat.
+
+## Important precautions
+
+- Do not paste Atlassian cookies, API tokens, passwords, or session headers into prompts, issues, logs, or commits.
+- Treat everything under `raw/` as confidential unless you know it is public.
+- Do not commit fetched Jira/Confluence exports or attachments to a public repository.
+- Review generated `attachments.json` manifests before sharing; they may contain private URLs and filenames.
+- Chrome remote debugging is configured for `127.0.0.1`; do not expose it to a network interface.
+- Use dedicated browser profiles for fetch automation.
+- The default attachment download cap is `5mb`; skipped large attachments are still referenced in `attachments.json`.
+
+## Attachment size limits
+
+Both fetchers support:
+
+```bash
+--max-attachment-size 5mb
+--max-attachment-size 500kb
+--max-attachment-size unlimited
+```
+
+Large skipped files remain documented in `attachments.json` with filename, URL, size, and skip reason.
+
+## Reporting security issues
+
+If you find a vulnerability, please open a private security advisory on GitHub if available, or contact the repository owner directly. Do not publish exploit details before there is a fix or mitigation.

package/bin/agent-skills.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const fsp = require('fs/promises');
+const os = require('os');
+const path = require('path');
+
+const packageRoot = path.resolve(__dirname, '..');
+const sourceSkillsDir = path.join(packageRoot, 'skills');
+
+const TARGETS = {
+  pi: path.join(os.homedir(), '.pi/agent/skills'),
+  agents: path.join(os.homedir(), '.agents/skills'),
+  claude: path.join(os.homedir(), '.claude/skills'),
+  codex: path.join(os.homedir(), '.codex/skills'),
+  openclaw: path.join(os.homedir(), '.agents/skills'),
+  project: path.join(process.cwd(), '.pi/skills'),
+  'project-pi': path.join(process.cwd(), '.pi/skills'),
+  'project-agents': path.join(process.cwd(), '.agents/skills'),
+  'project-claude': path.join(process.cwd(), '.claude/skills'),
+  'project-codex': path.join(process.cwd(), '.codex/skills'),
+};
+
+function usage() {
+  console.log(`Usage: agent-skills [command] [options]
+
+Install this package's Agent Skills into a local skills directory.
+
+Commands:
+  install                 Install skills (default command)
+  list                    List bundled skills
+  paths                   Show target install paths
+  help                    Show this help
+
+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
+  --force                 Overwrite existing skill directories
+  --dry-run               Show what would be copied without writing
+
+Examples:
+  npx @aholbreich/agent-skills
+  npx @aholbreich/agent-skills install --target agents --force
+  npx @aholbreich/agent-skills install --target pi --force
+  npx @aholbreich/agent-skills install --target project
+  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 --dir ~/.pi/agent/skills
+  npx @aholbreich/agent-skills list
+
+Pi-native install is also supported:
+  pi install npm:@aholbreich/agent-skills
+`);
+}
+
+async function listSkills() {
+  const entries = await fsp.readdir(sourceSkillsDir, { withFileTypes: true });
+  return entries
+    .filter(e => e.isDirectory() && fs.existsSync(path.join(sourceSkillsDir, e.name, 'SKILL.md')))
+    .map(e => e.name)
+    .sort();
+}
+
+function expandHome(p) {
+  if (!p) return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+async function copyDir(src, dest) {
+  await fsp.cp(src, dest, { recursive: true, force: true, errorOnExist: false });
+}
+
+async function install(args) {
+  let target = 'agents';
+  let customDir = '';
+  let force = false;
+  let dryRun = false;
+
+  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 === '--force') force = true;
+    else if (a === '--dry-run') dryRun = true;
+    else if (a === '-h' || a === '--help') { usage(); return; }
+    else throw new Error(`Unknown install option: ${a}`);
+  }
+
+  if (!customDir && !TARGETS[target]) {
+    throw new Error(`Unknown target '${target}'. Valid targets: ${Object.keys(TARGETS).join(', ')}`);
+  }
+
+  const destRoot = path.resolve(expandHome(customDir || TARGETS[target]));
+  const skills = await listSkills();
+
+  console.log(`Installing ${skills.length} skill(s) to ${destRoot}`);
+  if (dryRun) console.log('Dry run: no files will be written.');
+
+  if (!dryRun) await fsp.mkdir(destRoot, { recursive: true });
+
+  let installed = 0;
+  let skipped = 0;
+  for (const skill of skills) {
+    const src = path.join(sourceSkillsDir, skill);
+    const dest = path.join(destRoot, skill);
+    const exists = fs.existsSync(dest);
+    if (exists && !force) {
+      console.log(`SKIP ${skill} (already exists; use --force to overwrite)`);
+      skipped++;
+      continue;
+    }
+    console.log(`${exists ? 'OVERWRITE' : 'INSTALL'} ${skill}`);
+    if (!dryRun) {
+      if (exists) await fsp.rm(dest, { recursive: true, force: true });
+      await copyDir(src, dest);
+    }
+    installed++;
+  }
+
+  console.log(`Done. Installed: ${installed}. Skipped: ${skipped}.`);
+  if (target.startsWith('project') && !customDir) {
+    console.log('Project-local skills are available when running an Agent Skills-compatible tool inside this project.');
+  } else if (target === 'pi' && !customDir) {
+    console.log('Restart Pi or start a new session to discover newly installed skills.');
+  }
+}
+
+async function showPaths() {
+  for (const [name, p] of Object.entries(TARGETS)) console.log(`${name.padEnd(8)} ${p}`);
+}
+
+async function main() {
+  const [cmdRaw, ...rest] = process.argv.slice(2);
+  const cmd = cmdRaw || 'install';
+
+  if (cmd === 'help' || cmd === '-h' || cmd === '--help') return usage();
+  if (cmd === 'install') return install(rest);
+  if (cmd === 'list') {
+    for (const skill of await listSkills()) console.log(skill);
+    return;
+  }
+  if (cmd === 'paths') return showPaths();
+
+  // Support `npx @aholbreich/agent-skills --target project` as shorthand for install.
+  if (cmd.startsWith('-')) return install([cmd, ...rest]);
+
+  throw new Error(`Unknown command: ${cmd}`);
+}
+
+main().catch(err => {
+  console.error(`ERROR: ${err.message}`);
+  process.exit(1);
+});