Agent Skills Integration

Agent Skills Integration

Outcome

Preserve one explicit boundary for reusable skills:

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:

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.