@aholbreich/agent-skills 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,8 @@ Added:
 - `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.
 
 ## 0.1.0 - 2026-05-06
 

package/COMPATIBILITY.md

@@ -4,96 +4,111 @@ 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:
+This fallback copies files. For symlinked, multi-agent installs, prefer `npx skills add aholbreich/agent-skills`.
 
-```bash
-npx @aholbreich/agent-skills --target project-codex
-```
+## Collision behavior
 
-### Generic `.agents/skills`
+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 agents
-```
+Common precedence pattern:
 
-Project-local generic install:
+1. Project-local skills override user/global skills.
+2. User/global skills override bundled/system skills.
+3. Duplicate names are not merged.
 
-```bash
-npx @aholbreich/agent-skills --target project-agents
+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 +121,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 +133,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 +149,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,18 +15,16 @@ 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
 
@@ -37,52 +35,74 @@ See [`COMPATIBILITY.md`](COMPATIBILITY.md) for details.
 
 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
 ```
 
-Try without installing:
+List available skills without installing:
 
 ```bash
-pi -e git:github.com/aholbreich/agent-skills
+npx skills add aholbreich/agent-skills --list
 ```
 
-## One-shot install with npx
+Non-interactive examples:
 
-Install bundled skills into the generic Agent Skills directory `~/.agents/skills`:
+```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
-npx @aholbreich/agent-skills
+pi install npm:@aholbreich/agent-skills
 ```
 
-This is equivalent to:
+Project-local Pi package install, useful for teams that already standardize on Pi packages:
 
 ```bash
-npx @aholbreich/agent-skills --target agents
+pi install -l npm:@aholbreich/agent-skills
 ```
 
-Install into a project-local `.pi/skills` directory:
+Try without installing:
 
 ```bash
-npx @aholbreich/agent-skills install --target project
+pi -e npm:@aholbreich/agent-skills
 ```
 
-Install for Claude Code, Codex, or generic Agent Skills harnesses:
+## 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`:
 
 ```bash
+npx @aholbreich/agent-skills
+```
+
+Install for a specific target:
+
+```bash
+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 agents
+npx @aholbreich/agent-skills install --target project
 ```
 
 Overwrite existing installed skill directories:
@@ -97,6 +117,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/bin/agent-skills.js

@@ -27,6 +27,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
@@ -40,6 +45,7 @@ Options for install:
   --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 --target agents --force
   npx @aholbreich/agent-skills install --target pi --force

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aholbreich/agent-skills",
-  "version": "0.3.0",
+  "version": "0.4.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": [