Pack Install Issue Analysis

The current repository state is mostly healthy. Project-local Claude and Codex roots now expose the expected active skills, including analyze-sessions, investigate, targeted-skill-builder, ship, and sync. The remaining risk is workflow friction: users naturally say $pack install targeted skill builder or $pack install content creator pack, while the script is safest with exact identifiers such as targeted-skill-builder, skill-dev, creator-media, or a real skill name discovered through scripts/pack.sh which.

The strongest evidence is from repeated session logs on May 22-29, repository lessons written immediately after failures, and current pack script behavior. The weakest evidence is any claim about Claude internals beyond what conversations and docs show, because Claude's runtime loader behavior is inferred from observed prompts and project docs rather than instrumented directly.

Counts from the compact pass: 12,927 user records, 9,744 Claude and 3,183 Codex. Counts from the rich pass: 36,667 records, 22,697 Claude and 13,970 Codex. The rich pass can over-count pasted file contents, so quantitative command counts use compact histories while qualitative failure analysis uses rich session records.

1. Running sessions do not hot-reload newly installed skills

Shared High confidence

pack install updates local files and .agents/project.json, but Claude and Codex may load available skill instructions at session start. The project docs and pack skill explicitly say a fresh CLI session may be needed. Many successful installs ended with that caveat, which explains why an install can succeed yet the user still cannot invoke the skill immediately.

2. Natural-language install phrases are ambiguous

Shared High confidence

The install parser splits raw arguments on spaces and commas. That makes exact names reliable, but phrases such as targeted skill builder, skill fixer, or content creator pack can become separate tokens. Some tokens resolve to aliases or packs, while later tokens can fail. This also explains why agents repeatedly had to use scripts/pack.sh which or inspect pack manifests.

3. Codex discovery previously missed symlink-style installs

Codex-heavy High confidence

A May 28 lesson recorded that scripts/pack.sh status listed the expected packs while real-file discovery under .codex/skills saw only two SKILL.md files. The repair changed active managed installs to copied real files rather than symlinked SKILL.md files. Current local roots are healthy, so this appears fixed locally rather than an active blocker.

4. Codex executions hit launcher, working-directory, sandbox, and filesystem blockers

Codex-heavy High confidence

Several Codex incidents first ran the bundled launcher from the skill directory or a wrong path, then had to rerun from the target repository with the repo-local script. Codex also hit sandbox write restrictions around .agents and .codex. One incident had a zero-byte .codex file where the installer needed a directory.

5. Cross-pack routing guidance was incomplete until late May

Shared Medium-high confidence

Before the current fallback rules, skills and agents could recommend a skill by name without telling the user which pack contains it. The user explicitly called out this gap, and the project now instructs agents to run scripts/pack.sh which <skill-name> and recommend installing the containing pack when the command is missing.

Lower-confidence findings

• Exact Claude runtime mechanics are inferred from docs and conversations. I did not instrument Claude's skill loader.
• Some rich transcript matches can include pasted file contents, so the rich pass is not used for exact command frequency.
• Pack lock issues appear in sessions, but this pass did not audit lock implementation in depth because the stronger recurring blockers are naming, reload, and sandbox context.

Source gaps

• No direct telemetry from Claude or Codex skill-list reload internals.
• No fresh reproduction of every historical failing command, because running install commands could mutate the local project again.
• No cross-machine validation that all developers have refreshed away from stale symlink installs.

If this analysis is accepted, the highest-leverage fixes are small and targeted:

• Add a preflight phase to scripts/pack.sh install so all tokens or phrases are validated before any project mutation occurs.
• Normalize common natural phrases before token splitting, especially targeted skill builder to targeted-skill-builder and content/creator phrases to the intended creator media bundle.
• Keep scripts/pack.sh which <skill> in missing-skill fallback rules and benchmark those rules so agents recommend the containing pack.
• Keep the no-hot-reload warning visible in install output and final responses after installs.
• For Codex, prefer running the repo-local scripts/pack.sh from the target project root, and treat sandbox write errors as permission issues rather than pack logic failures.

The lower-risk path is documentation and benchmark reinforcement only. The higher-leverage path is a parser preflight change, because it prevents partial mutation when a multi-token phrase contains both valid and invalid tokens.

This report run proposes the following durable files only:

• alignment/analyze-sessions-pack-install-issues.html: this review artifact.
• tasks/roadmap.md: current targeted update status.
• tasks/todo.md: current task checklist and review notes.

No pack script changes are included in this report run. Any parser, alias, launcher, or benchmark change should be handled as a separate implementation task after review.