Ship repo skills through the npm package (#541)

The documented npx skills installer path needs the published package to include the repo-root skills catalog, not only the in-repo templates.

Constraint: Keep the install surface package-owned and avoid copying runtime scripts.

Rejected: Add a new gx skill install command | the existing npx skills add recodee/gitguardex path already owns this flow.

Confidence: high

Scope-risk: narrow

Directive: Keep package.json files explicit so future npm packs continue to include skills/.

Tested: node --test --test-name-pattern 'package manifest ships repo skills|README advertises the repo skills' test/metadata.test.js

Tested: npm pack --dry-run --json confirmed skills/gitguardex/SKILL.md and skills/guardex-merge-skills-to-dev/SKILL.md

Tested: openspec validate agent-codex-codex-task-2026-05-08-12-32 --type change --strict

Tested: openspec validate --specs

Not-tested: Full test/metadata.test.js remains blocked by pre-existing cosign-installer v4.1.2 vs v4.1.1 pin assertion.

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>
Co-authored-by: OmX <omx@oh-my-codex.dev>

Author: 3 people

README.md

@@ -377,7 +377,7 @@ All optional — but if you're running many agents, you probably want them.
 `gx status` auto-detects each one and reports it in the `Global services`
 block.
 
-Install repo skills with `npx skills add recodee/gitguardex`; `npx skills add recodee/` opens the recodee namespace. `gx setup` does not auto-run `npx skills add ...`. If the picker does not show a separate `guardex` skill, that is expected.
+Install repo skills with `npx skills add recodee/gitguardex`; the npm package also ships the root `skills/` catalog so the npx installer can read the GitGuardex skill from the published tarball. `npx skills add recodee/` opens the recodee namespace. `gx setup` does not auto-run `npx skills add ...`. If the picker does not show a separate `guardex` skill, that is expected.
 
 | Tool | What it does | Stars |
 | --- | --- | --- |

openspec/changes/agent-codex-codex-task-2026-05-08-12-32/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-08

openspec/changes/agent-codex-codex-task-2026-05-08-12-32/proposal.md

@@ -0,0 +1,14 @@
+## Why
+
+- Users should be able to install the GitGuardex repo skill through the existing `npx skills add recodee/gitguardex` path without depending on repository-only files that are absent from the published npm tarball.
+
+## What Changes
+
+- Ship the repo-root `skills/` catalog as an explicit npm package asset.
+- Document that the published package includes the skill catalog for the npx skill installer.
+- Add metadata coverage so the package manifest keeps shipping the root skill catalog.
+
+## Impact
+
+- Affects package metadata, README install guidance, and metadata tests only.
+- The tarball gains two small `skills/**/SKILL.md` files; no runtime CLI command behavior changes.

openspec/changes/agent-codex-codex-task-2026-05-08-12-32/specs/agent-codex-codex-task-2026-05-08-12-32/spec.md

@@ -0,0 +1,17 @@
+## ADDED Requirements
+
+### Requirement: Published Skill Catalog
+The npm package manifest SHALL include the repo-root `skills/` catalog so skill installers can access the GitGuardex skill from the published package.
+
+#### Scenario: Package tarball includes repo skills
+- **WHEN** the package is packed for publication
+- **THEN** `skills/gitguardex/SKILL.md` is included
+- **AND** `skills/guardex-merge-skills-to-dev/SKILL.md` is included.
+
+### Requirement: Skill Install Documentation
+The README SHALL document the `npx skills add recodee/gitguardex` repo skill install path and explain that the npm package ships the root `skills/` catalog.
+
+#### Scenario: User finds npx skill install path
+- **WHEN** a user reads the companion tools section
+- **THEN** the `npx skills add recodee/gitguardex` install command is visible
+- **AND** the package-backed skill catalog behavior is described.

openspec/changes/agent-codex-codex-task-2026-05-08-12-32/tasks.md

@@ -0,0 +1,34 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-codex-codex-task-2026-05-08-12-32`; branch=`agent/codex/codex-task-2026-05-08-12-32`; scope=`TODO`; action=`continue this sandbox or finish cleanup after a usage-limit/manual takeover`.
+- Copy prompt: Continue `agent-codex-codex-task-2026-05-08-12-32` on branch `agent/codex/codex-task-2026-05-08-12-32`. Work inside the existing sandbox, review `openspec/changes/agent-codex-codex-task-2026-05-08-12-32/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/codex/codex-task-2026-05-08-12-32 --base main --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-codex-task-2026-05-08-12-32`.
+- [x] 1.2 Define normative requirements in `specs/agent-codex-codex-task-2026-05-08-12-32/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Implement scoped behavior changes.
+- [x] 2.2 Add/update focused regression coverage.
+
+## 3. Verification
+
+- [x] 3.1 Run targeted project verification commands.
+- [x] 3.2 Run `openspec validate agent-codex-codex-task-2026-05-08-12-32 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/codex-task-2026-05-08-12-32 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).

package.json

@@ -39,6 +39,7 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "templates",
     "README.md",
     "LICENSE",

test/metadata.test.js

@@ -268,6 +268,12 @@ test('package manifest ships the extracted src runtime', () => {
   assert.match(pkg.files.join('\n'), /^src$/m);
 });
 
+test('package manifest ships repo skills for npx skills installer', () => {
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  assert.ok(Array.isArray(pkg.files), 'package.json files must stay explicit');
+  assert.match(pkg.files.join('\n'), /^skills$/m);
+});
+
 test('doctor CLI parser stays in src/cli args while the main doctor command stays routable and dead legacy audit stubs stay removed', () => {
   const argsSource = fs.readFileSync(path.join(repoRoot, 'src', 'cli', 'args.js'), 'utf8');
   const cliSource = fs.readFileSync(path.join(repoRoot, 'src', 'cli', 'main.js'), 'utf8');