jhste-skills 0.3.7 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.4.0 - 2026-07-01
+
+### Added
+- Added `skills/_shared/` shared companion resources (`solid-lens`, `evidence-discipline`, `issue-candidate`, `scope-discipline`) as the single source for cross-cutting doctrine, cited by the jhste skills instead of restating it per skill.
+- Added a first-class shared-resource install concept: directories under `skills/` starting with `_` are not skills (excluded from listing, selection, and missing-skill checks) but are copied alongside skills so installed `../_shared/...` references never dangle.
+- Added `jhste-skills global` — advisory-only, user-level setup for Codex, Claude Code, and OpenCode that installs skills to `~/.jhste/skills` and writes marker-managed bridges into `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, and `~/.config/opencode/AGENTS.md`, with no git hooks or per-repo files; `--uninstall` reverses it.
+- Added `ask-jhste`, a user-invoked router for choosing the right jhste skill/workflow without adding always-on model context.
+- Added OpenCode support to global setup via `~/.config/opencode/AGENTS.md`.
+- Added a safe global-only npm postinstall refresh: after a user has opted into `jhste-skills global`, later `npm update -g jhste-skills` refreshes managed global skill copies and existing managed global bridges without creating a new setup.
+
+### Changed
+- Trimmed jhste skill descriptions and SKILL bodies for lower operating-context cost while preserving behavior; SKILL files now own the decision procedure and cite `_shared` doctrine, and reference files are examples/lookup only.
+- Reduced `docs-check` to load-bearing behavior anchors (pinned once at their source) instead of exact prose/section titles; de-duplicated the triplicated issue-candidate pin to the shared doctrine.
+- Deduplicated the `## Workflow` section in `AGENTS.md` against the managed bridge block.
+- Extracted shared `removeManagedSkills`/manifest loading into `install-actions/skills.mjs` for reuse by `uninstall` and `global`.
+- Made `grill-me` a user-invoked alias for `grilling` to reduce duplicate invocation surface while preserving the personal pressure-test entrypoint.
+- Made `global` skip bridge writes when skill installation is blocked, and preflight `_shared` unmanaged conflicts before copying selected skills.
+- Synced README translations (ko/zh/ja) with global setup, `ask-jhste`, and `_shared` companion-resource docs.
+- Hardened `global` option validation, refused vendor-only global installs, reported invalid-manifest uninstall failures, and rejected unsafe manifest entry names before managed skill removal.
+
+### Validation
+- `npm test` passed (12 stages, including new `_shared` install integrity and `global` command smoke coverage).
+
 ## 0.3.7 - 2026-06-30
 
 ### Added

package/README.ja.md

@@ -81,6 +81,19 @@ jhste-skills install
 
 一度だけ試すなら `npx`、普段使う CLI として置いておきたいなら `npm install -g` を使ってください。
 
+### Global setup（Codex + Claude Code + OpenCode、advisory-only）
+
+リポジトリごとのファイルや git hooks を作らず、すべてのリポジトリで skills を使いたい場合は、ユーザーレベルで一度だけ設定します。
+
+```bash
+npm install -g jhste-skills
+jhste-skills global
+```
+
+このコマンドは skills と shared companion resources を `~/.jhste/skills` にコピーし、各 agent の global instruction file（`~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md`、`~/.config/opencode/AGENTS.md`）に marker-managed bridge block を書き込みます。ファイルがなければ作成します。git hooks やリポジトリごとのファイルは書き込まず、guard は advisory のままです（`jhste-skills guard --scope changed`）。対象 agent は `--agents codex,claude,opencode` で選択でき、`jhste-skills global --uninstall` で削除できます。
+
+この一度の global setup 後は、以降の `npm update -g jhste-skills` で managed skill copies と既存の managed global bridge blocks が安全に更新されます。agent やオプションを変更したい場合だけ `jhste-skills global` を再実行してください。
+
 デフォルトインストールは Normal mode を使います。
 
 - bundled skills 全体をインストールします: jhste core skills + vendored workflow skills。
@@ -162,6 +175,7 @@ Custom   - 効果ベースの質問でセットアップ範囲を選択
 | Skill | いつ使うか | 何を減らすか |
 |---|---|---|
 | [`setup`](skills/setup/SKILL.md)<br>install/connect/update が既存プロジェクト指示を上書きしないようにする安全セットアップ skill | kit をインストール、またはリポジトリに接続するとき | Unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
+| [`ask-jhste`](skills/ask-jhste/SKILL.md)<br>適切な jhste skill や workflow を選ぶ user-invoked router | 次にどの jhste skill/workflow を使うべきか迷うとき | Wrong workflow selection, unnecessary always-on context, accidental side effects from routing |
 | [`jhste-engineering-groundwork`](skills/jhste-engineering-groundwork/SKILL.md)<br>コード変更前に goal、premise、scope、boundary、failure path を検証する pre-change groundwork skill | non-trivial code change の前 | Blind agreement, scope creep, unverified assumption, unclear boundary |
 | [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>input validation、observable failure handling、secret-safe logging、oversized-file review の skill | external input、failure handling、logging、env/config、code-quality review path を触るとき | Unvalidated input, silent failure, secret logging, oversized file |
 | [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>module boundary、side-effect placement、SOLID-informed design risk を確認する architecture review skill | module boundary、app structure、side-effect placement、responsibility split を変更するとき | Pass-through abstraction, mixed responsibility, side-effect leakage |
@@ -270,3 +284,5 @@ Release acceptance notes は [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.
 - non-trivial work を完了と呼ぶ前に red-team code review を行う。
 
 高速な agent には guardrail が必要です。`jhste-skills` は agent に repo-respecting engineering workflow を提供します。
+
+Skills は `skills/_shared/` の cross-cutting doctrine（SOLID lens、evidence discipline、issue-candidate protocol、scope discipline）を共有します。`skills/` 配下で名前が `_` から始まるディレクトリは skill ではなく shared companion resource です。skill listing、selection、missing-skill checks からは除外されますが、どの skill をインストールしても一緒にコピーされるため、インストール済み artifact 内の cross-skill `../_shared/...` references が dangling になりません。

package/README.ko.md

@@ -82,6 +82,19 @@ jhste-skills install
 
 한 번만 실행해보고 싶다면 `npx`를 쓰면 되고, 평소에 계속 사용할 CLI로 두고 싶다면 `npm install -g`를 쓰면 됩니다.
 
+### Global setup (Codex + Claude Code + OpenCode, advisory-only)
+
+레포별 파일이나 git hook 없이 모든 레포에서 skills를 쓰고 싶다면, 사용자 수준에서 한 번 설정하세요.
+
+```bash
+npm install -g jhste-skills
+jhste-skills global
+```
+
+이 명령은 skills와 shared companion resources를 `~/.jhste/skills`에 복사하고, 각 agent의 global instruction file(`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.config/opencode/AGENTS.md`)에 marker-managed bridge block을 씁니다. 파일이 없으면 생성합니다. Git hook이나 레포별 파일은 쓰지 않으며, guard는 advisory 상태로 남습니다(`jhste-skills guard --scope changed`). Agent는 `--agents codex,claude,opencode`로 선택하고, `jhste-skills global --uninstall`로 제거할 수 있습니다.
+
+이 최초 global setup 이후에는 `npm update -g jhste-skills`만으로 managed skill copy와 기존 managed global bridge block이 안전하게 새로고침됩니다. Agent나 옵션을 바꾸고 싶을 때만 `jhste-skills global`을 다시 실행하세요.
+
 기본 설치는 Normal mode를 사용합니다.
 
 - bundled skills 전체를 설치합니다: jhste core skills + vendored workflow skills.
@@ -165,6 +178,7 @@ Custom   - 효과 중심 질문을 통해 설치 범위를 직접 선택
 | Skill | 언제 쓰나 | 무엇을 줄여주나 |
 |---|---|---|
 | [`setup`](skills/setup/SKILL.md)<br>설치, 연결, 업데이트가 기존 프로젝트 지침을 덮어쓰지 않도록 하는 안전 설치 스킬 | kit를 설치하거나 레포에 연결할 때 | unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
+| [`ask-jhste`](skills/ask-jhste/SKILL.md)<br>적절한 jhste skill이나 workflow를 고르는 user-invoked router | 다음에 어떤 jhste skill/workflow를 써야 할지 확실하지 않을 때 | wrong workflow selection, unnecessary always-on context, accidental side effects from routing |
 | [`jhste-engineering-groundwork`](skills/jhste-engineering-groundwork/SKILL.md)<br>코드 변경 전 목표, 전제, scope, boundary, failure path, final behavior predicate를 검증하는 pre-change groundwork 스킬 | non-trivial code change 전 | blind agreement, scope creep, unverified assumption, unclear boundary |
 | [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>입력 검증, 관측 가능한 실패 처리, secret-safe logging, oversized-file review 스킬 | external input, failure handling, logging, env/config, cleanup/search-replace, code-quality review path를 만질 때 | unvalidated input, silent failure, secret logging, unsafe broad cleanup, oversized file |
 | [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>모듈 경계, side effect 위치, SOLID-informed design risk를 검토하는 아키텍처 리뷰 스킬 | module boundary, app structure, side-effect placement, responsibility split 변경 시 | pass-through abstraction, mixed responsibility, side-effect leakage |
@@ -273,3 +287,5 @@ Release acceptance notes는 [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.m
 - non-trivial work를 완료라고 말하기 전에 red-team code review를 수행합니다.
 
 빠른 agent에는 guardrail이 필요합니다. `jhste-skills`는 agent에게 repo-respecting engineering workflow를 제공합니다.
+
+Skills는 `skills/_shared/`의 cross-cutting doctrine(SOLID lens, evidence discipline, issue-candidate protocol, scope discipline)을 공유합니다. `skills/` 아래에서 이름이 `_`로 시작하는 디렉터리는 skill이 아니라 shared companion resource입니다. skill listing, selection, missing-skill check에서는 제외되지만, 어떤 skill을 설치하든 함께 복사되어 설치된 artifact 안에서 cross-skill `../_shared/...` reference가 끊어지지 않습니다.

package/README.md

@@ -82,7 +82,20 @@ jhste-skills install
 
 Use `npx` when you want a one-off run without a global install. Use `npm install -g` when you want `jhste-skills` available as a normal shell command.
 
-The default install uses Normal mode.
+### Global setup (Codex + Claude Code + OpenCode, advisory-only)
+
+If you want the skills available in every repository without per-repo files or git hooks, set up once at the user level:
+
+```bash
+npm install -g jhste-skills
+jhste-skills global
+```
+
+This copies the skills (and shared companion resources) to `~/.jhste/skills` and writes a marker-managed bridge block into each agent's global instruction file (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.config/opencode/AGENTS.md`), creating them if needed. No git hooks and no per-repo files are written; guard stays advisory (`jhste-skills guard --scope changed`). Choose agents with `--agents codex,claude,opencode`, and remove everything with `jhste-skills global --uninstall`.
+
+After this one-time global setup, later `npm update -g jhste-skills` runs a safe global-only refresh of the managed skill copies and existing managed global bridge blocks. Re-run `jhste-skills global` when you want to change agents or options.
+
+The default (per-repo) install uses Normal mode.
 
 - Installs all bundled skills: jhste core skills + vendored workflow skills.
 - Creates `.jhste/profile.yaml` when missing; `--force` refreshes generated/managed profiles, while modified profiles require `--force --allow-profile-overwrite`.
@@ -165,6 +178,7 @@ These are the jhste-authored guardrail skills. They are installed by default as
 | Skill | Use it when | What it helps reduce |
 |---|---|---|
 | [`setup`](skills/setup/SKILL.md)<br>A safe setup skill that prevents install/connect/update flows from overwriting existing project instructions | Installing or connecting the kit to a repository | Unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
+| [`ask-jhste`](skills/ask-jhste/SKILL.md)<br>A user-invoked router for choosing the right jhste skill or workflow | You are not sure which jhste skill or workflow to use next | Wrong workflow selection, unnecessary always-on context, accidental side effects from routing |
 | [`jhste-engineering-groundwork`](skills/jhste-engineering-groundwork/SKILL.md)<br>A pre-change groundwork skill that verifies goal, premise, scope, boundary, failure path, and final behavior predicates before code edits | Before non-trivial code changes | Blind agreement, scope creep, unverified assumptions, unclear boundaries |
 | [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>A code-quality skill for input validation, observable failure handling, secret-safe logging, and oversized-file review | Touching external input, failure handling, logging, env/config, cleanup/search-replace, or code-quality review paths | Unvalidated input, silent failure, secret logging, unsafe broad cleanup, oversized files |
 | [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>An architecture review skill for module boundaries, side-effect placement, and SOLID-informed design risks | Changing module boundaries, app structure, side-effect placement, or responsibility splits | Pass-through abstraction, mixed responsibility, side-effect leakage |
@@ -274,4 +288,6 @@ See [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.md) for release acceptanc
 
 Fast agents need guardrails. `jhste-skills` gives them a repo-respecting engineering workflow.
 
+Skills share cross-cutting doctrine (SOLID lens, evidence discipline, issue-candidate protocol, scope discipline) from `skills/_shared/`. Directories under `skills/` whose name starts with `_` are shared companion resources, not skills: they are excluded from skill listing, selection, and missing-skill checks, but are copied alongside the skills whenever any skill is installed so cross-skill `../_shared/...` references never dangle in the installed artifact.
+
 Installed skill directories are tracked with `.jhste-skills-manifest.json`. `--force` refreshes manifest-managed skill copies and generated/managed profiles; modified profiles need `--force --allow-profile-overwrite`; overwriting unmanaged differing skill directories still requires the separate `--allow-unmanaged-skill-overwrite` flag after review. `sync` and `update` can also adopt additional known jhste skills into an already managed skills directory so older mixed installs can be reconciled without a manual overwrite flag. Legacy managed renames are also reconciled during `sync` and `update`, so older managed installs that still have `diagnose` or `jhste-engineering-judgment` are migrated to `diagnosing-bugs` or `jhste-engineering-groundwork`. Managed copies of retired `write-a-skill` are removed rather than kept as a compatibility fallback.

package/README.zh.md

@@ -81,6 +81,19 @@ jhste-skills install
 
 如果只想临时运行一次，请使用 `npx`。如果希望把 `jhste-skills` 作为常用 shell 命令，请使用 `npm install -g`。
 
+### Global setup（Codex + Claude Code + OpenCode，advisory-only）
+
+如果你希望在所有仓库中使用 skills，但不写入每个仓库的文件或 git hooks，可以在用户级别设置一次：
+
+```bash
+npm install -g jhste-skills
+jhste-skills global
+```
+
+该命令会把 skills 和 shared companion resources 复制到 `~/.jhste/skills`，并在每个 agent 的 global instruction file（`~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md`、`~/.config/opencode/AGENTS.md`）中写入 marker-managed bridge block；文件不存在时会创建。它不会写入 git hooks 或每仓库文件；guard 保持 advisory（`jhste-skills guard --scope changed`）。可用 `--agents codex,claude,opencode` 选择 agent，用 `jhste-skills global --uninstall` 移除。
+
+完成这一次 global setup 后，之后运行 `npm update -g jhste-skills` 会安全刷新 managed skill copies 和已有 managed global bridge blocks。只有在需要更改 agent 或选项时才重新运行 `jhste-skills global`。
+
 默认安装使用 Normal mode。
 
 - 安装全部 bundled skills：jhste core skills + vendored workflow skills。
@@ -162,6 +175,7 @@ Custom   - 通过面向效果的问题自定义安装范围
 | Skill | 何时使用 | 帮助减少什么 |
 |---|---|---|
 | [`setup`](skills/setup/SKILL.md)<br>安全安装 skill，避免 install/connect/update 覆盖现有项目说明 | 安装 kit 或连接仓库时 | Unsafe overwrite, unmanaged hook conflict, repo instruction replacement |
+| [`ask-jhste`](skills/ask-jhste/SKILL.md)<br>用于选择正确 jhste skill 或 workflow 的 user-invoked router | 不确定下一步该用哪个 jhste skill/workflow 时 | Wrong workflow selection, unnecessary always-on context, accidental side effects from routing |
 | [`jhste-engineering-groundwork`](skills/jhste-engineering-groundwork/SKILL.md)<br>pre-change groundwork skill，在改代码前验证目标、前提、scope、boundary 和 failure path | non-trivial code change 前 | Blind agreement, scope creep, unverified assumption, unclear boundary |
 | [`jhste-code-quality`](skills/jhste-code-quality/SKILL.md)<br>检查 input validation、observable failure handling、secret-safe logging 和 oversized-file review 的 skill | 触及 external input、failure handling、logging、env/config 或 code-quality review path 时 | Unvalidated input, silent failure, secret logging, oversized file |
 | [`jhste-architecture-review`](skills/jhste-architecture-review/SKILL.md)<br>检查 module boundary、side-effect placement 和 SOLID-informed design risk 的架构 review skill | 修改 module boundary、app structure、side-effect placement 或 responsibility split 时 | Pass-through abstraction, mixed responsibility, side-effect leakage |
@@ -270,3 +284,5 @@ Release acceptance notes 请参考 [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_
 - 在称 non-trivial work 完成前执行 red-team code review。
 
 快速的 agent 需要 guardrail。`jhste-skills` 为它们提供 repo-respecting engineering workflow。
+
+Skills 共享来自 `skills/_shared/` 的 cross-cutting doctrine（SOLID lens、evidence discipline、issue-candidate protocol、scope discipline）。`skills/` 下名称以 `_` 开头的目录是 shared companion resources，不是 skills：它们会从 skill listing、selection 和 missing-skill checks 中排除，但安装任何 skill 时都会一起复制，确保已安装 artifact 中的 cross-skill `../_shared/...` references 不会悬空。

package/cli/global.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import os from 'node:os';
+import path from 'node:path';
+import { ask, parseArgs } from './shared.mjs';
+import { installSkills, removeManagedSkills } from './install-actions/skills.mjs';
+import { removeManagedGlobalBridge, writeManagedGlobalBridge } from './install-actions/bridge-writer.mjs';
+
+// Agent-neutral global setup: one canonical skills dir + a marker-managed bridge in
+// each agent's global instruction file. Advisory only — no per-repo files, no git hooks.
+const AGENT_TARGETS = {
+  claude: path.join(os.homedir(), '.claude', 'CLAUDE.md'),
+  codex: path.join(os.homedir(), '.codex', 'AGENTS.md'),
+  opencode: path.join(os.homedir(), '.config', 'opencode', 'AGENTS.md'),
+};
+
+function usage() {
+  console.log(`jhste-skills global
+Install jhste skills once at the user level for Codex and Claude Code. Advisory only.
+
+Usage:
+  jhste-skills global [--agents codex,claude,opencode] [--skill-set core|all] [--skills-dir <path>] [--force] [--yes]
+  jhste-skills global --uninstall [--agents codex,claude,opencode] [--skills-dir <path>] [--keep-skills] [--yes]
+
+Notes:
+  Skills (and shared companion resources) are copied to --skills-dir (default ~/.jhste/skills).
+  A marker-managed bridge block is written to each agent's global instruction file:
+    claude -> ~/.claude/CLAUDE.md
+    codex  -> ~/.codex/AGENTS.md
+    opencode -> ~/.config/opencode/AGENTS.md
+  Manifest-managed skills are refreshed automatically; --force also overwrites
+  unmanaged differing directories after review.
+  No git hooks and no per-repo files are written; guard stays advisory.
+  Use --claude-file / --codex-file / --opencode-file to override a target path.
+  --yes skips the confirmation prompt.
+`);
+}
+
+function fail(message) {
+  console.error(`jhste-skills global: ${message}`);
+  process.exit(1);
+}
+
+function parseAgents(value, errors) {
+  if (value === undefined) return ['codex', 'claude', 'opencode'];
+  if (typeof value !== 'string') {
+    errors.push('--agents requires a comma-separated value.');
+    return ['codex', 'claude', 'opencode'];
+  }
+  const list = String(value).split(',').map((item) => item.trim().toLowerCase()).filter(Boolean);
+  const unknown = list.filter((name) => !Object.prototype.hasOwnProperty.call(AGENT_TARGETS, name));
+  if (unknown.length) errors.push(`--agents supports only codex,claude,opencode; unknown: ${unknown.join(', ')}`);
+  return list.length ? [...new Set(list)] : ['codex', 'claude', 'opencode'];
+}
+
+function agentTargets(agents, args) {
+  const overrides = { claude: args['claude-file'], codex: args['codex-file'], opencode: args['opencode-file'] };
+  return agents.map((agent) => ({
+    agent,
+    file: typeof overrides[agent] === 'string' ? path.resolve(overrides[agent]) : AGENT_TARGETS[agent],
+  }));
+}
+
+function readBoolean(args, key, errors) {
+  if (!Object.prototype.hasOwnProperty.call(args, key)) return false;
+  if (args[key] !== true) errors.push(`--${key} does not take a value.`);
+  return args[key] === true;
+}
+
+function readString(args, key, errors) {
+  if (!Object.prototype.hasOwnProperty.call(args, key)) return undefined;
+  if (typeof args[key] !== 'string') {
+    errors.push(`--${key} requires a value.`);
+    return undefined;
+  }
+  return args[key];
+}
+
+async function confirmGlobalWrite(args, action, targets, skillsDir) {
+  if (args.yes === true || args.y === true) return true;
+  console.log(`jhste-skills global ${action}:`);
+  console.log(`  skills: ${skillsDir}`);
+  for (const { agent, file } of targets) console.log(`  ${agent}: ${file}`);
+  if (!process.stdin.isTTY) {
+    console.error(`Non-interactive global ${action} requires explicit --yes or -y; refusing to change files.`);
+    process.exit(3);
+  }
+  const answer = await ask(`Continue global ${action}? [y/N] `);
+  if (answer.toLowerCase() === 'y') return true;
+  console.log(`Global ${action} cancelled. No changes made.`);
+  return false;
+}
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help || args.h) return usage();
+  const errors = [];
+  const supported = new Set(['agents', 'skill-set', 'skills-dir', 'claude-file', 'codex-file', 'opencode-file', 'force', 'yes', 'y', 'uninstall', 'keep-skills', 'help', 'h', '_']);
+  for (const key of Object.keys(args)) {
+    if (!supported.has(key)) errors.push(`unknown option --${key}.`);
+  }
+  if (Array.isArray(args._) && args._.length) errors.push(`unexpected positional argument: ${args._[0]}`);
+
+  const uninstall = readBoolean(args, 'uninstall', errors);
+  const keepSkills = readBoolean(args, 'keep-skills', errors);
+  const force = readBoolean(args, 'force', errors);
+  readBoolean(args, 'yes', errors);
+  readBoolean(args, 'y', errors);
+  const skillSetRaw = readString(args, 'skill-set', errors);
+  const skillSet = skillSetRaw ? skillSetRaw.toLowerCase() : 'all';
+  if (!['core', 'all'].includes(skillSet)) errors.push('global --skill-set must be core or all because the global bridge requires core workflow skills.');
+  const skillsDirInput = readString(args, 'skills-dir', errors);
+  readString(args, 'claude-file', errors);
+  readString(args, 'codex-file', errors);
+  readString(args, 'opencode-file', errors);
+  const skillsDir = path.resolve(skillsDirInput || path.join(os.homedir(), '.jhste', 'skills'));
+  const agents = parseAgents(args.agents, errors);
+  if (errors.length) return fail(errors.join('\n'));
+
+  const targets = agentTargets(agents, args);
+  if (!(await confirmGlobalWrite(args, uninstall ? 'uninstall' : 'install', targets, skillsDir))) return;
+
+  if (uninstall) {
+    console.log('jhste-skills global uninstall:');
+    if (!keepSkills) {
+      const result = removeManagedSkills(skillsDir);
+      const removed = result.skills?.filter((item) => item.status === 'removed').length ?? 0;
+      console.log(`  skills: ${result.status}${result.status === 'removed-managed' ? ` (${removed} removed from ${skillsDir})` : ''}`);
+      if (result.status === 'invalid-manifest') {
+        console.log(`  blocked: ${result.reason || result.status} (${result.path})`);
+        console.log('  bridges: skipped because skills uninstall did not complete');
+        process.exitCode = 3;
+        return;
+      }
+    } else {
+      console.log(`  skills: kept (${skillsDir})`);
+    }
+    for (const { agent, file } of targets) {
+      const result = removeManagedGlobalBridge(file);
+      console.log(`  ${agent}: ${result.status} (${file})`);
+    }
+    return;
+  }
+
+  // `global` owns the canonical skills dir, so it refreshes manifest-managed skills
+  // automatically (idempotent: unchanged when identical) and adopts known jhste skills,
+  // while still protecting unmanaged differing directories unless --force is given.
+  const skillResults = installSkills(skillsDir, { force: true, adoptKnownSkills: true, allowUnmanagedOverwrite: force, skillSet });
+  const blocked = skillResults.filter((item) => ['skipped-unmanaged-different', 'invalid-manifest'].includes(item.status));
+  const copied = skillResults.filter((item) => ['created', 'overwritten-managed', 'adopted-managed', 'unchanged'].includes(item.status)).length;
+
+  console.log('jhste-skills global install:');
+  console.log(`  skills: ${copied} managed under ${skillsDir}${blocked.length ? ` (${blocked.length} skipped; rerun with --force after review)` : ''}`);
+  if (blocked.length) {
+    for (const item of blocked) {
+      console.log(`  blocked: ${item.reason || item.status} (${item.destination || item.source})`);
+    }
+    console.log('  bridges: skipped because skills install did not complete');
+    process.exitCode = 3;
+    return;
+  }
+  for (const { agent, file } of targets) {
+    const result = writeManagedGlobalBridge(file);
+    console.log(`  ${agent}: ${result.status} (${file})`);
+  }
+  console.log('\nAdvisory only: no git hooks and no per-repo files were written.');
+  console.log('Run guard manually anytime: jhste-skills guard --scope changed');
+}
+
+main(process.argv.slice(2));

package/cli/index.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 
 const cliDir = path.dirname(fileURLToPath(import.meta.url));
 const [command, ...rest] = process.argv.slice(2);
-const commands = new Set(['install', 'connect', 'sync', 'update', 'deep-scan', 'guard', 'hooks', 'tune', 'baseline', 'uninstall']);
+const commands = new Set(['install', 'connect', 'global', 'sync', 'update', 'deep-scan', 'guard', 'hooks', 'tune', 'baseline', 'uninstall']);
 
 if (!command || command === '--help' || command === '-h') {
   console.log(`jhste-skills
@@ -13,6 +13,7 @@ if (!command || command === '--help' || command === '-h') {
 Usage:
   jhste-skills install [--mode minimal|normal|full|custom] [--yes] [--repo <path>]
   jhste-skills connect [--mode normal|full|custom] [--repo <path>]
+  jhste-skills global [--agents codex,claude,opencode] [--skill-set core|all] [--uninstall]
   jhste-skills sync [--repo <path>] [--skills-dir <path>] [--yes]
   jhste-skills update [--repo <path>] [--skills-dir <path>] [--yes]
   jhste-skills deep-scan [--repo <path>]

package/cli/install-actions/bridge-writer.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { BRIDGE_BLOCK, BRIDGE_END, BRIDGE_START, MANAGED_BRIDGE_BLOCK, readIfExists } from '../shared.mjs';
+import { BRIDGE_BLOCK, BRIDGE_END, BRIDGE_START, MANAGED_BRIDGE_BLOCK, MANAGED_GLOBAL_BRIDGE_BLOCK, ensureDir, readIfExists } from '../shared.mjs';
 
 function escapeRegExp(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -27,6 +27,43 @@ export function bridgeStatus(repoRoot, fileName) {
   return { fileName, path: target, status: 'will-append-managed' };
 }
 
+// Write/refresh the agent-neutral global bridge in an absolute instruction file,
+// creating parent directories and the file when absent. Marker-managed and idempotent.
+export function writeManagedGlobalBridge(targetPath) {
+  ensureDir(path.dirname(targetPath));
+  const existing = readIfExists(targetPath);
+  if (existing === null) {
+    fs.writeFileSync(targetPath, `${MANAGED_GLOBAL_BRIDGE_BLOCK}\n`);
+    return { status: 'created', path: targetPath };
+  }
+  if (existing.includes(BRIDGE_START) && existing.includes(BRIDGE_END)) {
+    const pattern = new RegExp(`${escapeRegExp(BRIDGE_START)}[\\s\\S]*?${escapeRegExp(BRIDGE_END)}`);
+    const updated = existing.replace(pattern, MANAGED_GLOBAL_BRIDGE_BLOCK);
+    if (updated === existing) return { status: 'unchanged', path: targetPath };
+    fs.writeFileSync(targetPath, updated);
+    return { status: 'updated-managed', path: targetPath };
+  }
+  const prefix = existing.endsWith('\n') ? existing : `${existing}\n`;
+  fs.writeFileSync(targetPath, `${prefix}\n${MANAGED_GLOBAL_BRIDGE_BLOCK}\n`);
+  return { status: 'appended-managed', path: targetPath };
+}
+
+// Remove a marker-managed bridge block from an absolute instruction file. Deletes the
+// file only if it becomes empty and was created solely for the bridge.
+export function removeManagedGlobalBridge(targetPath) {
+  const existing = readIfExists(targetPath);
+  if (existing === null) return { status: 'absent', path: targetPath };
+  if (!(existing.includes(BRIDGE_START) && existing.includes(BRIDGE_END))) return { status: 'no-managed-block', path: targetPath };
+  const pattern = new RegExp(`\\n?${escapeRegExp(BRIDGE_START)}[\\s\\S]*?${escapeRegExp(BRIDGE_END)}\\n?`);
+  const updated = existing.replace(pattern, '\n').replace(/^\n+/, '').replace(/\n{3,}/g, '\n\n');
+  if (updated.trim() === '') {
+    fs.rmSync(targetPath, { force: true });
+    return { status: 'removed-empty-file', path: targetPath };
+  }
+  fs.writeFileSync(targetPath, updated);
+  return { status: 'removed-managed-block', path: targetPath };
+}
+
 export function writeManagedBridge(repoRoot, fileName) {
   const target = path.join(repoRoot, fileName);
   const existing = readIfExists(target);

package/cli/install-actions/skills.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { directoryDigest, ensureDir, KIT_ROOT, listDirectories, nowIso } from '../shared.mjs';
+import { directoryDigest, ensureDir, KIT_ROOT, listSharedResourceNames, listSkillDirectories, nowIso } from '../shared.mjs';
 import { readJsonFile, validateJsonObject, validateStringArray } from '../json-file.mjs';
 
 export const SKILLS_MANIFEST_NAME = '.jhste-skills-manifest.json';
@@ -26,7 +26,7 @@ function vendoredSkillNames() {
 
 export function skillNamesForSet(skillSet) {
   const sourceRoot = path.join(KIT_ROOT, 'skills');
-  const all = listDirectories(sourceRoot).filter((name) => !Object.prototype.hasOwnProperty.call(LEGACY_SKILL_RENAMES, name));
+  const all = listSkillDirectories(sourceRoot).filter((name) => !Object.prototype.hasOwnProperty.call(LEGACY_SKILL_RENAMES, name));
   const vendored = vendoredSkillNames();
   if (skillSet === 'all') return all;
   if (skillSet === 'vendor') return all.filter((name) => vendored.has(name));
@@ -44,6 +44,58 @@ export function installedSkillStatus(skillsDir, skillSet) {
   return { expected, missing };
 }
 
+// Single source for manifest-based removal, shared by `uninstall` and `global`.
+// Removes every manifest-managed directory (skills and shared companion resources
+// such as `_shared`), then the manifest, then best-effort empty-dir cleanup.
+export function loadInstalledManifest(skillsDir) {
+  const file = manifestPath(skillsDir);
+  if (!fs.existsSync(file)) return { manifest: null, path: file };
+  try {
+    const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!manifest || typeof manifest !== 'object' || manifest.managed_by !== MANIFEST_MANAGED_BY || typeof manifest.skills !== 'object' || Array.isArray(manifest.skills)) {
+      return { invalid: true, path: file, reason: `${SKILLS_MANIFEST_NAME} is not a valid ${MANIFEST_MANAGED_BY} manifest.` };
+    }
+    return { manifest, path: file };
+  } catch (error) {
+    return { invalid: true, path: file, reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export function removeManagedSkills(skillsDir) {
+  const loaded = loadInstalledManifest(skillsDir);
+  if (loaded.invalid) return { status: 'invalid-manifest', path: loaded.path, reason: loaded.reason, skills: [] };
+  if (!loaded.manifest) return { status: 'no-manifest', path: loaded.path, skills: [] };
+  for (const name of Object.keys(loaded.manifest.skills || {})) {
+    if (!name || name !== path.basename(name) || name === '.' || name === '..') {
+      return {
+        status: 'invalid-manifest',
+        path: loaded.path,
+        reason: `${SKILLS_MANIFEST_NAME} contains an invalid managed skill name: ${name}`,
+        skills: [],
+      };
+    }
+  }
+  const skills = [];
+  for (const name of Object.keys(loaded.manifest.skills || {}).sort()) {
+    const dir = path.join(skillsDir, name);
+    if (!fs.existsSync(dir)) {
+      skills.push({ name, status: 'absent' });
+      continue;
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+    skills.push({ name, status: 'removed' });
+  }
+  fs.rmSync(loaded.path, { force: true });
+  try {
+    if (fs.existsSync(skillsDir) && fs.readdirSync(skillsDir).length === 0) fs.rmdirSync(skillsDir);
+    const parent = path.dirname(skillsDir);
+    if (fs.existsSync(parent) && fs.readdirSync(parent).length === 0) fs.rmdirSync(parent);
+  } catch {
+    // Empty-dir cleanup is best-effort only.
+  }
+  return { status: 'removed-managed', path: loaded.path, skills };
+}
+
 function manifestPath(skillsDir) {
   return path.join(skillsDir, SKILLS_MANIFEST_NAME);
 }
@@ -201,6 +253,7 @@ export function installSkills(skillsDir, {
   const sourceRoot = path.join(KIT_ROOT, 'skills');
   ensureDir(skillsDir);
   const selected = (Array.isArray(skillSet) ? skillSet : skillNamesForSet(skillSet)).map((name) => canonicalSkillName(name));
+  const shared = selected.length ? listSharedResourceNames(sourceRoot) : [];
   const currentManifest = loadSkillsManifest(skillsDir);
   if (currentManifest?.invalid) return [{ status: 'invalid-manifest', source: '', destination: manifestPath(skillsDir), reason: currentManifest.reason }];
   const nextManifest = currentManifest || { managed_by: MANIFEST_MANAGED_BY, version: packageVersion(), installed_at: nowIso(), skills: {} };
@@ -209,7 +262,7 @@ export function installSkills(skillsDir, {
   nextManifest.updated_at = nowIso();
   nextManifest.skills ||= {};
   const conflicts = force && !allowUnmanagedOverwrite
-    ? unmanagedSkillConflicts(selected, sourceRoot, skillsDir, currentManifest, { adoptKnownSkills })
+    ? unmanagedSkillConflicts([...selected, ...shared], sourceRoot, skillsDir, currentManifest, { adoptKnownSkills })
     : [];
   if (conflicts.length) return conflicts;
   const legacyResults = removeLegacySkillDirectories(skillsDir, selected, currentManifest, nextManifest, {
@@ -224,6 +277,18 @@ export function installSkills(skillsDir, {
     manifest: currentManifest,
     nextManifest,
   }));
+  // Copy shared companion resources (e.g. `_shared/` doctrine) alongside skills so
+  // installed `../_shared/...` references never dangle. These are not skills and are
+  // excluded from skill enumeration/status, but reuse managed-copy semantics.
+  const sharedResults = shared.length
+    ? shared.map((name) => copyManagedSkill(path.join(sourceRoot, name), path.join(skillsDir, name), name, {
+        force,
+        allowUnmanagedOverwrite,
+        adoptKnownSkills,
+        manifest: currentManifest,
+        nextManifest,
+      }))
+    : [];
   writeSkillsManifest(skillsDir, nextManifest);
-  return [...legacyResults, ...deletedResults, ...results];
+  return [...legacyResults, ...deletedResults, ...results, ...sharedResults];
 }

package/cli/postinstall-global-refresh.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { installSkills } from './install-actions/skills.mjs';
+import { writeManagedGlobalBridge } from './install-actions/bridge-writer.mjs';
+import { BRIDGE_END, BRIDGE_START } from './shared.mjs';
+
+const AGENT_TARGETS = {
+  claude: path.join(os.homedir(), '.claude', 'CLAUDE.md'),
+  codex: path.join(os.homedir(), '.codex', 'AGENTS.md'),
+  opencode: path.join(os.homedir(), '.config', 'opencode', 'AGENTS.md'),
+};
+
+function isGlobalNpmLifecycle() {
+  return process.env.npm_config_global === 'true' || process.env.npm_config_location === 'global';
+}
+
+function hasManagedBridge(file) {
+  if (!fs.existsSync(file)) return false;
+  const text = fs.readFileSync(file, 'utf8');
+  return text.includes(BRIDGE_START) && text.includes(BRIDGE_END);
+}
+
+function main() {
+  if (!isGlobalNpmLifecycle()) return;
+  const skillsDir = path.join(os.homedir(), '.jhste', 'skills');
+  const manifestExists = fs.existsSync(path.join(skillsDir, '.jhste-skills-manifest.json'));
+  const bridgeTargets = Object.entries(AGENT_TARGETS)
+    .filter(([, file]) => hasManagedBridge(file))
+    .map(([agent, file]) => ({ agent, file }));
+
+  // Do not create a new global setup from an npm lifecycle hook. Only refresh a
+  // global setup the user already opted into with `jhste-skills global`.
+  if (!manifestExists && bridgeTargets.length === 0) return;
+
+  const skillResults = installSkills(skillsDir, {
+    force: true,
+    adoptKnownSkills: true,
+    allowUnmanagedOverwrite: false,
+    skillSet: 'all',
+  });
+  const blocked = skillResults.filter((item) => ['skipped-unmanaged-different', 'invalid-manifest'].includes(item.status));
+  if (blocked.length) {
+    console.warn(`jhste-skills postinstall: global skill refresh skipped (${blocked.length} blocked); run jhste-skills global --force after review.`);
+    return;
+  }
+
+  for (const { file } of bridgeTargets) writeManagedGlobalBridge(file);
+  console.log(`jhste-skills postinstall: refreshed global skills${bridgeTargets.length ? ` and ${bridgeTargets.length} global bridge(s)` : ''}.`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.warn(`jhste-skills postinstall: global refresh skipped: ${error instanceof Error ? error.message : String(error)}`);
+}

package/cli/shared/files.mjs

@@ -25,6 +25,22 @@ export function listDirectories(dir) {
     .sort();
 }
 
+// Directories under skills/ whose name starts with `_` are shared companion
+// resources (doctrine/templates), not skills. They ship in the package and are
+// copied alongside skills so cross-skill `../_shared/...` references resolve,
+// but are excluded from skill enumeration, selection, and missing-skill checks.
+export function isSharedResourceName(name) {
+  return name.startsWith('_');
+}
+
+export function listSkillDirectories(dir) {
+  return listDirectories(dir).filter((name) => !isSharedResourceName(name));
+}
+
+export function listSharedResourceNames(dir) {
+  return listDirectories(dir).filter((name) => isSharedResourceName(name));
+}
+
 export function directoryDigest(dir) {
   const hash = crypto.createHash('sha256');
   if (!fs.existsSync(dir)) return null;

package/cli/shared/templates.mjs

@@ -26,6 +26,27 @@ Do not enter an unbounded fix/review loop; stop after at most two fix + re-revie
 
 export const MANAGED_BRIDGE_BLOCK = `${BRIDGE_START}\n${BRIDGE_BLOCK}\n${BRIDGE_END}`;
 
+// Agent-neutral variant written to a global instruction file (e.g. Claude
+// ~/.claude/CLAUDE.md, Codex ~/.codex/AGENTS.md, OpenCode
+// ~/.config/opencode/AGENTS.md). Shares the same markers so it is
+// marker-managed (idempotent update/removal), but omits repo-only wording and the
+// repo profile reference, and frames guard as advisory (no per-repo hooks).
+export const GLOBAL_BRIDGE_BLOCK = `## Agent skills (jhste, global)
+jhste skills are installed globally as shared engineering guidance for this agent.
+Repo-local AGENTS.md, CLAUDE.md, and docs remain authoritative when present.
+File, repo, command, issue, PR, or other external side effects are allowed when the user directly requested that workflow or repo-local standing approval covers it.
+Ask for destructive, irreversible, ambiguous, production, secret, cost-bearing, broad existing-item, or out-of-scope changes.
+For reversible in-scope choices, make a reasonable assumption, proceed, and report it in the final summary.
+Before non-trivial code changes, use the \`jhste-engineering-groundwork\` skill to check scope, boundaries, failure paths, final behavior predicates, and assumptions.
+For changed code, name the one main responsibility of each changed class, module, and function, and reject adjacent responsibilities unless they are on the changed execution path and prevent a concrete failure.
+Use SOLID-informed coding discipline as a clean-code review lens for concrete failure modes, not a compliance claim or automatic abstraction trigger; guard findings are review candidates, not proof.
+After code changes, run \`jhste-skills guard --scope changed --format text --fail-on warning\` when available; treat guard output as advisory review evidence, not proof.
+Before declaring non-trivial code work complete, use the \`jhste-red-team-review\` skill.
+Skip red-team review for docs-only, comment-only, formatting-only, or trivial rename-only changes.
+Do not enter an unbounded fix/review loop; stop after at most two fix + re-review cycles and report remaining risks.`;
+
+export const MANAGED_GLOBAL_BRIDGE_BLOCK = `${BRIDGE_START}\n${GLOBAL_BRIDGE_BLOCK}\n${BRIDGE_END}`;
+
 export const DEFAULT_PROFILE = `version: 1
 mode: advisory
 installed_at: "<installed_at>"