Installation & Updates
Relevant source files
The following files were used as context for generating this wiki page:
Installation and updates in the claude-skills project involve synchronizing version-controlled assets from a git repository to a local agent environment. The project establishes a governed Claude Code agent estate where the main branch serves as the authoritative source for global rules, skills, and execution hooks.
This system ensures that the agent operates with a predictable set of deterministic behaviors and quality gates. Updates require reconciliation between the tracked repository files and the active environment in ~/.claude/ to preserve machine-managed integrations while applying new project standards.
Core Installation Workflow
The installation process synchronizes the repository's authoritative files to specific paths within the ~/.claude/ directory. You must start from a clean checkout of the main branch to ensure consistency.
File Mapping
The project maps repository paths to live environment paths as follows:
| Repo Path | Live Path | Purpose |
|---|---|---|
CLAUDE.md | ~/.claude/CLAUDE.md | Global rules and hard invariants |
skills/ | ~/.claude/skills/ | Directory of executable agent skills |
settings.json | ~/.claude/settings.json | Permissions, model, and hook wiring |
hooks/ | ~/.claude/hooks/ | Execution gates and workflow hooks |
Sources: README.md:1-12
Installation Steps
- Fetch and Align: Update your local repository to the latest
mainbranch. - Reconcile: Compare
settings.jsonandCLAUDE.mdwith the local versions to identify intentional machine-managed changes. - Backup: Create a timestamped backup of the existing
~/.claude/directory. - Sync: Use
rsyncandcpto copy files without deleting machine-managed additions (like HerdR session hooks). - Set Permissions: Ensure all Python hooks in
~/.claude/hooks/are executable. - Install Dependencies: Pinned tools like
ruffmust be installed viauvto satisfy edit-time quality hooks.
Sources: README.md:17-45
The following diagram illustrates the synchronization flow from the repository to the agent estate:
The diagram shows the sequential steps required to safely update the local agent environment from the authoritative repository source.
Per-Repo Skill Setup
After the global installation, individual repositories require local configuration so that engineering skills understand the specific environment. This is handled by the setup-matt-pocock-skills utility.
Configuration Categories
The setup process prompts the user to define three core settings:
- Issue Tracker: Determines where tasks live (GitHub, GitLab, Local Markdown, or Other).
- Triage Labels: Maps the five canonical triage roles (
needs-triage,needs-info,ready-for-agent,ready-for-human,wontfix) to specific strings. - Domain Docs: Configures the layout for
CONTEXT.mdand ADRs (Single-context vs. Multi-context).
Sources: skills/setup-matt-pocock-skills/SKILL.md:1-16
Persistence Logic
The setup skill modifies specific files based on existing presence:
- If
CLAUDE.mdexists at the repo root, it edits it. - Otherwise, if
AGENTS.mdexists, it edits it. - It creates detailed documentation in
docs/agents/(e.g.,issue-tracker.md,domain.md).
Sources: skills/setup-matt-pocock-skills/SKILL.md:104-121
External Dependencies
The estate is not self-contained and relies on external tools to function. These tools must be installed on the host machine; otherwise, the environment will "brick" itself because quality gates will fail to execute.
Mandatory Toolset
| Tool | Requirement | Function |
|---|---|---|
| GitNexus | Built to dist | Architecture execution flow analysis |
| Repo Context Forge | Private Repo | Initial target and coverage surface generation |
| fff | Binary 0.7.1 | Initial search layer and file discovery |
| ruff | Pinned Version | Edit-time Python linting |
Sources: README.md:120-155
Hook Permissions and Execution
Hooks are registered in settings.json. Every tracked top-level hook is written in Python.
- Permissions: The installation process uses
chmod +xon*.pyfiles in the hooks directory. - Shell Hooks: Specific shell hooks (like
herdr-agent-state.sh) are registered asbash '<path>' sessionand do not require the executable bit. - Ruff Requirement: If
ruffis missing or fails to launch, the hook reportsruff could not run: python lint skippedon every Python edit, though the quality gate will still attempt to run.
Sources: README.md:38-55
Maintenance and Updates
Maintaining the estate involves pruning "orphans"—files that exist in the local ~/.claude/ directory but are no longer tracked in the repository.
Pruning Orphans
Because the installation uses rsync without the --delete flag to protect machine-managed files, renamed or deleted upstream files remain in the local environment.
- Identify orphans using
diff -qr. - Retire orphans by appending
.deprecatedto the filename. - Remove the executable bit from deprecated files.
- Delete deprecated files once replacements are verified.
Sources: README.md:65-103
Verification Procedures
After an update, you must verify the integrity of the estate using the provided test scripts:
bash ~/.claude/hooks/tests/run.sh: Tests the core execution gates.bash ~/.claude/skills/codex-advisor/tests/test-ask-codex-advisor.sh: Verifies advisor integration.- Mode checks: Ensure
find ~/.claude/hooks -maxdepth 1 -name '*.py' ! -perm -u+xreturns no results.
Sources: README.md:57-63
The following sequence diagram represents a typical update verification:
Sources: README.md:17-63
Summary
Installation and updates of claude-skills follow a strict governance model to ensure the agent estate remains predictable. The process prioritizes the preservation of local machine integrations through non-destructive rsync while enforcing project standards via global rules (CLAUDE.md), skills, and hooks. Successful installation requires external tool availability and post-install verification to confirm that all gates and skills are correctly positioned and executable.