skills #

Nate's personal skills. This repository owns the content and named selections; clients retain their own progressive disclosure and execution permissions.

local use #

profiles.toml is the portable selection contract. interactive opts into every tracked top-level skill; gardener selects gardener-history and pr-body. Add another explicit list when a consumer needs a different subset.

On this laptop, individual links under ~/.agents/skills serve Codex and Pi (including the inspected orca-pi launcher). Individual links under ~/.claude/skills serve Claude Code. Claude's synced/ account cache is outside this repository. Edits through a link immediately edit the authoritative source. Existing sessions may require their client's reload or a fresh session.

uv run scripts/skills.py sync --check
uv run scripts/skills.py sync
uv run scripts/skills.py inventory --profile interactive

Machine configuration lives in ignored .skills-local.toml; copy .skills-local.example.toml on a new machine and choose each target's profile. extras explicitly preserves local-only skill directories. Those extras are never included in portable exports. Third-party entries remain installer-owned. Sync refuses conflicting entries and removes only links it previously recorded as owned. It does not delete source skills or replace third-party installations.

uv run scripts/skills.py install-hooks

This installs repository-local Git hooks for commit, merge, and checkout. New or removed tracked skills reconcile automatically; edits need no copying. Existing hooks/configuration cause a refusal instead of being overwritten. Hook failures are visible in .git/skills-sync.log; Git has already completed its action. After git add without committing, or after editing the local configuration, run sync explicitly. There is no background daemon or account upload.

.git/skills-state.json records links owned by sync, tracked-file hashes, frontmatter, source revision, and local-only selections. A working-tree inventory is explicitly labeled: its revision identifies the base commit, while its hashes identify current tracked bytes. It is not a complete client/plugin inventory.

For the old whole-repository Claude symlink only, migrate-claude replaces it with individual links and moves synced/ into Claude's real skill directory. It preserves local-only skills and leaves the original root link at ~/.claude/skills-repository-link.backup. This migration has been applied here.

portable delivery #

Export from one commit, including the selection at that same commit. No network fetch or mutable default-branch resolution occurs inside an export. Resolve and record a revision after fetching once; all skills then come from that revision. Tracked regular files only: no ignored material, untracked extras, or symlinks inside a skill. Companion scripts retain executable permissions.

revision=$(git rev-parse HEAD)
uv run scripts/skills.py export --profile gardener --revision "$revision" --output /tmp/gardener-skills
uv run scripts/skills.py verify --bundle /tmp/gardener-skills

Outputs refuse to overwrite an existing directory. skills-lock.json records source, commit, selection, verbatim parsed frontmatter, and file paths, sizes, SHA-256 digests, and skill:// URIs. This is our delivery receipt, not a new protocol standard, signature, runtime permission grant, or MCP response envelope. Verification detects content drift; it assumes the receipt itself is trusted.

Layout	Recipient and handoff
directory (default)	skills/<name>/ plus receipt; sandbox runner copies the selected directories and passes explicit skill paths.
--layout project	.agents/skills/<name>/ plus .claude/skills relative link to the same packages; integrate and commit these files into the recipient project for native repository discovery.
--layout claude	Full directories plus one deterministic ZIP per skill; upload selected ZIPs to Claude's account catalog. Upload remains a provider action, not local sync.

A subset controls what this delivery includes, not what other client roots or plugins expose. For an isolated Pi worker use a fresh home and --no-skills plus explicit --skill paths. Match the recipient's tools and environment: several interactive skills assume Nate's filesystem, CLIs, or human feedback. The interactive profile is not a promise that every skill works in the cloud.

The Gardener profile matches the audited autofix selection. Existing Prefect flows have not been switched to this exporter or redeployed. Phi continues to own its separate runtime catalog. Do not silently replace either catalog.

MCP and cloud boundaries #

The same selected packages and receipt can back a future Skills-over-MCP adapter. That adapter must implement the released extension contract, retain server provenance, enforce selection on both discovery and reads, and keep its cache outside local authored-skill roots. It must not promote downloaded remote instructions into trusted local installations.

Our actual client probes found no native skills/list or skills/get calls. Codex CLI could read MCP resources autonomously; Claude ordinary chat needed manual resource attachment. An MCP connection alone therefore does not replace native installation. A search/read tool compatibility adapter would be a separate, explicitly labeled interface, not native skill support.

ChatGPT/Claude account catalogs and cloud sessions do not inherit these local links. Claude ZIPs and committed project packages cover documented handoffs; OpenAI plugin import is a versioned publication snapshot. No remote endpoint, account upload, or plugin publication is configured by this repository. See the audit for evidence and untested surfaces. Publishing requires authorization for the destination repository.

ownership and publishing #

Personal publishable skills live at the repository root. Private secrets, local-only entries, and the externally managed playwright-cli link stay out of exports. Third-party skills remain installer-managed in ~/.agents/skills and its adjacent .skill-lock.json. Project skills belong to their owning repos.

Tangled CI publishes tracked top-level SKILL.md files to skillz.supply as zzstoatzz.io when they change on main. Existing listings retain their URLs and creation dates; unchanged content is skipped, and removing a source does not delete its listing. Skillz distributes only SKILL.md, so full packages must still come from Git or the exporter.

uv run scripts/publish_skillz.py --dry-run
uv run --no-project --with PyYAML==6.0.2 --with atproto==0.0.72 python -m unittest discover -s tests

The repository's SKILLZ_APP_PASSWORD secret on spindle.zzstoatzz.io is derived from the SOPS store. Publishing updates only this repository's skills.* records; earlier protopack.* listings are untouched.