AGENTS.md git:20261026.38a67b8A

Immutable. This exact content never changes and is served at /api/v1/blob/8bbe574ec5034857.

# skillcask

Lockfile-first package manager for agent skills, shipped as one Rust binary. Design, non-goals and
numbered decisions (D1, D2, …) live in `docs/specs/2026-10-19-skillcask-v1.md`: read it before
changing how the manifest, lock, install or publish behave, and record a new decision there in the
same change.

## Checks

Run what CI runs before every commit:

```sh
cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked
```

`cargo test --locked --test cli -- --ignored` runs end-to-end against live Packagist; run it after
touching registry or HTTP code.

CI tests Linux, macOS and Windows. Paths, symlinks and exec bits must work on all three.

## Invariants

- Package content is data only: skillcask never runs scripts, hooks or plugins from a package.
- `install` installs exactly what the lock pins and fails on any hash mismatch.
- No telemetry.
- The repository is public: code, docs and commit messages name only public projects and services.

## Commits

Conventional Commits with a lowercase subject that states the outcome, e.g.
`fix: refuse symlinked project dirs and harden add, gitignore and CLI errors`.

## Release

1. Bump `version` in `Cargo.toml`, run `cargo build` to update `Cargo.lock`, commit
   `chore: release X.Y.Z`, push.
2. `git tag vX.Y.Z && git push origin vX.Y.Z`. `release.yml` builds all targets and publishes the
   GitHub Release, Homebrew formula and npm package.
3. `cargo publish --locked` from the tag (manual).
4. Edit the GitHub Release in the browser, tick "Publish this Action to the GitHub Marketplace" and
   save (manual: GitHub has no API for it, and releases made by `release.yml` are not listed).

`release.yml` comes from `dist generate`, but it is hand-edited; re-apply the edits after
regenerating:

- `publish-npm` uses npm trusted publishing: `id-token: write`, an exact npm >= 11.5.1 at least
  3 days old, no `GH_TOKEN`, and no `registry-url` in `setup-node` (it injects a placeholder
  `NODE_AUTH_TOKEN` that breaks OIDC with E404).
- Supply chain: every action pinned to a commit sha, the dist installer checked against a pinned
  sha256, and `GH_TOKEN: ""` on the steps that install tools.