Agent Skills Integration

---
name: agent-skills-integration
description: "Maintain the pinned agent-skills provider/consumer integration. Use when changing the external skill repository or pin, installing or verifying the Codex user catalog, troubleshooting skill collisions or recovery, or changing the dotfiles integration contract."
---

# Agent Skills Integration

## Outcome

Preserve one explicit boundary for reusable skills:

```text
wcygan/agent-skills       dotfiles                     GitHub CLI / Codex
source and validation -> exact consumer lock       -> shared machine-local user copies
                           supported orchestration     and tracking state
```

Success means reusable skill source remains in `wcygan/agent-skills`, this
repository consumes one reviewed commit through `agent-skills.lock.toml`, and
GitHub CLI installs and reports the complete Codex shared user catalog at that
exact commit.

## Ownership Contract

- The `agent-skills` repository owns reusable skill contents, dependencies,
  packaging, and provider-side validation.
- This repository owns only the external repository identifier, immutable
  commit pin, supported command, collision policy, recovery boundary, and
  consumer-side verification.
- GitHub CLI owns fetching, installing, and tracking machine-local copies.
  The lock owns a portable relative shared directory; resolve it under the
  current home and verify its actual contents with `gh skill list --dir`.
- Project-specific operating skills remain under `.agents/skills/` here and
  are not part of the global catalog.

## Invariants

- Pin a full lowercase 40-character commit SHA. Mutable branches, tags, and
  abbreviated SHAs are not an installation contract.
- Invoke `gh skill install` with `--dir <resolved shared user directory> --all
  --pin`. Keep catalog discovery and installation in GitHub CLI instead of
  adding a second clone, copy, vendoring, or synchronization implementation.
- Keep installation explicit through `./bootstrap.sh agent-skills`; the default
  dotfiles install does not mutate the global skill catalog.
- Serialize and journal installation as a dotfiles mutation. Keep
  `./bootstrap.sh agent-skills --check` read-only and lock-free.
- Refuse same-name user skills from another source or duplicate user-scope
  locations before using `--force`.
- Verify every expected skill's source, custom-directory scope, pinned flag,
  exact version, and installed path after installation.
- Keep installed copies and GitHub CLI tracking state untracked and
  machine-local. Never write credentials or remote contents to the operation
  journal.
- Judge unchanged reruns by durable catalog state. Because installation uses
  `--force`, GitHub CLI refreshes `updatedAt` for managed entries in
  `~/.agents/.skill-lock.json` even when source, pin, paths, and contents are
  unchanged. A timestamp-only tracking diff is expected; any inventory,
  duplicate-name, source, scope, pin, path, or file-content change is not.
- Treat removal separately when advancing a pin: GitHub CLI installation does
  not prove that skills removed upstream were pruned locally.

## Workflow

1. Read `agent-skills.lock.toml`, `src/dotfiles_setup/agent_skills.py`, the
   `agent-skills` CLI branch in `src/dotfiles_setup/cli.py`, recovery handling,
   focused tests, and the pinned-skills section of the operations runbook.
2. Inspect `git status --short` in both repositories and inspect the live
   shared user inventory with `gh skill list --dir "$HOME/.agents/skills"
   --json skillName,sourceURL,scope,version,pinned,path`.
3. Classify the change:
   - author or modify a reusable skill in `wcygan/agent-skills`;
   - advance the dotfiles consumer pin after reviewing the provider change;
   - install, reconcile, or verify the currently pinned catalog;
   - change the consumer integration, collision rules, or recovery behavior;
   - explicitly review stale local skills removed from the provider catalog.
4. Make the change only in the owning layer. A provider-source change does not
   belong in dotfiles, and a consumer pin or setup-policy change does not belong
   in the provider repository.
5. For a pin advance, use the reviewed provider commit's full SHA, update only
   `agent-skills.lock.toml`, run the explicit installer, then run the read-only
   check. Inspect removed or renamed skills before any cleanup.
6. For integration code changes, preserve the root `bootstrap.sh` entry point,
   mutation journal, recovery behavior, and metadata-based verification; add
   focused tests for each changed invariant.

## Acceptance

Run the narrow checks first, then the repository gate appropriate to the
change:

```bash
uv tool run --from skills-ref agentskills validate \
  .agents/skills/agent-skills-integration
make agent-skills-check
make test-pre
git diff --check
git diff --exit-code -- flake.lock uv.lock
git status --short
```

For a live installation or pin advance, also confirm that `gh skill list --dir`
reports one source, one exact version, `scope=custom`, and `pinned=true` for
the complete expected catalog. For an unchanged rerun, compare the normalized
inventory and installed file contents; do not use the raw tracking-lock digest
as the idempotency oracle. For Python setup or recovery changes, follow the
broader setup validation matrix in `$dotfiles-operations`.

Report the provider commit, catalog count, actual destination reported by
GitHub CLI, validation evidence, stale-skill review, recovery state, worktree
state, and whether either repository was committed or published.