Tracker: `.agents/skills/skill-lifecycle/SKILL.md > The Pipeline`

[ptr727]

Tracker for .agents/skills/skill-lifecycle/SKILL.md > The Pipeline. Filed under the rule #1314's Merge Gate half writes into that unit: a finding classed pre-existing on carried prose is gathered onto the unit's tracker rather than dispositioned one at a time. These are the pre-existing findings the whole-unit pass raised on that unit while the change adding include regions to scripts/build_dist.py (#1317, mechanism pull request) was reviewed. None was introduced by the change and none blocked it. A new pre-existing finding on this unit gathers here, numbering continuing this list. This tracker closes when the unit is rewritten and each line below is settled or superseded.

1. "scripts/skills_install.py, run from a hub checkout, installs both forms per machine" is unconditional, where main() skips the Claude Code plugin install when claude is not on PATH, still exits 0 and still writes the stamp, so a run on such a machine installs one form, --report reads that stamp as current, and the unit gives the reader no signal that the second half did not happen.
2. "Codex and opencode read this tree directly, project-local, and also read the global ~/.agents/skills/ copy the installer materializes" is a claim about two third-party tools that no file the unit names verifies. The installer's docstring restates the same assertion and nothing in the tree tests it.

[ptr727]

Two more from the second whole-unit read on the same change, numbering continuing the list above:

3. "marked per skill so a retired skill is removed on the next run and a foreign skill is never touched" is false for a name collision: materialize_global_skills in scripts/skills_install.py unconditionally removes and replaces ~/.agents/skills/<name> for every current fleet skill name, marker or not, so a foreign skill sharing a fleet skill's name is deleted and overwritten. The marker protects a foreign directory from the retirement sweep only.
4. "installs both forms per machine" and, three sentences later, "The install is global per user" contradict each other: the overlay target and the stamp both sit under the user's home, so two accounts on one machine each install and stamp separately, and "per machine" is the wrong unit.

[ptr727]

One more from the fourth whole-unit read on the same change, numbering continuing the list above:

5. "--report reads that stamp against the checkout and exits non-zero when the machine is behind" names one of four causes: report() also exits 1 when the stamp was written from a dirty checkout, when the current checkout is dirty under .agents/skills/ or .claude-plugin/, and when the checkout is not a git tree. A reader who sees exit 1 on a tree at the stamped commit with local edits and re-runs the installer gets a stamp carrying dirty: true that reports stale until the tree is clean.

[ptr727]

One further pre-existing finding from the whole-unit read the #1317 class 2 pull request ran over this unit, gathered here per the tracker's rule:

3. "marked per skill so a retired skill is removed on the next run and a foreign skill is never touched" is false for a name collision. In scripts/skills_install.py the marker gates only the retirement sweep. The install loop that follows replaces ~/.agents/skills/<name>/ for every current fleet skill name unconditionally, marker or not, so a user's own skill sharing a fleet name is deleted and overwritten on the next run. The installer's own docstring bounds the guarantee correctly, and the unit should state that narrower claim: the marker protects a foreign skill from the retirement sweep, not from being overwritten by a fleet skill of the same name.

[ptr727]

Findings from four whole-unit passes over this unit during #1441 (2026-09-08). Every one is pre-existing: text this change did not write. The ones the change did write were fixed on that PR.

Claims that are false or over-broad

1. "A source is any regular file under the repository root outside the two generated trees and reached through no symlink" understates what include_source() enforces. It also refuses an empty path, an absolute path, any .. component, a spelling that does not round-trip through PurePosixPath (a trailing slash, a ./ prefix), and any component not spelled as the tree spells it. Read alone the sentence says ./AGENTS.md and agents.md are valid sources; the exit-2 list four lines later says both fail.
2. "Regenerating after a source edit changes the bytes of every skill unit including it" is over-broad. The fill re-renders only the body under the named heading, with the source's own markers dropped and doubled blanks collapsed, so an edit elsewhere in the source file changes no including unit's bytes and triggers no drift. The consequence drawn from it, that the whole-unit review pass is owed again, does not follow for a source edit generally.
3. "--report reads that stamp against the checkout and exits non-zero when the machine is behind" names one of five non-zero cases. report() also returns 1 with no stamp, an unreadable stamp, an unrecognized stampVersion, and a dirty checkout or a dirty recorded install. A machine that is exactly current reports non-zero whenever the hub checkout is dirty, and a reader takes that as "behind" and reinstalls.
4. "scripts/skills_install.py, run from a hub checkout, installs both forms per machine" disagrees with "The install is global per user" three sentences later. The installer's own docstring settles it as per user. On a host with no claude on PATH the overlay half lands, the plugin half is skipped, the run still exits 0 and stamps a partial install, so a reader believes both forms landed.
5. ".agents/skills/<name>/SKILL.md is the only tree a skill is authored in, with optional references/ and scripts/ directories beside it" calls a file a tree and then puts directories beside the file. The tree is .agents/skills/<name>/; SKILL.md is what marks the directory as a skill. No skill carries a scripts/ directory today.

Incompleteness a reader would act on

6. The exit-2 enumeration omits a manifest that reads and parses but is not the shape it declares, which _manifest_entries() refuses. scripts/README.md's parallel list names it.
7. Nothing tells a reader that a marker inside a fenced or indented code block is content, yet the enumeration's last item presupposes it. A genuine marker placed inside a fence gets silence and an unfilled region, and the near-miss refusal that exists to prevent exactly that will not fire there.
8. The refusal text the unit quotes offers two remedies, and the first is closed for every file spec/files.json carries content from: adding GOVERNANCE.md, AGENTS.md, CODESTYLE.md, WORKFLOW.md, AUDIT.md or .github/copilot-instructions.md to INCLUDE_DESTINATIONS is refused on the next line. The message presents both as equally available.
9. "build_dist.py --check exits non-zero when either tree differs from .agents/skills/" is true for .github/skills/ and not for the plugin tree, whose own root entries is_stale() never checks. Filed separately as a code defect, noted here because this sentence is where a reader would learn otherwise.

Raised by adversarial passes rather than by a PR-hosted reviewer, so there is no thread to link.