Harden skill catalog install and validation

[ccarvalho-eng]

Summary

This PR tightens the skill-pack maintenance flow so local installs are safer and catalog drift is caught automatically.

It fixes the stale elixir-phoenix-compound cross-skill references, makes .worktrees/ untracked, hardens install.sh so --dry-run is non-mutating, and adds manifest-based pruning/removal so repo-managed stale skills do not linger in local Codex installs. It also adds a catalog validator script and a GitHub Actions workflow to catch broken local references/... links and script regressions in CI.

Why

The repo had a few low-risk maintenance gaps:

• one skill referenced stale cross-skill paths and names
• install.sh --dry-run still created the target directory
• installs did not remove deleted repo-managed skills
• uninstall inferred ownership from the current tree rather than the installed set
• there was no automated validation to catch catalog drift

Impact

Users installing this skill pack get cleaner local updates, predictable dry-run behavior, and automatic pruning of removed skills. Maintainers also get CI coverage for catalog integrity and install/uninstall behavior.

Validation

• bash ./scripts/validate_skills.sh
• installed the updated pack into local ~/.codex/skills with bash ./install.sh

Summary by CodeRabbit

Release Notes

• New Features

  • Added --dry-run flag to preview installation and uninstall operations without modifying the filesystem
  • Implemented automatic skill manifest tracking to intelligently remove skills deleted from the repository

• Documentation

  • Updated README documenting manifest behavior and validation process

• Tests

  • Added automated skill catalog validation in CI/CD workflow

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 93d325b2-daaa-4270-963f-8526757a4449

📥 Commits

Reviewing files that changed from the base of the PR and between 38a154d and 86b55f2.

📒 Files selected for processing (7)

• .github/workflows/validate-skills.yml
• .gitignore
• README.md
• install.sh
• scripts/validate_skills.sh
• skills/elixir-phoenix-compound/SKILL.md
• uninstall.sh

---

📝 Walkthrough

Walkthrough

This PR introduces a skill manifest system for tracking installed skills, enabling automatic pruning of removed skills. A new validation workflow and script verify skill catalogs for broken references and test install/uninstall operations. Both install and uninstall scripts now support --dry-run mode.

Changes

Cohort / File(s)	Summary
GitHub Actions Workflow .github/workflows/validate-skills.yml	New workflow that runs skill validation on push and pull request events using a bash script.
Git Configuration .gitignore	Added .worktrees/ directory to ignore list.
Documentation README.md	Documented skill manifest generation/pruning behavior and added "Validate" section with validation command details.
Installation Logic install.sh	Added multi-argument parsing, --dry-run support, manifest-based skill synchronization, and automatic pruning of previously installed skills no longer in source.
Uninstallation Logic uninstall.sh	Added multi-argument parsing, --dry-run support, and manifest-driven uninstall to remove skills tracked in ownership manifest.
Validation Script scripts/validate_skills.sh	New bash script that validates skill catalog structure, checks for broken references/ links, and performs install/uninstall roundtrip testing in sandboxed environments.
Skill Documentation skills/elixir-phoenix-compound/SKILL.md	Updated to reference elixir-phoenix-compound-docs schema and templates instead of compound-docs/references/.

Sequence Diagram

sequenceDiagram
    participant User
    participant install.sh
    participant Manifest as Manifest File
    participant Skills as Skill Dirs
    participant uninstall.sh

    User->>install.sh: Run install.sh [--dry-run]
    install.sh->>Skills: Read source skill directories
    install.sh->>Skills: Prune previously installed skills<br/>no longer in source
    install.sh->>Skills: Copy/install current source skills
    install.sh->>Manifest: Write current skill inventory
    Manifest-->>install.sh: Manifest updated
    
    Note over install.sh: With --dry-run, no<br/>filesystem modifications
    
    User->>uninstall.sh: Run uninstall.sh [--dry-run]
    uninstall.sh->>Manifest: Read owned skills from manifest
    uninstall.sh->>Skills: Remove all owned skill directories
    uninstall.sh->>Manifest: Delete manifest file
    Manifest-->>uninstall.sh: Manifest removed

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A manifest so neat, tracking skills with care,
Dry runs test before we leap into the air,
Old skills pruned away, new ones installed with pride,
Validation keeps our catalog verified far and wide! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/fix-skill-catalog-polish

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}