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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
1---2name: agent-skills-integration3description: "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."4metadata:5 source: https://skillmd.com/skills/wcygan/agent-skills-integration6---78# Agent Skills Integration910## Outcome1112Preserve one explicit boundary for reusable skills:1314```text15wcygan/agent-skills dotfiles GitHub CLI / Codex16source and validation -> exact consumer lock -> shared machine-local user copies17 supported orchestration and tracking state18```1920Success means reusable skill source remains in `wcygan/agent-skills`, this21repository consumes one reviewed commit through `agent-skills.lock.toml`, and22GitHub CLI installs and reports the complete Codex shared user catalog at that23exact commit.2425## Ownership Contract2627- The `agent-skills` repository owns reusable skill contents, dependencies,28 packaging, and provider-side validation.29- This repository owns only the external repository identifier, immutable30 commit pin, supported command, collision policy, recovery boundary, and31 consumer-side verification.32- GitHub CLI owns fetching, installing, and tracking machine-local copies.33 The lock owns a portable relative shared directory; resolve it under the34 current home and verify its actual contents with `gh skill list --dir`.35- Project-specific operating skills remain under `.agents/skills/` here and36 are not part of the global catalog.3738## Invariants3940- Pin a full lowercase 40-character commit SHA. Mutable branches, tags, and41 abbreviated SHAs are not an installation contract.42- Invoke `gh skill install` with `--dir <resolved shared user directory> --all43 --pin`. Keep catalog discovery and installation in GitHub CLI instead of44 adding a second clone, copy, vendoring, or synchronization implementation.45- Keep installation explicit through `./bootstrap.sh agent-skills`; the default46 dotfiles install does not mutate the global skill catalog.47- Serialize and journal installation as a dotfiles mutation. Keep48 `./bootstrap.sh agent-skills --check` read-only and lock-free.49- Refuse same-name user skills from another source or duplicate user-scope50 locations before using `--force`.51- Verify every expected skill's source, custom-directory scope, pinned flag,52 exact version, and installed path after installation.53- Keep installed copies and GitHub CLI tracking state untracked and54 machine-local. Never write credentials or remote contents to the operation55 journal.56- Judge unchanged reruns by durable catalog state. Because installation uses57 `--force`, GitHub CLI refreshes `updatedAt` for managed entries in58 `~/.agents/.skill-lock.json` even when source, pin, paths, and contents are59 unchanged. A timestamp-only tracking diff is expected; any inventory,60 duplicate-name, source, scope, pin, path, or file-content change is not.61- Treat removal separately when advancing a pin: GitHub CLI installation does62 not prove that skills removed upstream were pruned locally.6364## Workflow65661. Read `agent-skills.lock.toml`, `src/dotfiles_setup/agent_skills.py`, the67 `agent-skills` CLI branch in `src/dotfiles_setup/cli.py`, recovery handling,68 focused tests, and the pinned-skills section of the operations runbook.692. Inspect `git status --short` in both repositories and inspect the live70 shared user inventory with `gh skill list --dir "$HOME/.agents/skills"71 --json skillName,sourceURL,scope,version,pinned,path`.723. Classify the change:73 - author or modify a reusable skill in `wcygan/agent-skills`;74 - advance the dotfiles consumer pin after reviewing the provider change;75 - install, reconcile, or verify the currently pinned catalog;76 - change the consumer integration, collision rules, or recovery behavior;77 - explicitly review stale local skills removed from the provider catalog.784. Make the change only in the owning layer. A provider-source change does not79 belong in dotfiles, and a consumer pin or setup-policy change does not belong80 in the provider repository.815. For a pin advance, use the reviewed provider commit's full SHA, update only82 `agent-skills.lock.toml`, run the explicit installer, then run the read-only83 check. Inspect removed or renamed skills before any cleanup.846. For integration code changes, preserve the root `bootstrap.sh` entry point,85 mutation journal, recovery behavior, and metadata-based verification; add86 focused tests for each changed invariant.8788## Acceptance8990Run the narrow checks first, then the repository gate appropriate to the91change:9293```bash94uv tool run --from skills-ref agentskills validate \95 .agents/skills/agent-skills-integration96make agent-skills-check97make test-pre98git diff --check99git diff --exit-code -- flake.lock uv.lock100git status --short101```102103For a live installation or pin advance, also confirm that `gh skill list --dir`104reports one source, one exact version, `scope=custom`, and `pinned=true` for105the complete expected catalog. For an unchanged rerun, compare the normalized106inventory and installed file contents; do not use the raw tracking-lock digest107as the idempotency oracle. For Python setup or recovery changes, follow the108broader setup validation matrix in `$dotfiles-operations`.109110Report the provider commit, catalog count, actual destination reported by111GitHub CLI, validation evidence, stale-skill review, recovery state, worktree112state, and whether either repository was committed or published.