Agent Workflows

This repository is the authoritative warehouse for reusable shared agent skills.

Storage model

Each skills/<name>/ directory is a complete, independently usable skill package. The repository itself is storage, not a skill.

Inventory

Skill	Purpose
issue-discovery	Investigate requests and draft approval-gated forge issues.
issue-delivery	Deliver existing issues through worktree, validation, pull-request, and merge gates.
clean-context-code-audit	Run independent clean-context implementation audits.
orchestrate-agent-work	Delegate approved long implementations to isolated background Codex workers.

Installed copies

Current global installations remain active and separate. Changes in this warehouse do not automatically update existing global copies under ~/.agents/skills, project-local skillctl-managed copies, or any other installed copy.

Existing manually copied global skills are unmanaged and are not automatically adopted by skillctl. An add --global operation refuses to replace an existing unmanaged destination, so keep those copies separate until performing a deliberate migration.

Project-specific skills stay in their owning repositories. Quant's find-issues and hypothesis-workflow are examples intentionally not stored here.

Use with skillctl

Skillctl can vendor complete skill packages from this warehouse into another project's .agents/skills/ directory. It reads committed Git snapshots, so commit authoritative warehouse changes before distributing them.

From the consuming project, initialize its lock once and add only the skills it needs:

WAREHOUSE=~/path/to/agent-workflows

skillctl init
skillctl add "$WAREHOUSE" --path skills/issue-discovery --ref main
skillctl add "$WAREHOUSE" --path skills/issue-delivery --ref main
skillctl add "$WAREHOUSE" --path skills/clean-context-code-audit --ref main
skillctl check

For a local repository source, skillctl records the canonical absolute warehouse path. A Git repository URL can be used instead when one is available. init creates .agents/skills.lock.yaml; each add validates the selected package, pins its current commit and digest in that lock, and installs the complete directory with its managed marker.

Commit the consuming project's .agents/skills.lock.yaml and .agents/skills/ snapshots together. Managed markers belong in consuming projects; do not add a lock or managed markers to this warehouse.

After committing a warehouse change, inspect the consuming project's managed state and update the selected copy:

skillctl check
skillctl status
skillctl diff issue-delivery
skillctl update issue-delivery --dry-run
skillctl update issue-delivery
skillctl check

check verifies installed integrity without network access, while diff compares installed files with the commit currently pinned in the lock. update --dry-run is the step that previews advancing to a new source commit.

update advances a selected skill along its configured ref and records a new commit and digest. sync instead restores the exact commit already recorded in the lock. Both refuse to overwrite modified managed content unless --force is supplied; edit the authoritative warehouse source instead of a vendored copy.

Manual use

When desired, copy a complete skill directory into an appropriate agent skill discovery directory. Copy the entire directory so its references, assets, agent metadata, and other bundled resources remain available.

Contribution and storage rules

Edit the authoritative warehouse sources, preserve each skill as a self-contained directory, validate every changed skill, and keep project-specific policy outside this repository.