diff --git a/.agents/skills/README.md b/.agents/skills/README.md
new file mode 100644
index 0000000..d337b02
--- /dev/null
+++ b/.agents/skills/README.md
@@ -0,0 +1,7 @@
+# Fleet Skills
+
+Canonical source for the fleet's Claude Code / opencode / Codex Skills, one directory per skill: `<name>/SKILL.md` plus optional `scripts/` and `references/`. This is the only place a skill's content is hand-authored. Everything else derived from it is generated, never hand-edited.
+
+Codex and opencode read this directory directly (`.agents/skills/<name>/SKILL.md`), no install step required, walking from a downstream repo's working directory up to its own repository root. Claude Code does not scan this path. `scripts/build_dist.py` generates a Claude-plugin-compatible copy at `.claude-plugin/fleet-skills/`, published through `.claude-plugin/marketplace.json`.
+
+See `AGENTS.md` for how a repo depends on these skills and `scripts/README.md` for `build_dist.py` and the installer.
diff --git a/.agents/skills/carried-instruction-file-guard/SKILL.md b/.agents/skills/carried-instruction-file-guard/SKILL.md
new file mode 100644
index 0000000..012fc4e
--- /dev/null
+++ b/.agents/skills/carried-instruction-file-guard/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: carried-instruction-file-guard
+description: >-
+  Stops a blind overwrite of a downstream repo's AGENTS.md, GOVERNANCE.md, CODESTYLE.md, or WORKFLOW.md when resyncing or updating it to match the ptr727/ProjectTemplate hub template. Use this whenever about to edit, replace, re-vendor, or sync-to-match-the-hub any of those four files in a repository that is not ProjectTemplate itself, or whenever asked to bring a repo's instruction set up to date, run a conformance sweep, or fix drift against the hub. Triggers even when the request sounds routine, such as copying the hub's AGENTS.md over or resyncing a repo's docs, because that phrasing is exactly how a real incident happened, where a downstream repo's local rules were silently deleted by a full-file overwrite. Do not skip this just because the task looks mechanical.
+---
+
+# Carried Instruction File Guard
+
+## Why this exists
+
+A downstream repo's `AGENTS.md`/`GOVERNANCE.md`/`CODESTYLE.md`/`WORKFLOW.md` can hold two different kinds of content mixed in one file: sections that are stale copies of the hub's fleet-wide rules, and local rules the repo wrote for a fault the fleet has never seen elsewhere. Re-vendoring the hub's canonical version over the whole file deletes the second kind silently, because nothing about the diff looks wrong. This has actually happened: a resync replaced a repo's `AGENTS.md` wholesale with the hub's, and the repo's own local additions were gone with no error, no warning, and no review comment calling it out.
+
+The fix is not "be careful." Being careful is what failed the first time. The fix is a mechanical check you run before any overwrite touches one of these four files, every time, regardless of how routine the request sounds.
+
+## Before you touch any of these four files
+
+1. **Check whether the file's content is declared `verbatim` or `intent`.** The hub's `spec/section-model.md` (fetch it from a hub checkout, `github.com/ptr727/ProjectTemplate`, if you don't have one) names, section by section, which parts of `AGENTS.md` and `GOVERNANCE.md` are universal fleet law (safe to byte-match against the hub) and which describe the repo itself (never safe to overwrite from another repo). `CODESTYLE.md` and `WORKFLOW.md` are carried whole at `intent` fidelity, judged by meaning, not hashed.
+2. **If any part of the file is `intent`, or if the file predates a clean split into hub-governed sections, do not diff-and-replace. Probe instead.** For each rule or paragraph in the current file that is not obviously boilerplate:
+   - Pick the phrase in it that is most peculiar to this repo, not generic governance vocabulary. A rule about "always sign commits" is generic. A rule about "this repo's Docker image pins Alpine 3.19 because 3.20 broke the s6 supervisor" is peculiar.
+   - Grep the hub's canonical copy of the same file for that peculiar phrase.
+   - **Absent from the hub canonical means it is a local addition.** It is never dropped because it looks similar to something else, and never dropped because a merge or overwrite would be simpler without it.
+3. **A local addition found by the probe gets a destination, not a deletion.** Either it names a rule that should apply fleet-wide (flag it for the maintainer to promote into the hub), or it is genuinely specific to this repo and moves to the repo's own topical doc before the carried file is touched: `CODESTYLE.md` for a language/formatting convention, `ARCHITECTURE.md` for a design decision, `OPERATIONS.md` for a runbook or operational note, `TODO.md` for backlog. Move it, confirm it is not lost, and only then proceed with the carry.
+4. **Do not trust a similarity or word-overlap check for step 2.** A repo-specific rule written in ordinary governance language reads as a reworded duplicate of an unrelated hub rule to that kind of check, and it will confidently tell you the local content is redundant when it is not. Exact phrase presence or absence is the only check that has held up.
+
+## What is actually safe to overwrite without this procedure
+
+A section `spec/section-model.md` names as `verbatim`, in a file that is already cleanly split (the file carries only that declared section, nothing else mixed in), can be re-vendored directly: byte-matching it against the hub canonical is the point of `verbatim` fidelity, and the audit already checks it that way. The guard above is for everything else: `intent`-fidelity content, a file that has not been split yet, or any file you are not certain is clean.
+
+## If you are not sure which case you are in
+
+Stop and say so, rather than guessing. Naming the uncertainty costs one sentence. Silently overwriting the wrong thing costs someone's local rules with no way to notice until much later.
diff --git a/.claude-plugin/fleet-skills/.claude-plugin/plugin.json b/.claude-plugin/fleet-skills/.claude-plugin/plugin.json
new file mode 100644
index 0000000..edc0fe1
--- /dev/null
+++ b/.claude-plugin/fleet-skills/.claude-plugin/plugin.json
@@ -0,0 +1,11 @@
+{
+  "name": "fleet-skills",
+  "version": "0.0.0",
+  "description": "Fleet-wide agent rules (comment style, PR-review conduct, resync safety) packaged as Claude Code Skills, generated from .agents/skills/.",
+  "author": {
+    "name": "ptr727"
+  },
+  "skills": [
+    "./skills/carried-instruction-file-guard"
+  ]
+}
diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest
new file mode 100644
index 0000000..66d4887
--- /dev/null
+++ b/.claude-plugin/fleet-skills/.source-digest
@@ -0,0 +1 @@
+948c01300ae03ac7
diff --git a/.claude-plugin/fleet-skills/skills/carried-instruction-file-guard/SKILL.md b/.claude-plugin/fleet-skills/skills/carried-instruction-file-guard/SKILL.md
new file mode 100644
index 0000000..012fc4e
--- /dev/null
+++ b/.claude-plugin/fleet-skills/skills/carried-instruction-file-guard/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: carried-instruction-file-guard
+description: >-
+  Stops a blind overwrite of a downstream repo's AGENTS.md, GOVERNANCE.md, CODESTYLE.md, or WORKFLOW.md when resyncing or updating it to match the ptr727/ProjectTemplate hub template. Use this whenever about to edit, replace, re-vendor, or sync-to-match-the-hub any of those four files in a repository that is not ProjectTemplate itself, or whenever asked to bring a repo's instruction set up to date, run a conformance sweep, or fix drift against the hub. Triggers even when the request sounds routine, such as copying the hub's AGENTS.md over or resyncing a repo's docs, because that phrasing is exactly how a real incident happened, where a downstream repo's local rules were silently deleted by a full-file overwrite. Do not skip this just because the task looks mechanical.
+---
+
+# Carried Instruction File Guard
+
+## Why this exists
+
+A downstream repo's `AGENTS.md`/`GOVERNANCE.md`/`CODESTYLE.md`/`WORKFLOW.md` can hold two different kinds of content mixed in one file: sections that are stale copies of the hub's fleet-wide rules, and local rules the repo wrote for a fault the fleet has never seen elsewhere. Re-vendoring the hub's canonical version over the whole file deletes the second kind silently, because nothing about the diff looks wrong. This has actually happened: a resync replaced a repo's `AGENTS.md` wholesale with the hub's, and the repo's own local additions were gone with no error, no warning, and no review comment calling it out.
+
+The fix is not "be careful." Being careful is what failed the first time. The fix is a mechanical check you run before any overwrite touches one of these four files, every time, regardless of how routine the request sounds.
+
+## Before you touch any of these four files
+
+1. **Check whether the file's content is declared `verbatim` or `intent`.** The hub's `spec/section-model.md` (fetch it from a hub checkout, `github.com/ptr727/ProjectTemplate`, if you don't have one) names, section by section, which parts of `AGENTS.md` and `GOVERNANCE.md` are universal fleet law (safe to byte-match against the hub) and which describe the repo itself (never safe to overwrite from another repo). `CODESTYLE.md` and `WORKFLOW.md` are carried whole at `intent` fidelity, judged by meaning, not hashed.
+2. **If any part of the file is `intent`, or if the file predates a clean split into hub-governed sections, do not diff-and-replace. Probe instead.** For each rule or paragraph in the current file that is not obviously boilerplate:
+   - Pick the phrase in it that is most peculiar to this repo, not generic governance vocabulary. A rule about "always sign commits" is generic. A rule about "this repo's Docker image pins Alpine 3.19 because 3.20 broke the s6 supervisor" is peculiar.
+   - Grep the hub's canonical copy of the same file for that peculiar phrase.
+   - **Absent from the hub canonical means it is a local addition.** It is never dropped because it looks similar to something else, and never dropped because a merge or overwrite would be simpler without it.
+3. **A local addition found by the probe gets a destination, not a deletion.** Either it names a rule that should apply fleet-wide (flag it for the maintainer to promote into the hub), or it is genuinely specific to this repo and moves to the repo's own topical doc before the carried file is touched: `CODESTYLE.md` for a language/formatting convention, `ARCHITECTURE.md` for a design decision, `OPERATIONS.md` for a runbook or operational note, `TODO.md` for backlog. Move it, confirm it is not lost, and only then proceed with the carry.
+4. **Do not trust a similarity or word-overlap check for step 2.** A repo-specific rule written in ordinary governance language reads as a reworded duplicate of an unrelated hub rule to that kind of check, and it will confidently tell you the local content is redundant when it is not. Exact phrase presence or absence is the only check that has held up.
+
+## What is actually safe to overwrite without this procedure
+
+A section `spec/section-model.md` names as `verbatim`, in a file that is already cleanly split (the file carries only that declared section, nothing else mixed in), can be re-vendored directly: byte-matching it against the hub canonical is the point of `verbatim` fidelity, and the audit already checks it that way. The guard above is for everything else: `intent`-fidelity content, a file that has not been split yet, or any file you are not certain is clean.
+
+## If you are not sure which case you are in
+
+Stop and say so, rather than guessing. Naming the uncertainty costs one sentence. Silently overwriting the wrong thing costs someone's local rules with no way to notice until much later.
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..8185806
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,14 @@
+{
+  "name": "projecttemplate-fleet",
+  "description": "Fleet-wide agent rules for the ptr727 repos, packaged as Claude Code Skills.",
+  "owner": {
+    "name": "ptr727"
+  },
+  "plugins": [
+    {
+      "name": "fleet-skills",
+      "description": "Fleet-wide agent rules (comment style, PR-review conduct, resync safety) packaged as Claude Code Skills.",
+      "source": "./.claude-plugin/fleet-skills"
+    }
+  ]
+}
diff --git a/.gitattributes b/.gitattributes
index bc83c5f..e4eb150 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -35,6 +35,10 @@ scripts/test_pr_review.py text eol=lf
 scripts/host_gate.py text eol=lf
 scripts/test_host_gate.py text eol=lf
 scripts/test_bootstrap.py text eol=lf
+scripts/build_dist.py text eol=lf
+scripts/test_build_dist.py text eol=lf
+scripts/skills_install.py text eol=lf
+scripts/test_skills_install.py text eol=lf
 
 # The uv tool regenerates uv.lock with LF on every platform, so pin it here.
 # That makes git enforce LF on checkout and renormalize, so a CRLF-default repo does not fight the tool on every `uv lock` or `uv sync`.
diff --git a/.github/workflows/validate-task.yml b/.github/workflows/validate-task.yml
index fbeb927..bfb8ef0 100644
--- a/.github/workflows/validate-task.yml
+++ b/.github/workflows/validate-task.yml
@@ -97,6 +97,8 @@ jobs:
           python3 scripts/test_prose_lint.py
           python3 scripts/test_repo_gate.py
           python3 scripts/test_pr_review.py
+          python3 scripts/test_build_dist.py
+          python3 scripts/test_skills_install.py
           python3 spec/audit.py --selftest
           python3 host-setup/agent-safety/gh-write-guard.py --selftest
           python3 host-setup/agent-safety/test_install.py
@@ -104,6 +106,10 @@ jobs:
       - name: Check repo gates step
         run: python3 scripts/repo_gate.py
 
+      # Read-only: fails if .claude-plugin/fleet-skills/ was not regenerated from .agents/skills/.
+      - name: Check fleet skills are current step
+        run: python3 scripts/build_dist.py --check
+
       # Every default prose rule is clean tree-wide, so all but one block a change that adds a finding.
       # `charset-unknown` is the exception and reports in the step below, for the reason given there.
       - name: Check prose step
diff --git a/AGENTS.md b/AGENTS.md
index 8fad245..f9acb0d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,3 +87,5 @@ Every rule below is a level-two section of [`GOVERNANCE.md`](./GOVERNANCE.md). R
 | Editor settings and tasks | `Editor and Tasks` |
 | The About panel, description, or repo toggles | `Repository Details` |
 | Where a file belongs in the tree | `Repository Layout` |
+
+Some of the rules above are also packaged as Claude Code / opencode / Codex Skills, hand-authored at [`.agents/skills/`](./.agents/skills/) in the hub, so they surface automatically instead of needing to be re-read every session. `scripts/` is hub-hosted and reached rather than carried, per "Hub-Hosted Tooling", so run the installer from a hub checkout: `python3 scripts/skills_install.py` (or the `.sh`/`.ps1` wrapper) once per machine, from `github.com/ptr727/ProjectTemplate`, installs them for every repo touched from that machine. `python3 scripts/skills_install.py --report`, also from a hub checkout, says whether this machine is current. A rule that keeps needing to be restated is a sign the install is missing or stale, not that the rule does not exist.
diff --git a/TODO.md b/TODO.md
index 71be78e..cb930e5 100644
--- a/TODO.md
+++ b/TODO.md
@@ -23,6 +23,20 @@ The steps below are followed in order rather than sampled.
 
 ## Work Clusters
 
+### Default `.py` to LF Fleet-Wide, Retiring the Per-Path Pin List
+
+One pull request changing [`GOVERNANCE.md`][governance] "Line Endings", [`.editorconfig`][editorconfig], and [`.gitattributes`][gitattributes] to pin `*.py` LF by extension, replacing the growing list of individually-pinned shebang scripts, plus the one-time renormalization it obliges fleet-wide.
+
+**State** `decision`. **Touches** `GOVERNANCE.md` "Line Endings" (verbatim, so it re-vendors fleet-wide), `.editorconfig`, `.gitattributes`, and every downstream repo carrying a CRLF `.py` file. **Cost** one hub edit plus a renormalization pass per affected repo. The hub itself needs no renormalization, since every `.py` file it tracks is already LF.
+
+- **Pin `*.py text eol=lf` by extension and drop the by-path list it replaces.** The by-path list exists because the fleet's default is CRLF for `.py` and only a shebang-executed script needs LF, so each new script has needed its own `.gitattributes` line and its own `.editorconfig` override. It reads 25 entries today, up from the roughly dozen it carried before this session added four more for two new scripts and their tests, which is the divergence outweighing the reason it was chosen.
+  - **Blocked by** - Nothing.
+  - **Issue** - None filed.
+  - **Checked** - `develop` at `7f9caaa` on 2026-08-12, where `.gitattributes` carries 25 LF pins (3 forward-declared) over 19 tracked `.py` files, and every one of those 19 is already LF (none is a vanilla CRLF `.py`), so the hub side of this change is comment-and-pattern-only.
+  - **Open** - Whether downstream repos with a vanilla (non-shebang) CRLF `.py` file need a coordinated renormalization pass or can pick it up on their own next resync. 5 repos in [`registry/repos.json`][repos] carry the `python` type (`aiopurpleair`, `homeassistant-purpleair`, `Financial-Modeling`, `PlexCleaner`, `ESPHome-Config`) and were not individually checked for CRLF `.py` content as part of writing this entry.
+  - **Settled** - The default was set to CRLF in #229 for editor compatibility on Windows, not because LF broke anything measured. The reason it is being revisited is that non-VSCode Windows editors were the concern, and the per-path pin list's growth now outweighs that concern's practical weight, per the maintainer.
+  - **Settled** - The by-path convention was reaffirmed in #503 ("Do not re-add a blanket `*.py text eol=lf`"), but that pull request only reshaped the two files' comment prose and did not re-examine the underlying policy, so it is not a second, independent rejection of this change.
+
 ### Giving the Fleet's Own Pins Something to Resolve Against
 
 One pull request pointing a hub `uses:` at a hub-owned action, so that the resolvability pass added beside it has a reference under this owner to read. It is separated from that pass because it changes what a workflow runs, where the pass only changes what a gate reports.
@@ -583,6 +597,7 @@ Nothing is awaiting close today. [#578][issue-578] was the last entry here and c
 [editorconfig]: ./.editorconfig
 [fidelity-honesty]: ./spec/fidelity_honesty.py
 [files]: ./spec/files.json
+[gitattributes]: ./.gitattributes
 [governance]: ./GOVERNANCE.md
 [host-setup-doc]: ./docs/host-setup.md
 [host-setup-windows]: ./host-setup/windows/
diff --git a/scripts/README.md b/scripts/README.md
index 30a3c7f..7803d41 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -4,7 +4,7 @@ The fleet's checks and review tooling, run by hand, with the deterministic ones
 
 **Hosted here and reached, never carried.** These are not declared in [`spec/files.json`][files], so the audit does not expect a downstream repo to ship them, the same footing as `spec/audit.py`. That is the fleet model rather than an omission: a script holding no per-repo content is one copy for the fleet, run from a hub checkout against the repository named on the command line, per [GOVERNANCE.md "Hub-Hosted Tooling"][governance-hub-hosted-tooling]. A repository that cannot reach the hub reports the check as not run rather than reconstructing it, since a rebuilt gate encodes its author's reading of the rule and agrees with no other repository. CI reaches the same rules through the [`prose-gate`][prose-gate-action] composite action, which a caller pins to a commit SHA. It reads the copy bundled at that pin only where the run targets `main`, and takes the rules from hub `develop` on every other target, a feature-branch push included, so a released repo's gate is reproducible while every branch below it exercises a rule change before that change reaches `main`. A caller wanting one specific hub ref passes `rules-ref` and overrides both.
 
-Python only, standard library only, no third-party packages. Every script is read-only and exits non-zero on a finding.
+Python only, standard library only, no third-party packages. Every check script is read-only and exits non-zero on a finding. `build_dist.py` and `skills_install.py` below are the two exceptions, since a generator and an installer both exist to write, and each still offers a read-only mode (`--check`, `--report`) for CI and for asking without changing anything.
 
 Each script has a `test_<script>.py` beside it, driving its gates against input they must reject, because a gate nobody has watched fail is a gate nobody knows works. Where a case covers a table it reads the live table rather than restating it, and each one asserts a floor on what a healthy run reaches, since a check whose scan matches nothing reports zero findings and reads exactly like a pass.
 
@@ -12,7 +12,9 @@ Each script has a `test_<script>.py` beside it, driving its gates against input
 python3 scripts/test_prose_lint.py
 python3 scripts/test_repo_gate.py
 python3 scripts/test_pr_review.py
-python3 -m unittest discover -s scripts          # all three, and exits 5 if the suite vanishes
+python3 scripts/test_build_dist.py
+python3 scripts/test_skills_install.py
+python3 -m unittest discover -s scripts          # all of them, and exits 5 if the suite vanishes
 uvx coverage@latest run --source=. -m unittest discover -s scripts && uvx coverage@latest report
 ```
 
@@ -192,17 +194,33 @@ Undecided is a third answer here for the reason it is one in `repo_gate.py`. A r
 
 The match is on the block's heading rather than anywhere in the body, and on the runbook's alternation rather than on one phrasing, since the wording has already appeared two ways. A case asserts the script's pattern is the one the runbook publishes rather than a copy of it that can drift. Reading the whole body was the first implementation and its own review caught it: a review whose overview prose discusses suppressed findings carries none, and reporting that as a finding trains the reader to skim the field. A heading outside any `<details>` wrapper is still read, because reporting zero when the markup moves is the same false clean one level up, and that fallback takes a count so ordinary prose does not become one.
 
+## `build_dist.py`
+
+Regenerates [`.claude-plugin/fleet-skills/`][fleet-skills-dist] from [`.agents/skills/`][agents-skills], the hub's own hand-authored fleet Skills. Codex and opencode read `.agents/skills/` directly, project-local, with no install step. Claude Code scans neither that path nor any repo-root path by default, only `.claude/skills/` or a plugin's own `skills/`, so this script materializes a Claude-plugin-compatible copy for [`.claude-plugin/marketplace.json`][marketplace] to publish, nested under `.claude-plugin/` rather than a top-level `dist/`, since this repo's `.gitignore` already gives `dist/` a different, Python-build-artifact meaning. `.agents/skills/` stays the one place a skill is hand-edited, and `.claude-plugin/fleet-skills/` is generated and never hand-edited, the same discipline this fleet already applies to other derived trees.
+
+`--check` is the read-only mode: it exits `1` when the generated plugin was built from different source bytes than `.agents/skills/` currently holds, comparing a digest over every source file rather than a file-count or a timestamp, so a same-size edit still registers. CI runs `--check` rather than trusting a contributor to have run the generator, the same reason `spec/audit.py` exists rather than trusting a hand-carried file.
+
+## `skills_install.py`
+
+Installs the fleet's Skills for the current machine, cross-platform and idempotent, mirroring [`host-setup/agent-safety/install.py`][agent-safety-install]'s shape: `skills_install.sh` and `skills_install.ps1` are thin wrappers that locate a Python 3 interpreter and hand off, so every OS runs one tested code path. Two independent things happen on a run, since the three tools this fleet targets discover skills differently: `.agents/skills/` is materialized (not symlinked) to `$HOME/.agents/skills/`, so Codex and opencode's global scan covers every repo on the machine rather than only the one that happens to be open, and this repo's marketplace is registered with the `claude` CLI (`claude plugin marketplace add`, `claude plugin install`) so Claude Code loads the same content the other two read directly. The marketplace/plugin registration goes through the `claude` CLI's own commands rather than writing its internal `known_marketplaces.json` by hand, because that file's shape is the CLI's state, not a documented contract, and a hand-written copy risks drifting from what the CLI expects on its next release.
+
+`--report` reads the stamp a prior run wrote (`$HOME/.agents/skills-install-stamp.json`, naming the hub commit installed) against the current checkout and says whether the machine is current, without installing anything. A repository whose `AGENTS.md` keeps needing a rule restated is usually this: the machine was never installed, or was installed from an older commit.
+
 <!-- Internal -->
 
+[agent-safety-install]: ../host-setup/agent-safety/install.py
+[agents-skills]: ../.agents/skills/README.md
 [audit]: ../spec/audit.py
 [copilot-instructions]: ../.github/copilot-instructions.md
 [editorconfig]: ../.editorconfig
 [files]: ../spec/files.json
+[fleet-skills-dist]: ../.claude-plugin/fleet-skills/
 [gitattributes]: ../.gitattributes
 [governance]: ../GOVERNANCE.md
 [governance-hub-hosted-tooling]: ../GOVERNANCE.md#hub-hosted-tooling
 [host-setup]: ../docs/host-setup.md
 [host-tools]: ../spec/host-tools.json
+[marketplace]: ../.claude-plugin/marketplace.json
 [operations]: ../OPERATIONS.md
 [prose-gate-action]: ../.github/actions/prose-gate/action.yml
 [repos]: ../registry/repos.json
diff --git a/scripts/build_dist.py b/scripts/build_dist.py
new file mode 100755
index 0000000..0ab44aa
--- /dev/null
+++ b/scripts/build_dist.py
@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Generate the Claude-plugin-compatible copy of .agents/skills/ at .claude-plugin/fleet-skills/.
+
+.agents/skills/ is the one hand-authored source: Codex and opencode read it directly with no
+install step. Claude Code never scans that path, only .claude/skills/ or a plugin's own skills/
+directory, so this script materializes a plugin (.claude-plugin/fleet-skills/) that
+.claude-plugin/marketplace.json publishes, keeping .agents/skills/ the single place a skill's
+content is ever hand-edited. Nested under .claude-plugin/ rather than a top-level dist/, since
+this repo's .gitignore already gives dist/ a different, Python-build-artifact meaning.
+
+Usage: python3 scripts/build_dist.py           regenerate the plugin from .agents/skills/
+       python3 scripts/build_dist.py --check   read-only: exit 1 if the plugin is stale
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import shutil
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SKILLS_SRC = ROOT / ".agents" / "skills"
+PLUGIN_NAME = "fleet-skills"
+DIST_PLUGIN = ROOT / ".claude-plugin" / PLUGIN_NAME
+PLUGIN_MANIFEST = DIST_PLUGIN / ".claude-plugin" / "plugin.json"
+DIGEST_STAMP = DIST_PLUGIN / ".source-digest"
+
+
+def skill_names():
+    """Every .agents/skills/<name>/ directory that carries a SKILL.md, sorted for a stable digest."""
+    if not SKILLS_SRC.is_dir():
+        return []
+    return sorted(p.name for p in SKILLS_SRC.iterdir() if (p / "SKILL.md").is_file())
+
+
+def reject_symlinks(skill_dir):
+    """Raise if `skill_dir` itself, or anything in its tree, is a symlink.
+
+    .agents/skills/ is the one hand-authored source, with no legitimate reason to hold a symlink.
+    Path.is_file() and read_bytes() both dereference one, and so does shutil.copytree() by
+    default, so an unnoticed symlink there would let the digest and the generated plugin silently
+    include content from outside this tree, tracked or not. `skill_dir` itself needs its own
+    check: rglob("*") only yields paths *inside* the directory it walks, so a skill directory that
+    is itself a symlink to another tree would walk straight into that tree without the walk ever
+    seeing (or flagging) the root symlink node.
+    """
+    if skill_dir.is_symlink():
+        raise ValueError(f"{skill_dir} is a symlink; .agents/skills/ must contain only real files")
+    for p in skill_dir.rglob("*"):
+        if p.is_symlink():
+            raise ValueError(f"{p} is a symlink; .agents/skills/ must contain only real files")
+
+
+def tree_digest(root, names):
+    """One digest over every file under `root/<name>` for each name, order-independent per skill.
+
+    Rooted at an arbitrary directory rather than hardcoding SKILLS_SRC, so the same function
+    hashes both the source tree and the generated tree, and is_stale() can compare the two
+    directly instead of trusting a stored digest to still describe what was actually generated.
+
+    Names are hashed in the fixed sorted order the caller already produced. Each skill's own files
+    are hashed in a second stable sort so an unrelated filesystem listing order never changes the
+    digest on a machine where nothing changed.
+    """
+    h = hashlib.sha256()
+    for name in names:
+        skill_dir = root / name
+        reject_symlinks(skill_dir)
+        h.update(name.encode("utf-8"))
+        # Sorted by the same .as_posix() key that gets hashed, not by raw Path comparison.
+        # Path ordering follows the platform's native separator.
+        # Two OSes can sort an identical file set into a different order and hash it into a different digest, even though the bytes hashed per file already agree via .as_posix() below.
+        files = sorted((f for f in skill_dir.rglob("*") if f.is_file()),
+                        key=lambda f: f.relative_to(root).as_posix())
+        for f in files:
+            h.update(f.relative_to(root).as_posix().encode("utf-8"))
+            h.update(f.read_bytes())
+    return h.hexdigest()[:16]
+
+
+def source_digest(names):
+    return tree_digest(SKILLS_SRC, names)
+
+
+def expected_manifest(names):
+    """The plugin.json content `names` should produce, entirely deterministic.
+
+    The one source is_stale() compares the actual manifest against, so a hand-edited field of
+    any kind (not only "skills") is caught the same way a hand-edited "skills" list already was.
+    """
+    return {
+        "name": PLUGIN_NAME,
+        "version": "0.0.0",
+        "description": "Fleet-wide agent rules (comment style, PR-review conduct, resync safety) "
+        "packaged as Claude Code Skills, generated from .agents/skills/.",
+        "author": {"name": "ptr727"},
+        "skills": [f"./skills/{name}" for name in names],
+    }
+
+
+def write_plugin_manifest(names):
+    PLUGIN_MANIFEST.parent.mkdir(parents=True, exist_ok=True)
+    manifest = expected_manifest(names)
+    # CRLF, matching this repo's JSON default (.editorconfig `[*] end_of_line = crlf`).
+    # No LF pin applies here, since this is not a shebang-executed or shell-consumed path.
+    PLUGIN_MANIFEST.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8", newline="\r\n")
+
+
+def regenerate():
+    names = skill_names()
+    if DIST_PLUGIN.is_symlink() or DIST_PLUGIN.is_file():
+        DIST_PLUGIN.unlink()
+    elif DIST_PLUGIN.is_dir():
+        shutil.rmtree(DIST_PLUGIN)
+    dist_skills = DIST_PLUGIN / "skills"
+    dist_skills.mkdir(parents=True, exist_ok=True)
+    for name in names:
+        reject_symlinks(SKILLS_SRC / name)
+        shutil.copytree(SKILLS_SRC / name, dist_skills / name)
+    write_plugin_manifest(names)
+    # CRLF, same as write_plugin_manifest.
+    # The platform default would write plain LF on Linux.
+    # That disagrees with this repo's CRLF default for a path no LF pin covers.
+    DIGEST_STAMP.write_text(source_digest(names) + "\n", encoding="utf-8", newline="\r\n")
+    return names
+
+
+def is_stale():
+    """Whether the generated plugin needs regenerating: missing, corrupted, or built from
+    different source bytes. Checks the manifest's own content and the generated tree's actual
+    bytes, not only the digest stamp, since a stamp surviving a partial deletion, a hand-edited
+    manifest, or an edited-in-place generated file would otherwise report current over a plugin
+    that no longer actually matches its source. Comparing the source and generated digests
+    directly, rather than trusting the stamp to still describe what is on disk, is what catches
+    the in-place edit: nothing else here re-reads the generated files at all.
+    """
+    if not DIGEST_STAMP.is_file() or not PLUGIN_MANIFEST.is_file():
+        return True
+    names = skill_names()
+    try:
+        manifest = json.loads(PLUGIN_MANIFEST.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return True
+    # The full manifest, not only "skills".
+    # A hand-edited description/author/version is exactly as much a corrupted-plugin case as a hand-edited skills list.
+    # The manifest is entirely deterministic from `names`, so comparing all of it costs nothing extra to get right.
+    if manifest != expected_manifest(names):
+        return True
+    # The digest walk below only hashes the expected names.
+    # An extra directory under DIST_PLUGIN/skills/ (a retired skill left behind, one added by hand) would never be read and could not affect that comparison.
+    # Checked by name first, deliberately not folded into the digest walk itself.
+    dist_skills = DIST_PLUGIN / "skills"
+    actual_names = {p.name for p in dist_skills.iterdir() if p.is_dir()} if dist_skills.is_dir() else set()
+    if actual_names != set(names):
+        return True
+    current_source_digest = source_digest(names)
+    if DIGEST_STAMP.read_text(encoding="utf-8").strip() != current_source_digest:
+        return True
+    return current_source_digest != tree_digest(dist_skills, names)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="read-only: exit 1 if the generated plugin is stale")
+    args = parser.parse_args()
+
+    if args.check:
+        try:
+            stale = is_stale()
+        except ValueError as exc:
+            print(exc, file=sys.stderr)
+            return 1
+        if stale:
+            print(f"{DIST_PLUGIN} is stale: run `python3 scripts/build_dist.py`.", file=sys.stderr)
+            return 1
+        print(f"{DIST_PLUGIN} is current.")
+        return 0
+
+    try:
+        names = regenerate()
+    except ValueError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    print(f"{DIST_PLUGIN} regenerated from {len(names)} skill(s): {', '.join(names) or '(none)'}.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/skills_install.ps1 b/scripts/skills_install.ps1
new file mode 100644
index 0000000..73836c2
--- /dev/null
+++ b/scripts/skills_install.ps1
@@ -0,0 +1,47 @@
+# Thin wrapper: run the cross-platform installer with a Python 3.7+ (Windows).
+# All logic lives in skills_install.py so every OS runs one tested code path.
+# It is idempotent and safe to re-run.
+#   Run: scripts\skills_install.ps1
+#   Or: $env:AGENTS_HOME = "C:\path"; scripts\skills_install.ps1   # override the target (testing)
+$ErrorActionPreference = "Stop"
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path
+$script = Join-Path $here "skills_install.py"
+
+# Try each candidate in order, version-checking it before committing to it.
+# None of these launchers guarantees 3.7+ by construction.
+# `py -3` and `python3` can both resolve to an old 3.6 interpreter on some systems.
+# Picking the first *available* launcher and checking only that one would fail the whole install on a machine where an earlier candidate is stale but a later one is fine.
+$candidates = @(
+    @{ Exe = "py"; Args = @("-3") },
+    @{ Exe = "python3"; Args = @() },
+    @{ Exe = "python"; Args = @() }
+)
+
+$pyExe = $null
+$pyArgs = @()
+foreach ($c in $candidates) {
+    if (-not (Get-Command $c.Exe -ErrorAction SilentlyContinue)) {
+        continue
+    }
+    # The installer uses `from __future__ import annotations`, which needs 3.7+.
+    # A bare `python` may be Python 2 on some systems.
+    & $c.Exe @($c.Args) -c "import sys; sys.exit(0 if sys.version_info >= (3, 7) else 1)" 2>$null
+    if ($LASTEXITCODE -eq 0) {
+        $pyExe = $c.Exe
+        $pyArgs = $c.Args
+        break
+    }
+}
+
+if (-not $pyExe) {
+    Write-Error "Python 3.7+ is required and was not found on PATH (tried py -3, python3, python)."
+    exit 1
+}
+
+# $pyArgs is splatted rather than sliced from a combined array.
+# PowerShell's `1..0` range operator returns a descending @(1, 0) rather than empty.
+# That would corrupt a single-element launcher's argument list.
+& $pyExe @pyArgs $script @args
+
+# Propagate the installer's exit code - a native command's non-zero exit does not stop the script.
+exit $LASTEXITCODE
diff --git a/scripts/skills_install.py b/scripts/skills_install.py
new file mode 100755
index 0000000..b9dc6ee
--- /dev/null
+++ b/scripts/skills_install.py
@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""Install the fleet's Skills for the current user account. Cross-platform, idempotent.
+
+Two independent things happen, since Claude Code, opencode, and Codex CLI discover skills
+differently (see AGENTS.md "Fleet Bootstrap" for why):
+
+  - Codex and opencode read .agents/skills/<name>/SKILL.md directly, project-local, walking up
+    from the working directory. They also check a global $HOME/.agents/skills/, which this
+    installer materializes so every repo on this machine benefits, not only this checkout.
+  - Claude Code never scans .agents/skills/, only .claude/skills/ or a plugin's own skills/. This
+    installer registers this repo's marketplace (built at .claude-plugin/fleet-skills/, see
+    build_dist.py) and installs its plugin via the `claude` CLI, so Claude Code loads the same
+    content the other two tools read directly.
+
+Both wrappers (skills_install.sh, skills_install.ps1) call this, so every OS runs one tested code path.
+
+Every run records a stamp at ~/.agents/skills-install-stamp.json naming the machine, what was
+installed, and the hub commit it came from, so staleness is checkable later without re-running the
+install. `--report` reads that stamp against this checkout and answers whether the machine is
+current, without changing anything.
+
+Usage: python3 scripts/skills_install.py            (installs)
+       python3 scripts/skills_install.py --report   (read-only: is this machine current?)
+       AGENTS_HOME=/x python3 scripts/skills_install.py   (override the global skills target, for testing)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+from pathlib import Path
+
+import build_dist
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parent
+SKILLS_SRC = ROOT / ".agents" / "skills"
+CLAUDE_PLUGIN_DIR = ROOT / ".claude-plugin"
+MARKETPLACE_NAME = "projecttemplate-fleet"
+PLUGIN_NAME = "fleet-skills"
+STAMP_VERSION = 1
+
+
+def agents_home():
+    """Where Codex/opencode look for globally-installed skills, overridable for testing."""
+    override = os.environ.get("AGENTS_HOME")
+    # .expanduser(): AGENTS_HOME=~/tmp is a real thing a caller would type.
+    # A bare Path() treats "~" as a literal directory name, not the shell-expanded home it looks like.
+    return Path(override).expanduser() if override else Path.home() / ".agents"
+
+
+def source_ref():
+    """The hub commit this installer is running from, and whether the tree is dirty."""
+    def git(*args):
+        try:
+            r = subprocess.run(["git", "-C", str(ROOT), *args], capture_output=True, text=True)
+        except OSError:
+            return None
+        return r.stdout.strip() if r.returncode == 0 else None
+
+    sha = git("rev-parse", "HEAD")
+    if not sha:
+        return {"vcs": "none"}
+    ref = {"vcs": "git", "commit": sha}
+    # Watches both paths this installer actually reads.
+    # .agents/skills/ is copied for Codex/opencode.
+    # .claude-plugin/ is the marketplace.json and generated plugin Claude Code reads.
+    # Scoping dirty to only the first missed a modified marketplace.json or generated content.
+    # Repo-relative pathspecs, not str(Path).
+    # With `git -C <repo>`, an absolute path can fail to match anything.
+    # That silently and permanently reports dirty=False.
+    watched = [SKILLS_SRC, CLAUDE_PLUGIN_DIR]
+    status = git("status", "--porcelain", "--", *(p.relative_to(ROOT).as_posix() for p in watched))
+    ref["dirty"] = bool(status)
+    return ref
+
+
+INSTALLED_MARKER = ".installed-by-projecttemplate-fleet"
+
+
+def skill_source_dirs():
+    """Every .agents/skills/<name>/ directory that actually carries a SKILL.md.
+
+    Matches build_dist.skill_names()'s own definition of a skill, so a stray non-skill directory
+    under .agents/skills/ (a cache folder, a scratch dir) is never treated as one here either.
+    """
+    if not SKILLS_SRC.is_dir():
+        return []
+    return [p for p in SKILLS_SRC.iterdir() if (p / "SKILL.md").is_file()]
+
+
+def materialize_global_skills(target):
+    """Overlay .agents/skills/ into `target`, one skill directory at a time.
+
+    Only this fleet's own skill names are touched under `target`. `~/.agents/skills/` is a shared
+    convention, not this fleet's own directory, so a machine can have skills installed there from
+    other sources, and replacing the whole directory would delete those as a side effect of
+    installing this fleet's skills. A plain copy rather than a symlink per skill: a symlink to a
+    checkout that later moves or is deleted leaves every repo on the machine silently unable to
+    resolve that skill, where a copy just goes stale (caught by --report) instead of missing
+    outright.
+
+    Raises ValueError (via build_dist.reject_symlinks) if a skill directory contains a symlink,
+    since shutil.copytree() follows one by default and would silently pull in content from
+    outside the tracked source tree.
+
+    Each installed skill carries an INSTALLED_MARKER file, so a later run can tell "a fleet skill
+    that got retired" apart from "someone else's skill that happens to share this directory."
+    Only a directory carrying the marker is ever removed for no longer being in the current
+    source set; a directory without one is never touched, retired-looking name or not.
+    """
+    if target.is_symlink() or target.is_file():
+        target.unlink()
+    target.mkdir(parents=True, exist_ok=True)
+    skill_dirs = skill_source_dirs()
+    current_names = {p.name for p in skill_dirs}
+
+    for existing in target.iterdir():
+        # A plain is_dir() check follows a symlink.
+        # Calling shutil.rmtree() on one refuses with an uncaught OSError instead of deleting through it.
+        # Confirmed locally rather than assumed.
+        # Skipping a symlink here avoids that crash on a stray one under the shared target.
+        if (not existing.is_symlink() and existing.is_dir()
+                and existing.name not in current_names and (existing / INSTALLED_MARKER).is_file()):
+            shutil.rmtree(existing)
+
+    for skill_dir in skill_dirs:
+        build_dist.reject_symlinks(skill_dir)
+        dest = target / skill_dir.name
+        if dest.is_symlink() or dest.is_file():
+            dest.unlink()
+        elif dest.is_dir():
+            shutil.rmtree(dest)
+        shutil.copytree(skill_dir, dest)
+        (dest / INSTALLED_MARKER).write_text("", encoding="utf-8")
+
+
+def claude_available():
+    return shutil.which("claude") is not None
+
+
+def register_claude_marketplace():
+    """Add this repo's marketplace and install its plugin via the `claude` CLI.
+
+    Shells out to `claude plugin marketplace add`/`install` rather than writing
+    ~/.claude/plugins/known_marketplaces.json directly: that file's shape is the CLI's own
+    internal state, not a documented contract, so writing it by hand risks silently drifting from
+    whatever the CLI actually expects on the next release.
+    """
+    marketplace_add = subprocess.run(
+        ["claude", "plugin", "marketplace", "add", str(ROOT)],
+        capture_output=True, text=True,
+    )
+    # Re-adding an already-registered marketplace is expected on a re-run.
+    # Only a genuine failure (not "already exists") is fatal, since idempotence is the point.
+    if (marketplace_add.returncode != 0
+            and "already" not in marketplace_add.stdout.lower()
+            and "already" not in marketplace_add.stderr.lower()):
+        print(marketplace_add.stdout, marketplace_add.stderr, file=sys.stderr)
+        return False
+
+    install = subprocess.run(
+        ["claude", "plugin", "install", f"{PLUGIN_NAME}@{MARKETPLACE_NAME}", "--scope", "user"],
+        capture_output=True, text=True,
+    )
+    if (install.returncode != 0
+            and "already" not in install.stdout.lower()
+            and "already" not in install.stderr.lower()):
+        print(install.stdout, install.stderr, file=sys.stderr)
+        return False
+    return True
+
+
+def build_stamp(claude_registered):
+    return {
+        "stampVersion": STAMP_VERSION,
+        "hostname": socket.gethostname(),
+        "source": source_ref(),
+        "claudeRegistered": claude_registered,
+    }
+
+
+def report(stamp_path):
+    if not stamp_path.is_file():
+        print("Not installed on this machine (no stamp found).")
+        return 1
+    try:
+        stamp = json.loads(stamp_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"Stamp at {stamp_path} is unreadable ({exc}). Re-run the installer.")
+        return 1
+    # A non-dict JSON value (an array, a bare string) is a shape this reader does not know.
+    # So is an unrecognized stampVersion, not merely a plain missing/dirty install.
+    if not isinstance(stamp, dict) or stamp.get("stampVersion") != STAMP_VERSION:
+        print(f"Stamp at {stamp_path} is not a recognized shape (stampVersion {STAMP_VERSION} expected). "
+              "Re-run the installer.")
+        return 1
+    current = source_ref()
+    current_commit = current.get("commit")
+    # A dict-shaped stamp can still carry a non-dict "source" (a stray string, a number).
+    # Calling .get("commit") on that would crash instead of reading as stale like every other unrecognized-shape case here does.
+    stamp_source = stamp.get("source")
+    stamp_commit = stamp_source.get("commit") if isinstance(stamp_source, dict) else None
+    stamp_dirty = stamp_source.get("dirty") if isinstance(stamp_source, dict) else None
+    # A dirty checkout cannot be asserted current.
+    # The commit it names is not what is actually on disk.
+    # A caller trusting "current" here would trust bytes that were never installed.
+    # Checked on both sides.
+    # The current checkout's own dirty flag catches a machine that has since gone dirty at the recorded commit.
+    # The stamp's recorded dirty flag catches the install itself having happened from a dirty checkout, whose bytes a later-clean tree at the same commit can never actually reproduce or verify.
+    # Wrapped in bool() rather than left as a bare "or" chain.
+    # A missing current_commit (a non-git checkout) reads as stale this way.
+    # A plain "or" chain would leave `stale` as the None that produces there instead, and `if stale else` treats that as falsy the same as an actual False.
+    # A missing "dirty" key by itself reads as not-dirty, since get() returns None there, which is falsy.
+    # That is not the same as reading as stale.
+    # A call to source_ref() always sets "dirty" whenever it sets "commit", so the two are missing together only in the vcs=="none" case, which current_commit is None already catches.
+    stale = bool(
+        current_commit is None
+        or stamp_commit != current_commit
+        or current.get("dirty")
+        or stamp_dirty
+    )
+    print(json.dumps({"stamp": stamp, "currentCommit": current_commit, "stale": stale}, indent=2))
+    return 1 if stale else 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--report", action="store_true", help="read-only: is this machine current?")
+    args = parser.parse_args()
+
+    home = agents_home()
+    stamp_path = home / "skills-install-stamp.json"
+
+    if args.report:
+        return report(stamp_path)
+
+    try:
+        materialize_global_skills(home / "skills")
+    except ValueError as exc:
+        print(exc, file=sys.stderr)
+        return 1
+
+    claude_present = claude_available()
+    claude_registered = register_claude_marketplace() if claude_present else False
+    if not claude_present:
+        print("`claude` not found on PATH, skipping Claude Code marketplace registration "
+              "(Codex/opencode global skills were still installed).", file=sys.stderr)
+
+    home.mkdir(parents=True, exist_ok=True)
+    stamp_path.write_text(json.dumps(build_stamp(claude_registered), indent=2) + "\n", encoding="utf-8")
+    print(f"Installed to {home / 'skills'}. Claude Code marketplace registered: {claude_registered}.")
+
+    # `claude` missing is a partial-but-expected install (a Codex/opencode-only machine).
+    # `claude` present but registration failing is a real failure.
+    # The stamp still records it either way, but only the exit code lets automation notice.
+    if claude_present and not claude_registered:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/skills_install.sh b/scripts/skills_install.sh
new file mode 100755
index 0000000..c499eb6
--- /dev/null
+++ b/scripts/skills_install.sh
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Thin wrapper: run the cross-platform installer with a Python 3 (Linux / WSL / macOS).
+# All logic lives in skills_install.py so every OS runs one tested code path.
+# It is idempotent and safe to re-run.
+#   Run: scripts/skills_install.sh              installs the fleet skills for this user
+#   Or: AGENTS_HOME=/x scripts/skills_install.sh   overrides the target (testing)
+set -Eeuo pipefail
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Pick the first candidate that is actually Python 3.7+.
+# The installer uses `from __future__ import annotations`, which needs 3.7+, so a 3.6 or a
+# Python-2 `python` is rejected rather than handed the script, which would fail to parse.
+py=""
+for c in python3 python; do
+  if command -v "$c" >/dev/null 2>&1 && "$c" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 7) else 1)' 2>/dev/null; then
+    py="$c"; break
+  fi
+done
+[ -n "$py" ] || { echo "Python 3.7+ is required and was not found on PATH (tried python3, python)." >&2; exit 1; }
+
+exec "$py" "$here/skills_install.py" "$@"
diff --git a/scripts/test_build_dist.py b/scripts/test_build_dist.py
new file mode 100755
index 0000000..c26cce4
--- /dev/null
+++ b/scripts/test_build_dist.py
@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""Exercise build_dist.py's regeneration and staleness detection against a crafted skills tree.
+
+Run as `python3 scripts/test_build_dist.py`, or under `python3 -m unittest discover -s scripts`.
+"""
+from __future__ import annotations
+
+import json
+import unittest
+from pathlib import Path
+
+import build_dist
+
+
+class RegenerateCase(unittest.TestCase):
+    """Redirects every module path onto a temp tree so a case never touches this repo's own."""
+
+    def setUp(self) -> None:
+        self.tmp = Path(self.enterContext(__import__("tempfile").TemporaryDirectory()))
+        self.skills_src = self.tmp / ".agents" / "skills"
+        self.dist_plugin = self.tmp / ".claude-plugin" / "fleet-skills"
+        self.addCleanup(self._restore, build_dist.SKILLS_SRC, build_dist.DIST_PLUGIN,
+                         build_dist.PLUGIN_MANIFEST, build_dist.DIGEST_STAMP)
+        build_dist.SKILLS_SRC = self.skills_src
+        build_dist.DIST_PLUGIN = self.dist_plugin
+        build_dist.PLUGIN_MANIFEST = self.dist_plugin / ".claude-plugin" / "plugin.json"
+        build_dist.DIGEST_STAMP = self.dist_plugin / ".source-digest"
+
+    def _restore(self, src, dist, manifest, stamp) -> None:
+        build_dist.SKILLS_SRC = src
+        build_dist.DIST_PLUGIN = dist
+        build_dist.PLUGIN_MANIFEST = manifest
+        build_dist.DIGEST_STAMP = stamp
+
+    def make_skill(self, name: str, body: str = "content") -> None:
+        d = self.skills_src / name
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "SKILL.md").write_text(body, encoding="utf-8")
+
+    def test_a_symlink_in_a_skill_directory_is_rejected_by_regenerate(self) -> None:
+        """shutil.copytree() follows a symlink by default, which would silently pull content
+        from outside .agents/skills/ into the generated, published plugin."""
+        self.make_skill("foo")
+        (self.skills_src / "foo" / "escape").symlink_to(self.tmp)
+        with self.assertRaises(ValueError):
+            build_dist.regenerate()
+
+    def test_a_symlink_in_a_skill_directory_is_rejected_by_source_digest(self) -> None:
+        self.make_skill("foo")
+        (self.skills_src / "foo" / "escape").symlink_to(self.tmp)
+        with self.assertRaises(ValueError):
+            build_dist.source_digest(["foo"])
+
+    def test_a_skill_directory_that_is_itself_a_symlink_is_rejected(self) -> None:
+        """rglob("*") only yields paths inside the directory it walks, so a skill directory that
+        is itself a symlink to another tree would otherwise walk straight into that tree without
+        the walk ever seeing the root symlink node."""
+        outside = self.tmp / "outside-the-repo"
+        outside.mkdir()
+        (outside / "SKILL.md").write_text("not tracked here", encoding="utf-8")
+        self.skills_src.mkdir(parents=True, exist_ok=True)
+        (self.skills_src / "foo").symlink_to(outside)
+        with self.assertRaises(ValueError):
+            build_dist.source_digest(["foo"])
+
+    def test_no_skills_still_produces_a_valid_manifest(self) -> None:
+        names = build_dist.regenerate()
+        self.assertEqual(names, [])
+        manifest = json.loads(build_dist.PLUGIN_MANIFEST.read_text(encoding="utf-8"))
+        self.assertEqual(manifest["skills"], [])
+        self.assertFalse(build_dist.is_stale())
+
+    def test_a_skill_directory_without_skill_md_is_not_discovered(self) -> None:
+        (self.skills_src / "half-written").mkdir(parents=True)
+        (self.skills_src / "half-written" / "notes.txt").write_text("wip", encoding="utf-8")
+        self.assertEqual(build_dist.skill_names(), [])
+
+    def test_digest_stamp_ends_with_a_final_crlf(self) -> None:
+        """Read as bytes, not text: a text-mode read applies universal-newline translation and
+        would report a plain LF ending as "\\n" too, hiding exactly the platform-default-newline
+        bug this asserts against."""
+        self.make_skill("foo")
+        build_dist.regenerate()
+        self.assertTrue(build_dist.DIGEST_STAMP.read_bytes().endswith(b"\r\n"))
+
+    def test_regenerate_copies_skill_content_and_lists_it_in_the_manifest(self) -> None:
+        self.make_skill("foo")
+        self.make_skill("bar")
+        names = build_dist.regenerate()
+        self.assertEqual(names, ["bar", "foo"])
+        manifest = json.loads(build_dist.PLUGIN_MANIFEST.read_text(encoding="utf-8"))
+        self.assertEqual(manifest["skills"], ["./skills/bar", "./skills/foo"])
+        self.assertEqual((self.dist_plugin / "skills" / "foo" / "SKILL.md").read_text(encoding="utf-8"), "content")
+        self.assertFalse(build_dist.is_stale())
+
+    def test_a_deleted_manifest_reports_stale_even_with_a_current_digest_stamp(self) -> None:
+        self.make_skill("foo")
+        build_dist.regenerate()
+        build_dist.PLUGIN_MANIFEST.unlink()
+        self.assertTrue(build_dist.is_stale())
+
+    def test_a_hand_edited_non_skills_manifest_field_reports_stale(self) -> None:
+        """Only the "skills" field was compared before; a hand-edited description, author, or
+        version slipped through undetected. The manifest is entirely deterministic from `names`,
+        so comparing all of it is both correct and free."""
+        self.make_skill("foo")
+        build_dist.regenerate()
+        manifest = json.loads(build_dist.PLUGIN_MANIFEST.read_text(encoding="utf-8"))
+        manifest["description"] = "hand-edited, not what build_dist.py would generate"
+        build_dist.PLUGIN_MANIFEST.write_text(json.dumps(manifest), encoding="utf-8")
+        self.assertTrue(build_dist.is_stale())
+
+    def test_a_deleted_generated_skill_reports_stale_even_with_a_current_digest_stamp(self) -> None:
+        self.make_skill("foo")
+        build_dist.regenerate()
+        import shutil
+        shutil.rmtree(self.dist_plugin / "skills" / "foo")
+        self.assertTrue(build_dist.is_stale())
+
+    def test_a_generated_file_edited_in_place_reports_stale(self) -> None:
+        """.source-digest, the manifest, and SKILL.md's mere presence can all stay untouched
+        while a generated file's actual content is edited or a non-SKILL.md file (a bundled
+        scripts/ or references/ file) is deleted. Only comparing the generated tree's own digest
+        against the source's catches this, since nothing else here re-reads the generated bytes."""
+        self.make_skill("foo")
+        (self.skills_src / "foo" / "references").mkdir()
+        (self.skills_src / "foo" / "references" / "notes.md").write_text("v1", encoding="utf-8")
+        build_dist.regenerate()
+        (self.dist_plugin / "skills" / "foo" / "references" / "notes.md").write_text(
+            "tampered", encoding="utf-8"
+        )
+        self.assertTrue(build_dist.is_stale())
+
+    def test_a_generated_extra_file_deleted_reports_stale(self) -> None:
+        self.make_skill("foo")
+        (self.skills_src / "foo" / "references").mkdir()
+        (self.skills_src / "foo" / "references" / "notes.md").write_text("v1", encoding="utf-8")
+        build_dist.regenerate()
+        (self.dist_plugin / "skills" / "foo" / "references" / "notes.md").unlink()
+        self.assertTrue(build_dist.is_stale())
+
+    def test_an_orphaned_generated_skill_directory_reports_stale(self) -> None:
+        """tree_digest() only hashes the expected `names`, so an extra directory under
+        DIST_PLUGIN/skills/ (a retired skill left behind, one added by hand) would never be
+        read and could not affect a pure digest comparison. Checked by name explicitly."""
+        self.make_skill("foo")
+        build_dist.regenerate()
+        (self.dist_plugin / "skills" / "orphan").mkdir()
+        (self.dist_plugin / "skills" / "orphan" / "SKILL.md").write_text("stray", encoding="utf-8")
+        self.assertTrue(build_dist.is_stale())
+
+    def test_editing_a_skill_after_regenerate_reports_stale(self) -> None:
+        self.make_skill("foo")
+        build_dist.regenerate()
+        (self.skills_src / "foo" / "SKILL.md").write_text("changed", encoding="utf-8")
+        self.assertTrue(build_dist.is_stale())
+
+    def test_adding_a_skill_after_regenerate_reports_stale(self) -> None:
+        self.make_skill("foo")
+        build_dist.regenerate()
+        self.make_skill("bar")
+        self.assertTrue(build_dist.is_stale())
+
+    def test_a_missing_dist_tree_is_stale(self) -> None:
+        self.make_skill("foo")
+        self.assertTrue(build_dist.is_stale())
+
+    def test_digest_uses_forward_slashes_regardless_of_platform(self) -> None:
+        """A digest built from str(Path) would use backslashes on Windows and disagree with a
+        Linux machine over identical bytes. Reproduce the expected posix-joined hash by hand and
+        confirm it matches, which would fail if source_digest regressed to str(Path)."""
+        self.make_skill("foo")
+        (self.skills_src / "foo" / "scripts").mkdir()
+        (self.skills_src / "foo" / "scripts" / "run.py").write_text("x", encoding="utf-8")
+
+        import hashlib
+        expected = hashlib.sha256()
+        expected.update(b"foo")
+        expected.update(b"foo/SKILL.md")
+        expected.update(b"content")
+        expected.update(b"foo/scripts/run.py")
+        expected.update(b"x")
+        self.assertEqual(build_dist.source_digest(["foo"]), expected.hexdigest()[:16])
+
+    def test_removing_a_skill_after_regenerate_no_longer_carries_it(self) -> None:
+        self.make_skill("foo")
+        self.make_skill("bar")
+        build_dist.regenerate()
+        import shutil
+        shutil.rmtree(self.skills_src / "bar")
+        names = build_dist.regenerate()
+        self.assertEqual(names, ["foo"])
+        self.assertFalse((self.dist_plugin / "skills" / "bar").exists())
+
+    def test_main_reports_a_symlink_cleanly_instead_of_a_raw_traceback(self) -> None:
+        self.make_skill("foo")
+        (self.skills_src / "foo" / "escape").symlink_to(self.tmp)
+        from unittest import mock
+        with mock.patch("sys.argv", ["build_dist.py"]), mock.patch("builtins.print"):
+            exit_code = build_dist.main()
+        self.assertEqual(exit_code, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/scripts/test_skills_install.py b/scripts/test_skills_install.py
new file mode 100755
index 0000000..e52d2a9
--- /dev/null
+++ b/scripts/test_skills_install.py
@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""Exercise skills_install.py's materialization and staleness reporting, without touching the
+real `claude` CLI state or the real ~/.agents directory.
+
+Run as `python3 scripts/test_skills_install.py`, or under `python3 -m unittest discover -s scripts`.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import skills_install
+
+
+class AgentsHomeCase(unittest.TestCase):
+    def test_a_tilde_override_expands_to_the_real_home_directory(self) -> None:
+        """AGENTS_HOME=~/tmp is a real thing a caller would type. A bare Path() treats "~" as a
+        literal directory name rather than the shell-expanded home it looks like."""
+        with mock.patch.dict("os.environ", {"AGENTS_HOME": "~/agents-test"}):
+            home = skills_install.agents_home()
+        self.assertNotIn("~", str(home))
+        self.assertEqual(home, Path.home() / "agents-test")
+
+
+class SourceRefCase(unittest.TestCase):
+    """source_ref()'s dirty check must watch every path this installer actually reads from,
+    not only .agents/skills/, or a modified marketplace.json/generated plugin would report
+    dirty=False over bytes that were never installed."""
+
+    def test_git_status_is_scoped_to_both_watched_paths(self) -> None:
+        calls = []
+
+        def fake_run(args, **kwargs):
+            calls.append(args)
+            result = mock.Mock()
+            result.returncode = 0
+            result.stdout = "deadbeef\n" if "rev-parse" in args else ""
+            return result
+
+        with mock.patch("subprocess.run", side_effect=fake_run):
+            skills_install.source_ref()
+
+        status_call = next(c for c in calls if "status" in c)
+        self.assertIn(str(skills_install.SKILLS_SRC.relative_to(skills_install.ROOT).as_posix()), status_call)
+        self.assertIn(
+            str(skills_install.CLAUDE_PLUGIN_DIR.relative_to(skills_install.ROOT).as_posix()), status_call
+        )
+
+
+class MaterializeCase(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = Path(self.enterContext(tempfile.TemporaryDirectory()))
+        self.src = self.tmp / "src"
+        self.addCleanup(self._restore, skills_install.SKILLS_SRC)
+        skills_install.SKILLS_SRC = self.src
+
+    def _restore(self, src) -> None:
+        skills_install.SKILLS_SRC = src
+
+    def test_materializing_with_no_source_creates_an_empty_target(self) -> None:
+        target = self.tmp / "target"
+        skills_install.materialize_global_skills(target)
+        self.assertTrue(target.is_dir())
+        self.assertEqual(list(target.iterdir()), [])
+
+    def test_materializing_when_the_target_parent_does_not_exist_yet(self) -> None:
+        (self.src / "foo").mkdir(parents=True)
+        (self.src / "foo" / "SKILL.md").write_text("x", encoding="utf-8")
+        target = self.tmp / "not-yet-created" / "skills"
+        skills_install.materialize_global_skills(target)
+        self.assertEqual((target / "foo" / "SKILL.md").read_text(encoding="utf-8"), "x")
+
+    def test_materializing_over_a_stray_file_at_the_target_path(self) -> None:
+        target = self.tmp / "target"
+        target.write_text("not a directory", encoding="utf-8")
+        skills_install.materialize_global_skills(target)
+        self.assertTrue(target.is_dir())
+
+    def test_materializing_copies_the_source_tree(self) -> None:
+        (self.src / "foo").mkdir(parents=True)
+        (self.src / "foo" / "SKILL.md").write_text("x", encoding="utf-8")
+        target = self.tmp / "target"
+        skills_install.materialize_global_skills(target)
+        self.assertEqual((target / "foo" / "SKILL.md").read_text(encoding="utf-8"), "x")
+
+    def test_re_materializing_replaces_stale_content(self) -> None:
+        (self.src / "foo").mkdir(parents=True)
+        (self.src / "foo" / "SKILL.md").write_text("v1", encoding="utf-8")
+        target = self.tmp / "target"
+        skills_install.materialize_global_skills(target)
+        (self.src / "foo" / "SKILL.md").write_text("v2", encoding="utf-8")
+        skills_install.materialize_global_skills(target)
+        self.assertEqual((target / "foo" / "SKILL.md").read_text(encoding="utf-8"), "v2")
+
+    def test_a_skill_from_another_source_already_in_target_is_left_alone(self) -> None:
+        """~/.agents/skills/ is a shared convention, not this fleet's own directory. Installing
+        this fleet's skills must never delete a skill some other tool or fleet put there."""
+        (self.src / "foo").mkdir(parents=True)
+        (self.src / "foo" / "SKILL.md").write_text("fleet content", encoding="utf-8")
+        target = self.tmp / "target"
+        target.mkdir(parents=True)
+        (target / "someone-elses-skill").mkdir()
+        (target / "someone-elses-skill" / "SKILL.md").write_text("not ours", encoding="utf-8")
+
+        skills_install.materialize_global_skills(target)
+
+        self.assertEqual((target / "foo" / "SKILL.md").read_text(encoding="utf-8"), "fleet content")
+        self.assertEqual(
+            (target / "someone-elses-skill" / "SKILL.md").read_text(encoding="utf-8"), "not ours"
+        )
+
+    def test_a_retired_fleet_skill_is_removed_on_the_next_install(self) -> None:
+        (self.src / "foo").mkdir(parents=True)
+        (self.src / "foo" / "SKILL.md").write_text("x", encoding="utf-8")
+        (self.src / "bar").mkdir(parents=True)
+        (self.src / "bar" / "SKILL.md").write_text("x", encoding="utf-8")
+        target = self.tmp / "target"
+        skills_install.materialize_global_skills(target)
+        self.assertTrue((target / "bar").is_dir())
+
+        shutil.rmtree(self.src / "bar")
+        skills_install.materialize_global_skills(target)
+
+        self.assertFalse((target / "bar").exists())
+        self.assertTrue((target / "foo").is_dir())
+
+    def test_a_symlinked_directory_in_the_cleanup_scan_is_skipped_not_crashed_on(self) -> None:
+        """is_dir() alone follows a symlink, and shutil.rmtree() refuses a top-level symlink
+        with an uncaught OSError. A stray symlink under the shared target, even one whose real
+        target happens to carry the marker, must be skipped rather than blow up the install."""
+        real = self.tmp / "elsewhere"
+        real.mkdir()
+        (real / skills_install.INSTALLED_MARKER).write_text("", encoding="utf-8")
+        target = self.tmp / "target"
+        target.mkdir(parents=True)
+        (target / "retired-name").symlink_to(real)
+        self.src.mkdir(parents=True)
+
+        skills_install.materialize_global_skills(target)  # must not raise
+
+        self.assertTrue((target / "retired-name").is_symlink())
+        self.assertTrue((real / skills_install.INSTALLED_MARKER).is_file())
+
+    def test_a_same_named_third_party_skill_is_never_removed_as_if_retired(self) -> None:
+        """The marker, not the name, decides what this installer may remove. A third-party
+        skill happening to share a name with something the fleet once published must survive,
+        even though a name-only check would read it as "our old content, now gone"."""
+        target = self.tmp / "target"
+        target.mkdir(parents=True)
+        (target / "bar").mkdir()
+        (target / "bar" / "SKILL.md").write_text("not ours, no marker", encoding="utf-8")
+        self.src.mkdir(parents=True)
+
+        skills_install.materialize_global_skills(target)
+
+        self.assertEqual((target / "bar" / "SKILL.md").read_text(encoding="utf-8"), "not ours, no marker")
+
+    def test_an_installed_skill_carries_the_marker(self) -> None:
+        (self.src / "foo").mkdir(parents=True)
+        (self.src / "foo" / "SKILL.md").write_text("x", encoding="utf-8")
+        target = self.tmp / "target"
+        skills_install.materialize_global_skills(target)
+        self.assertTrue((target / "foo" / skills_install.INSTALLED_MARKER).is_file())
+
+    def test_a_directory_without_skill_md_is_not_copied_as_a_skill(self) -> None:
+        """Matches build_dist.skill_names()'s own definition of a skill, so a stray cache or
+        scratch directory under .agents/skills/ is never treated as one here either."""
+        (self.src / "not-a-skill").mkdir(parents=True)
+        (self.src / "not-a-skill" / "notes.txt").write_text("wip", encoding="utf-8")
+        target = self.tmp / "target"
+        skills_install.materialize_global_skills(target)
+        self.assertFalse((target / "not-a-skill").exists())
+
+    def test_a_symlink_in_a_skill_directory_is_rejected(self) -> None:
+        """shutil.copytree() follows a symlink by default, which would silently pull content
+        from outside .agents/skills/ into the shared, machine-wide skills directory."""
+        (self.src / "foo").mkdir(parents=True)
+        (self.src / "foo" / "SKILL.md").write_text("x", encoding="utf-8")
+        (self.src / "foo" / "escape").symlink_to(self.tmp)
+        target = self.tmp / "target"
+        with self.assertRaises(ValueError):
+            skills_install.materialize_global_skills(target)
+
+
+class ReportCase(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = Path(self.enterContext(tempfile.TemporaryDirectory()))
+
+    def test_no_stamp_reports_not_installed(self) -> None:
+        with mock.patch("builtins.print"):
+            exit_code = skills_install.report(self.tmp / "missing-stamp.json")
+        self.assertEqual(exit_code, 1)
+
+    def test_matching_commit_reports_current(self) -> None:
+        stamp = self.tmp / "stamp.json"
+        with mock.patch("skills_install.source_ref", return_value={"vcs": "git", "commit": "abc", "dirty": False}):
+            stamp.write_text(json.dumps({"stampVersion": skills_install.STAMP_VERSION, "source": {"commit": "abc"}}), encoding="utf-8")
+            exit_code = skills_install.report(stamp)
+        self.assertEqual(exit_code, 0)
+
+    def test_mismatched_commit_reports_stale(self) -> None:
+        stamp = self.tmp / "stamp.json"
+        stamp.write_text(json.dumps({"stampVersion": skills_install.STAMP_VERSION, "source": {"commit": "old"}}), encoding="utf-8")
+        with mock.patch("skills_install.source_ref", return_value={"vcs": "git", "commit": "new", "dirty": False}):
+            exit_code = skills_install.report(stamp)
+        self.assertEqual(exit_code, 1)
+
+    def test_unreadable_stamp_reports_stale_instead_of_crashing(self) -> None:
+        stamp = self.tmp / "stamp.json"
+        stamp.write_text("not valid json {{{", encoding="utf-8")
+        with mock.patch("builtins.print"):
+            exit_code = skills_install.report(stamp)
+        self.assertEqual(exit_code, 1)
+
+    def test_matching_commit_but_dirty_checkout_reports_stale(self) -> None:
+        stamp = self.tmp / "stamp.json"
+        stamp.write_text(json.dumps({"stampVersion": skills_install.STAMP_VERSION, "source": {"commit": "abc"}}), encoding="utf-8")
+        with mock.patch("skills_install.source_ref",
+                         return_value={"vcs": "git", "commit": "abc", "dirty": True}):
+            exit_code = skills_install.report(stamp)
+        self.assertEqual(exit_code, 1)
+
+    def test_installed_from_dirty_but_now_clean_at_the_same_commit_still_reports_stale(self) -> None:
+        """The stamp records dirty=True from install time, when the actual materialized bytes
+        did not match any clean commit. A checkout going clean at the same commit afterward
+        cannot make that install "current": the bytes it produced are still unverifiable
+        against anything, since nothing about the current clean state proves what was on disk
+        at install time."""
+        stamp = self.tmp / "stamp.json"
+        stamp.write_text(
+            json.dumps({"stampVersion": skills_install.STAMP_VERSION,
+                        "source": {"commit": "abc", "dirty": True}}),
+            encoding="utf-8",
+        )
+        with mock.patch("skills_install.source_ref",
+                         return_value={"vcs": "git", "commit": "abc", "dirty": False}):
+            with mock.patch("builtins.print"):
+                exit_code = skills_install.report(stamp)
+        self.assertEqual(exit_code, 1)
+
+    def test_a_valid_json_non_dict_stamp_reports_stale_instead_of_crashing(self) -> None:
+        stamp = self.tmp / "stamp.json"
+        stamp.write_text(json.dumps(["not", "a", "dict"]), encoding="utf-8")
+        with mock.patch("builtins.print"):
+            exit_code = skills_install.report(stamp)
+        self.assertEqual(exit_code, 1)
+
+    def test_a_dict_stamp_with_a_non_dict_source_reports_stale_instead_of_crashing(self) -> None:
+        stamp = self.tmp / "stamp.json"
+        stamp.write_text(
+            json.dumps({"stampVersion": skills_install.STAMP_VERSION, "source": "oops"}),
+            encoding="utf-8",
+        )
+        with mock.patch("skills_install.source_ref", return_value={"vcs": "git", "commit": "abc", "dirty": False}):
+            with mock.patch("builtins.print"):
+                exit_code = skills_install.report(stamp)
+        self.assertEqual(exit_code, 1)
+
+    def test_an_unrecognized_stamp_version_reports_stale(self) -> None:
+        """A future format bump must not have an old-shaped stamp read as current."""
+        stamp = self.tmp / "stamp.json"
+        stamp.write_text(
+            json.dumps({"stampVersion": skills_install.STAMP_VERSION + 1, "source": {"commit": "abc"}}),
+            encoding="utf-8",
+        )
+        with mock.patch("skills_install.source_ref", return_value={"vcs": "git", "commit": "abc", "dirty": False}):
+            with mock.patch("builtins.print"):
+                exit_code = skills_install.report(stamp)
+        self.assertEqual(exit_code, 1)
+
+    def test_a_non_git_checkout_reports_stale_rather_than_current(self) -> None:
+        """source_ref() returns {"vcs": "none"} with no "commit" key at all outside a git
+        checkout. A bare equality/or chain could leave `stale` as None (falsy, same as False)
+        instead of asserting staleness when there is no commit to compare against at all."""
+        stamp = self.tmp / "stamp.json"
+        stamp.write_text(
+            json.dumps({"stampVersion": skills_install.STAMP_VERSION, "source": {"commit": None}}),
+            encoding="utf-8",
+        )
+        with mock.patch("skills_install.source_ref", return_value={"vcs": "none"}):
+            with mock.patch("builtins.print"):
+                exit_code = skills_install.report(stamp)
+        self.assertEqual(exit_code, 1)
+
+
+class MainExitCodeCase(unittest.TestCase):
+    """A caller scripting this installer needs the exit code to distinguish a real failure
+    (claude present but registration failed) from an expected partial install (no claude on
+    this machine at all)."""
+
+    def setUp(self) -> None:
+        self.tmp = Path(self.enterContext(tempfile.TemporaryDirectory()))
+        self.addCleanup(mock.patch.stopall)
+        mock.patch("skills_install.agents_home", return_value=self.tmp).start()
+        mock.patch("skills_install.materialize_global_skills").start()
+        mock.patch("sys.argv", ["skills_install.py"]).start()
+
+    def test_claude_present_but_registration_fails_exits_nonzero(self) -> None:
+        mock.patch("skills_install.claude_available", return_value=True).start()
+        mock.patch("skills_install.register_claude_marketplace", return_value=False).start()
+        self.assertEqual(skills_install.main(), 1)
+
+    def test_claude_present_and_registration_succeeds_exits_zero(self) -> None:
+        mock.patch("skills_install.claude_available", return_value=True).start()
+        mock.patch("skills_install.register_claude_marketplace", return_value=True).start()
+        self.assertEqual(skills_install.main(), 0)
+
+    def test_claude_absent_is_a_partial_install_not_a_failure(self) -> None:
+        mock.patch("skills_install.claude_available", return_value=False).start()
+        self.assertEqual(skills_install.main(), 0)
+
+
+if __name__ == "__main__":
+    unittest.main()