jhste-skills 0.3.6 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # 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
+- Added `implement`, a jhste-compatible implementation workflow skill for scoped PRD/issue/spec work.
+- Added `writing-great-skills`, replacing the legacy `write-a-skill` skill with upstream skill-writing guidance.
+
+### Changed
+- Refreshed Matt Pocock vendored workflow skills against upstream `43ea088`, excluding `tdd` and `resolving-merge-conflicts`.
+- Updated `triage` to cover external PRs as a triage surface, including PR diff verification and PR-specific agent briefs.
+- Slimmed duplicated architecture/grilling docs by routing shared vocabulary through `codebase-design`, `grilling`, and `domain-modeling`.
+- Updated issue slicing to prefer prefactoring slices where they make later implementation easier and to represent human decisions as blockers rather than a separate HITL/AFK field.
+- Removed managed legacy `write-a-skill` installs during sync/update; `writing-great-skills` is the replacement skill going forward.
+
+### Validation
+- `npm test` passed.
+- `jhste-skills guard --scope changed --format text --fail-on error` passed with 0 warnings/errors.
+- `git diff --check` passed.
 ## 0.3.6 - 2026-06-28
 
 ### Changed

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 |
@@ -172,7 +186,7 @@ Custom   - 効果ベースの質問でセットアップ範囲を選択
 
 ## Bundled workflow skills
 
-Normal install では、Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring した 13 個の workflow skills もインストールします。これらは debugging、planning、architecture、issue workflow、prototyping、handoff に役立ちます。インストールしたくない場合は `--skill-set core` を使ってください。
+Normal install では、Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring した 14 個の workflow skills もインストールします。これらは implementation、debugging、planning、architecture、issue workflow、prototyping、handoff、skill-writing guidance に役立ちます。インストールしたくない場合は `--skill-set core` を使ってください。
 
 | Skill | いつ使うか |
 |---|---|
@@ -188,11 +202,12 @@ Normal install では、Matt Pocock の [`mattpocock/skills`](https://github.com
 | [`to-issues`](skills/to-issues/SKILL.md)<br>計画を issue-ready vertical slices に分解する skill | implementation tickets/work breakdown が必要なとき; tracker creation は直接依頼または repo approval がある場合 |
 | [`triage`](skills/triage/SKILL.md)<br>issue を分類し次の action を計画する triage skill | issue classification、next-action planning、repo-approved triage writes が必要なとき |
 | [`handoff`](skills/handoff/SKILL.md)<br>次の agent や session が続けられるよう context を圧縮する handoff skill | handoff、session summary、continuation brief、next-agent context の依頼時 |
-| [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>正しい構造と progressive disclosure で agent skill を作成する skill-writing skill | agent skill を作成または改善したいとき |
+| [`implement`](skills/implement/SKILL.md)<br>jhste groundwork、verification、guard、review を使う scoped PRD/issue/spec implementation workflow skill | PRD、issue、spec、handoff から focused work を実装したいとき |
+| [`writing-great-skills`](skills/writing-great-skills/SKILL.md)<br>predictable invocation、progressive disclosure、context load control、pruning の skill-writing reference | agent skill を作成、置換、改善したいとき |
 
 ## Attribution: Matt Pocock skills
 
-このリポジトリは、上記 13 個の skills を Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring しています。
+このリポジトリは、上記 14 個の skills を Matt Pocock の [`mattpocock/skills`](https://github.com/mattpocock/skills) から vendoring しています。
 
 これらの skills は upstream MIT License に基づいて vendoring されています。このリポジトリは必要な copyright/license notice を保持し、インポート元を記録しています。
 
@@ -269,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 |
@@ -175,7 +189,7 @@ Custom   - 효과 중심 질문을 통해 설치 범위를 직접 선택
 
 ## Bundled workflow skills
 
-Normal install은 Matt Pocock의 [`mattpocock/skills`](https://github.com/mattpocock/skills)에서 vendoring한 workflow skills 13개도 함께 설치합니다. 이 스킬들은 debugging, planning, architecture, issue workflow, prototyping, handoff 작업에 유용합니다. 설치하고 싶지 않다면 `--skill-set core`를 사용하세요.
+Normal install은 Matt Pocock의 [`mattpocock/skills`](https://github.com/mattpocock/skills)에서 vendoring한 workflow skills 14개도 함께 설치합니다. 이 스킬들은 implementation, debugging, planning, architecture, issue workflow, prototyping, handoff, skill-writing guidance 작업에 유용합니다. 설치하고 싶지 않다면 `--skill-set core`를 사용하세요.
 
 | Skill | 언제 쓰나 |
 |---|---|
@@ -191,7 +205,8 @@ Normal install은 Matt Pocock의 [`mattpocock/skills`](https://github.com/mattpo
 | [`to-issues`](skills/to-issues/SKILL.md)<br>계획을 issue-ready vertical slice로 나누는 스킬 | implementation ticket/work breakdown이 필요할 때; tracker creation은 직접 요청이나 repo approval이 있을 때 |
 | [`triage`](skills/triage/SKILL.md)<br>issue를 분류하고 다음 행동을 계획하는 triage 스킬 | issue classification, next-action planning, repo-approved triage write가 필요할 때 |
 | [`handoff`](skills/handoff/SKILL.md)<br>다음 agent나 session이 이어받을 수 있도록 context를 압축하는 handoff 스킬 | handoff, session summary, continuation brief, next-agent context 요청 시 |
-| [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>새로운 agent skill을 올바른 구조와 progressive disclosure 방식으로 작성하는 스킬 | agent skill을 새로 만들거나 다듬고 싶을 때 |
+| [`implement`](skills/implement/SKILL.md)<br>jhste groundwork, verification, guard, review를 사용하는 scoped PRD/issue/spec 구현 workflow 스킬 | PRD, issue, spec, handoff에서 focused work를 구현하고 싶을 때 |
+| [`writing-great-skills`](skills/writing-great-skills/SKILL.md)<br>predictable invocation, progressive disclosure, context load control, pruning을 다루는 skill-writing reference | agent skill을 만들거나, 교체하거나, 다듬고 싶을 때 |
 
 ## Attribution: Matt Pocock skills
 
@@ -272,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 |
@@ -175,7 +189,7 @@ These are the jhste-authored guardrail skills. They are installed by default as
 
 ## Bundled workflow skills
 
-Normal install also includes 13 workflow skills vendored from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills). These are useful for debugging, planning, architecture, issue workflows, prototyping, and handoffs. Use `--skill-set core` if you do not want them installed.
+Normal install also includes 14 workflow skills vendored from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills). These are useful for implementation, debugging, planning, architecture, issue workflows, prototyping, handoffs, and skill-writing guidance. Use `--skill-set core` if you do not want them installed.
 
 | Skill | Use it when |
 |---|---|
@@ -191,11 +205,12 @@ Normal install also includes 13 workflow skills vendored from Matt Pocock's [`ma
 | [`to-issues`](skills/to-issues/SKILL.md)<br>A skill that breaks a plan into issue-ready vertical slices | You want implementation tickets or work breakdown; tracker creation follows direct request or repo approval |
 | [`triage`](skills/triage/SKILL.md)<br>An issue triage skill that classifies issues and plans next actions through a structured workflow | You want issue classification, next-action planning, or repo-approved triage writes |
 | [`handoff`](skills/handoff/SKILL.md)<br>A handoff skill that compresses context so the next agent or session can continue | You ask for a handoff, session summary, continuation brief, or next-agent context |
-| [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>A skill-writing skill for creating agent skills with the right structure and progressive disclosure | You want to create or refine an agent skill |
+| [`implement`](skills/implement/SKILL.md)<br>An implementation workflow skill for scoped PRD/issue/spec work using jhste groundwork, verification, guard, and review | You want an agent to implement focused work from a PRD, issue, spec, or handoff |
+| [`writing-great-skills`](skills/writing-great-skills/SKILL.md)<br>A skill-writing reference for predictable invocation, progressive disclosure, context load control, and pruning | You want to create, replace, or refine an agent skill |
 
 ## Attribution: Matt Pocock skills
 
-This repository vendors the 13 skills listed above from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills).
+This repository vendors the 14 skills listed above from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills).
 
 Those skills are vendored under the upstream MIT License. This repository preserves the required copyright/license notice and records the imported sources.
 
@@ -273,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.
 
-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` without leaving duplicate skill directories.
+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 |
@@ -172,7 +186,7 @@ Custom   - 通过面向效果的问题自定义安装范围
 
 ## Bundled workflow skills
 
-Normal install 还会安装 13 个从 Matt Pocock 的 [`mattpocock/skills`](https://github.com/mattpocock/skills) vendoring 的 workflow skills。它们适用于 debugging、planning、architecture、issue workflow、prototyping 和 handoff。若不想安装它们，请使用 `--skill-set core`。
+Normal install 还会安装 14 个从 Matt Pocock 的 [`mattpocock/skills`](https://github.com/mattpocock/skills) vendoring 的 workflow skills。它们适用于 implementation、debugging、planning、architecture、issue workflow、prototyping、handoff 和 skill-writing guidance。若不想安装它们，请使用 `--skill-set core`。
 
 | Skill | 何时使用 |
 |---|---|
@@ -188,11 +202,12 @@ Normal install 还会安装 13 个从 Matt Pocock 的 [`mattpocock/skills`](http
 | [`to-issues`](skills/to-issues/SKILL.md)<br>把计划拆成 issue-ready vertical slices 的 skill | 需要 implementation tickets/work breakdown；tracker creation 需直接请求或 repo approval |
 | [`triage`](skills/triage/SKILL.md)<br>分类 issue 并规划下一步行动的 triage skill | 需要 issue classification、next-action planning 或 repo-approved triage writes 时 |
 | [`handoff`](skills/handoff/SKILL.md)<br>压缩 context，让下一个 agent 或 session 能继续工作的 handoff skill | 请求 handoff、session summary、continuation brief 或 next-agent context 时 |
-| [`write-a-skill`](skills/write-a-skill/SKILL.md)<br>用正确结构和 progressive disclosure 创建 agent skill 的 skill-writing skill | 想创建或改进 agent skill 时 |
+| [`implement`](skills/implement/SKILL.md)<br>使用 jhste groundwork、verification、guard、review 的 scoped PRD/issue/spec implementation workflow skill | 想从 PRD、issue、spec 或 handoff 实现 focused work 时 |
+| [`writing-great-skills`](skills/writing-great-skills/SKILL.md)<br>关于 predictable invocation、progressive disclosure、context load control、pruning 的 skill-writing reference | 想创建、替换或改进 agent skill 时 |
 
 ## Attribution: Matt Pocock skills
 
-本仓库从 Matt Pocock 的 [`mattpocock/skills`](https://github.com/mattpocock/skills) vendoring 了上面列出的 13 个 skills。
+本仓库从 Matt Pocock 的 [`mattpocock/skills`](https://github.com/mattpocock/skills) vendoring 了上面列出的 14 个 skills。
 
 这些 skills 按 upstream MIT License vendoring。本仓库保留所需 copyright/license notice，并记录导入来源。
 
@@ -269,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);