Downstream Skill Inventory Analysis
A full compact-history `$analyze-sessions` report on whether downstream repositories need a skill-copy cleanup workflow, an inventory/version-drift workflow, or a combined approach.
Skill: analyze-sessionsGenerated: 2026-05-31Artifact: alignment/analyze-sessions-downstream-skill-inventory.html
Executive Summary
Verdict: build or extend an inventory-first workflow, not a standalone cleanup-first skill.
The repo already has the primitives for cleanup and refresh: managed skill markers, per-repo drift detection, `scripts/pack.sh doctor`, `scripts/pack.sh refresh`, global init/update, pins, and update modes. The missing surface is a cross-repository inventory that lists every downstream repo's installed skill copies against canonical source versions and hashes, then proposes safe remediation.
The cleanup behavior should exist, but only as an explicit apply mode after the inventory report. Default behavior should be read-only and should distinguish `ok`, `stale`, `unknown`, `pinned`, `missing-source`, non-managed local roots, and active-session reload requirements.
For one repository, this is mostly already covered by `$sync` plus `scripts/pack.sh doctor`. For many downstream repos, the right owner is the fleet/control-repo layer, either as a new project-fleet skill such as `skill-install-inventory` or a focused project-fleet lane. The report should use the existing `doctor` and `refresh` mechanics rather than inventing a second cleanup implementation.
Scope And Method
Sources read:
- Full compact Codex prompt history: `~/.codex/history.jsonl`.
- Full Claude user prompt history: `~/.claude/history.jsonl`.
- Codex rich session metadata from `~/.codex/sessions/**/*.jsonl`, first-line `session_meta` only, used to enrich Codex prompts with project CWD. Compact history remained the prompt-count source of truth.
- Current repository files: `docs/packs.md`, `README.md`, `docs/operating-modes.md`, `scripts/skill-links.sh`, `scripts/pack.sh`, `scripts/skill-drift-hook.sh`, mirrored `sync` skill contracts, and `packs/project-fleet` contracts.
- Current local repo drift command: `scripts/pack.sh doctor`.
No hidden system/developer prompts, tool output text, or base instruction payloads were counted as user prompt patterns. The counts below come from visible user compact histories.
Overview Stats
| Source | User messages | Sessions | Notes |
|---|---|---|---|
| Claude | 9,902 | 2,982 | Largest source; includes older workflow and skill-library history. |
| Codex | 1,931 | 616 | Enriched with 684 rollout metadata records where session IDs matched. |
| Total | 11,833 | 3,598 | Full compact user-history scope, not a sample. |
| Top project | Messages | Relevance to this question |
|---|---|---|
| `/home/georgeqle/projects/tools/dev/agentic-skills` | 447 | Primary skill-library and pack-management evidence source. |
| `/home/georgeqle/projects/tools/dev/claude-skills` | 347 | Older skill-library history; includes symlink/copy and context-pollution discussion. |
| `/home/georgeqle/projects` | 407 | Cross-project and install-management prompts. |
| `/home/georgeqle/projects/web/dev/gblock-party-redux` | not top-15 total | Contains explicit symlink vs copy context-usage question. |
Categorized Patterns
| Pattern | Count | Sessions | Source split | Interpretation |
|---|---|---|---|---|
| Skill/pack plus copy/version/downstream/inventory/cleanup concepts | 116 | 101 | Combined derived category | Directly supports a durable skill-install drift/inventory surface. |
| Pack install, refresh, reload, missing-skill, skill visibility | 62 | 57 | 30 Codex / 32 Claude | Users repeatedly need help understanding how installs become visible and when refresh/reload is needed. |
| Managed copies, symlinks, real-file installs, context pollution | 21 | 19 | 6 Codex / 15 Claude | Directly supports preserving optionality between track-latest copies and pinned/frozen versions. |
| Canonical version, source drift, stale installs, pinned/latest | 44 | 40 | 15 Codex / 29 Claude | Version drift is a recurring concern, but usually as a report/check before action. |
| Downstream or project-local repo scope | 21 | 20 | 13 Codex / 8 Claude | The cross-repo dimension is real but narrower than the generic install/visibility pattern. |
| Inventory/audit/list/status/doctor language | 941 | 682 | 117 Codex / 824 Claude | Broad and noisy category; supports preference for report-first workflows but is not all skill-install related. |
| Cleanup/prune/remove/repair language | 130 | 125 | 16 Codex / 114 Claude | Broad and noisy; direct skill-install cleanup evidence is much smaller than inventory/visibility evidence. |
| `sync` skill usage or sync-freshness requests | 48 | 44 | 37 Codex / 11 Claude | Per-repo status and freshness checks already have an owner surface. |
Representative Examples
| Date | Source | Project | Example | Pattern |
|---|---|---|---|---|
| 2026-05-31 | Codex | `agentic-skills` | `$analyze-sessions should we have a skill which cleans up all copies ... Or have an inventory skill which can list the current versions and the current canonical version?` | Current direct request. |
| 2026-05-30 | Codex | `agentic-skills` | `canonically, are we using symlinks or copies of skills in the downstream repos?` | Copy/symlink policy. |
| 2026-05-30 | Codex | `agentic-skills` | `downstream repos should commit .agents/project.json, not generated .claude/skills or .codex/skills; those are recreated by $pack / scripts/pack.sh refresh?` | Generated roots and safe refresh boundary. |
| 2026-05-29 | Claude | `agentic-skills` | `... transitioning away from symlinks toward copies ... update a certain skill and then the downstream skill can't detect that it is not the canonical skill ... optionality there` | Version drift and pin/latest tradeoff. |
| 2026-05-29 | Claude | `gblock-party-redux` | `is it better to do symlinks or copy? From a context usage perspective, which is better to avoid context pollution?` | Copy model and context cost. |
| 2026-04-13 | Codex | `agentic-skills` | `what's the skill to install packs and will that skill clean up the stubs per project once it's been invoked?` | Install cleanup expectation. |
Repository Evidence
| Artifact | Observed fact | Decision relevance |
|---|---|---|
| `docs/packs.md` | Managed installs are copies stamped with `.agentic-skills-managed`; marker records `source_version` and `source_sha`; `doctor` reports drift; `refresh` re-copies installs; pins are frozen symlinks. | The repo already has the per-repo model needed for inventory and safe refresh. |
| `scripts/skill-links.sh` | `skill_install_status` reports `ok`, `stale`, `unknown`, `missing-source`, `pinned`, or `not-managed`. Its own comment says local edits inside installed copies are intentionally out of scope. | A new inventory workflow should reuse this engine and add local-edit detection only if needed. |
| `scripts/pack.sh doctor` | Read-only drift report for current project-local managed installs; exits non-zero when stale and prints `Fix: scripts/pack.sh refresh`. | Cleanup should call existing refresh after report approval, not reimplement deletion logic. |
| Mirrored `sync` skills | `$sync` and `/sync` already run `scripts/pack.sh doctor`, fold stale installs into the status report, and explicitly must not mutate during plain sync. | Per-repo inventory exists; cross-repo fleet inventory is the missing layer. |
| `scripts/skill-drift-hook.sh` | Opt-in session-start hook warns by default or auto-refreshes when preferences/project update mode enable it. | Automatic cleanup already exists as an opt-in trigger, so a new cleanup-first skill would duplicate policy. |
| `packs/project-fleet` | Project-fleet is the existing pack for central control repositories that coordinate many downstream repositories with status dashboards, guarded batches, and blocker ledgers. | Fleet-level skill install inventory belongs here or should be implemented as a project-fleet lane. |
Current Repo Doctor Smoke
I ran `scripts/pack.sh doctor` in this repository as a non-mutating smoke. It reported the current project update mode as `warn (default)` and found tracked local skill roots with mixed statuses:
- 17 `unknown` installs: run refresh once to enable drift tracking.
- 13 `missing-source` installs: recorded canonical source path no longer exists.
- 2 `stale` installs: `investigate` for Claude and Codex, both `v0.1 -> v0.1` by version but changed by content hash.
- 0 automatic changes were made.
This is strong practical evidence for inventory-first UX: even in the master repo, the actionable answer is not "delete all copies." It is "show status, classify the reason, then choose refresh, pin, ignore, or repair source paths."
Recommendation
Recommended Shape
Create or extend a fleet-level, report-first workflow tentatively named `skill-install-inventory` or `skill-drift-inventory`. It should live in the project-fleet/gitops boundary:
- Project-fleet owner if the skill scans many downstream repositories from a control repo.
- Gitops/sync owner if the change only improves the existing per-repo `$sync` report.
The durable gap is fleet inventory. The cleanup primitive already exists as `scripts/pack.sh refresh` for project-local pack installs and init/update for global installs.
Default Behavior
- Read-only by default.
- Accept explicit repo roots or discover a project-fleet manifest when present.
- For each repo, report `.agents/project.json`, enabled packs, enabled individual skills, `.claude/skills` and `.codex/skills` managed roots, installed `source_version`, canonical version, recorded and current hashes, status, pinned state, and reload guidance.
- Classify actions as `refresh`, `pin acknowledged`, `missing source needs migration`, `unknown needs one refresh`, `non-managed skip`, or `manual review`.
- Do not stage or commit generated `.claude/skills/**` or `.codex/skills/**`; keep `.agents/project.json` as the committed project designation.
Apply Mode
Add cleanup only as an explicit apply mode after a report:
- `--apply refresh-stale`: run `scripts/pack.sh refresh` only in repos with managed installs and `.agents/project.json`.
- `--apply refresh-unknown`: allow one-time marker upgrade for unknown installs.
- Skip pinned installs unless an explicit unpin policy is provided.
- Skip non-managed local directories and report them as user-owned.
- Stop on missing source paths unless a migration map is supplied.
Ranked Recommendations
| Rank | Pattern | Frequency | Recommendation type | Suggested surface |
|---|---|---|---|---|
| 1 | Need to know which skill copies are stale across repos | 116 relevant messages / 101 sessions | Skill or project-fleet lane | `skill-install-inventory` report-first workflow. |
| 2 | Per-repo install drift and sync status | 48 sync-related sessions plus current contracts | Existing skill extension | Keep `$sync`/`/sync` as per-repo owner; ensure output is easy to read. |
| 3 | Cleanup/refresh after inventory | Direct cleanup prompts are sparse; refresh commands already exist | Explicit apply mode | Use `scripts/pack.sh refresh`, `init` update, and existing update modes. |
| 4 | Pin/latest optionality | Explicit May 29 tradeoff prompt plus docs | Standing policy in workflow | Never auto-overwrite pinned installs; show frozen versions clearly. |
| 5 | Local edits to installed copies | Repo engine says out of scope | Optional detector | Add target-copy hash comparison only if downstream repos may hand-edit managed roots. |
Highest-Impact Automations
- Fleet inventory report over downstream repos: avoids manual `doctor` runs and status copy/paste across many projects.
- Action plan grouping: `refresh now`, `pinned`, `missing-source`, `unknown marker`, and `manual review` buckets.
- Safe apply mode that delegates to `scripts/pack.sh refresh` with dry-run/report output first.
- Integration with `$sync` so single-repo and fleet reports use one vocabulary.
- Optional local-edit detector for managed roots, because the current drift engine intentionally does not detect edits to the copied install itself.
Portability Addendum (2026-06-07)
Follow-up finding: downstream inventory scripts are not ready to recommend for broad manual use until they are either macOS-stock-Bash compatible or explicitly documented as requiring Bash 4+ or Node.
The inventory-first recommendation still stands, but portability is now a precondition. The scriptability investigation observed Bash 3.2 failures on this macOS host in scripts that use Bash 4-only constructs such as associative arrays or mapfile. That matters because downstream/manual inventory workflows are most valuable when they can run from ordinary developer machines without hidden shell-version assumptions.
| Script surface | Observed portability issue | Implication for downstream inventory |
|---|---|---|
packs/project-fleet/{claude,codex}/skill-inventory/scripts/skill-inventory.sh | Failed under Bash 3.2 due to Bash 4-only constructs. | Do not recommend as a stock macOS manual script until rewritten or explicitly gated. |
scripts/skill-deps.sh | Failed under Bash 3.2 due to Bash 4-only constructs. | Dependency inventory needs a Bash 3.2-compatible path or a declared Bash 4+ requirement. |
scripts/skill-versions.sh | Failed under Bash 3.2 due to Bash 4-only constructs. | Version inventory cannot be treated as portable until the shell requirement is explicit. |
scripts/skill-next-step-routing.sh | Failed under Bash 3.2 due to Bash 4-only constructs. | Routing inventory should not become a downstream/manual prerequisite without portability remediation. |
scripts/pack.sh remains the best script-first precedent, but fleet inventory should not blindly inherit runnable-script assumptions from adjacent helper scripts. Similarly, the compile-central-alignment follow-up points to a deterministic algorithm that should be extracted carefully, while the scripts/init-agentic-skills.sh documentation/path mismatch shows that a script recommendation is only useful when the documented path exists.
Amended Recommendation
- Keep the report-first downstream inventory shape.
- Add portability to the acceptance criteria before positioning these scripts as manual or downstream-ready.
- Choose one compatibility contract per script: macOS stock Bash 3.2, explicit Bash 4+ dependency, or Node-based implementation.
- Run downstream inventory smoke checks from a stock macOS shell before exposing the workflow as a general operator command.
Evidence Matrix
| Claim | Evidence | Inference | Confidence | Assumption status | Decision impact |
|---|---|---|---|---|---|
| Inventory should be primary. | Current request asks cleanup vs inventory. Full compact histories show 116 skill-install/version/copy relevant messages across 101 sessions; current repo `doctor` produces mixed statuses rather than a single cleanup answer. | The user need is to understand state and safe action. Cleanup is downstream of classification. | High | Evidence-backed for workflow shape; actual downstream stale count not yet scanned. | Design default as read-only inventory. |
| Standalone automatic cleanup would be risky. | Docs define pinned installs as frozen; the May 29 prompt explicitly wants optionality for people who prefer a version. `scripts/skill-drift-hook.sh` already supports opt-in auto-refresh. | Blind cleanup would erase a valid "pinned/frozen" choice or duplicate existing update-mode behavior. | High | Evidence-backed. | Cleanup must be explicit apply mode, not default. |
| Per-repo status already has an owner. | `sync` skills run `scripts/pack.sh doctor`, report stale/unknown/pinned installs, and do not mutate. `scripts/pack.sh doctor` is read-only. | A new single-repo skill would be mostly duplicate; improvements should extend `$sync` or `doctor` output. | High | Evidence-backed. | Do not create redundant per-repo cleanup skill. |
| Fleet inventory is the missing layer. | Project-fleet exists for control repos managing many downstream repos. `doctor` scans only the current project. The user asks about downstream repos not this master repo. | The cross-repo traversal, aggregation, and action-plan reporting do not currently appear as a dedicated skill surface. | Medium-high | Evidence-backed for gap; needs actual downstream root list to validate exact implementation scope. | Put the new workflow in project-fleet or a project-fleet-adjacent pack. |
| The existing drift engine is good enough for canonical moved, but not complete inventory. | `scripts/skill-links.sh` says `skill_install_status` detects canonical moved, not local edits to the install itself. | Inventory should surface this caveat and optionally add target-copy hashing when needed. | High | Evidence-backed. | Scope a local-edit check as optional or Phase 2. |
Assumptions And Confidence
| Conclusion | Confidence | What could change it |
|---|---|---|
| Inventory-first is the right default. | High | If downstream repos are all disposable generated repos where no one pins or edits skill roots, cleanup-first could be acceptable for that narrow fleet. |
| Use existing `doctor`/`refresh` primitives. | High | If those scripts cannot run from downstream repos due launcher resolution issues, the inventory skill must repair launcher resolution first. |
| New cross-repo surface belongs with project-fleet. | Medium-high | If the desired scope is only "current repo before each sync", then extending `$sync` is enough and no new fleet skill is needed. |
| Actual downstream stale volume is unknown. | Medium | A real scan over the intended repo roots could show most repos already current, shifting this from a skill to a recurring check. |
Alternatives Considered
| Alternative | Pros | Cons | Verdict |
|---|---|---|---|
| Standalone cleanup skill | Simple mental model for "make my repos current." | Risky default; duplicates `refresh`; may override pins; hides diagnosis. | Reject as primary. Keep as explicit apply mode. |
| Only document existing commands | No new skill maintenance. | Does not solve multi-repo inventory or action grouping. | Insufficient for downstream fleet use. |
| Extend `$sync` only | Strong per-repo owner; already checks drift. | Sync is scoped to one repo; scanning many downstream repos would bloat a daily primitive. | Good for per-repo polish, not fleet inventory. |
| Project-fleet lane or new skill | Matches control-repo/downstream model; can aggregate, batch, and guard mutations. | Needs repo-root discovery and clear apply safety. | Recommended. |
Review Gates
Evidence Coverage Gate
Is the evidence sufficient to choose an inventory-first workflow shape?
Candidate Verdict Gate
Which candidate should move forward?
Scope Gate
What should the initial implementation be allowed to mutate?
Proposed File Changes Gate
What artifact should be produced after this report is approved?
Compile Answers
Use feedback-only YAML for concerns or clarification before final approval. Use final answers when every required gate has a selected option.