AGENTS.md ยท diff
git:20260925.160ae7c to git:20260928.4f921ea
20 added, 9 removed. Audit A to A.
# AGENTS.md - aigb-skills-usda
## Quick Start
- `git status --short --branch`
- `node -e "require('./package.json')"`
- `npm install` (or `make install`)
- `npm test` (or `make test`)
- `npx skills --help`
- - `npx skills sync --mode copy` (or `make sync`)
+ - `npx skills install --target ~/.agents/skills` (or `make install-skills`)
+ ## Installing Skills (Users & Agents)
+ - **Primary off-ramp**: Pre-materialized skills live in `skills/`.
+ - To install skills into your agent directory on any machine, run:
+ - `npx skills install --target ~/.agents/skills` (or `~/.claude/skills`, `~/.cursor/skills`)
+ - Or run `make install-skills`
+ - **Do not run `skills sync` or `make sync` to install skills.** `sync` is a maintainer-only command that rebuilds `skills/` from upstream source checkouts.
+
+ ## Maintainer Workflows
+ - `npx skills sync --mode copy` (or `make sync`): Re-materializes `skills/` from external source repositories listed in `catalog/skills.lock.json`. Requires local source repo checkouts.
+ - `npm run catalog:mine` (or `make catalog`): Regenerates catalog lockfile.
+
## Repo shape
- `bin/` -- executable shims that expose CLI entry points.
- - `src/` -- CLI implementation layer (delegates commands cleanly).
- - `skills/` -- curated and materialized skill folders.
- - `catalog/` -- authoritative lockfile.
- - `scripts/` -- sync, installer, history mining, and smoke check utilities.
+ - `src/` -- CLI implementation layer (`install` and `sync` commands).
+ - `skills/` -- curated and materialized skill folders (packaged source of truth for installations).
+ - `catalog/` -- authoritative lockfile for upstream source repos.
+ - `scripts/` -- installer (`install.js`), maintainer sync (`sync-skills.js`), history mining, and smoke check utilities.
- `planning/` -- execution plans, wave states, task tracking, and prompt templates (untracked locally).
- - `Makefile` -- standard developer workflow targets (`make help`, `make test`, `make sync`).
+ - `Makefile` -- standard developer workflow targets (`make help`, `make install`, `make install-skills`, `make test`, `make sync`).
- `README.md` -- public-facing overview and install guidance.
- `LICENSE` -- MIT License at the repo root.
## Working conventions
- Keep the public package minimal, reliable, and functional.
- `package.json` must parse cleanly and expose the `skills` bin.
- - The `skills` CLI supports `sync` and `install` operations backed by `catalog/skills.lock.json`.
- - Skills in `skills/` are materialized from source repos according to the catalog lockfile.
+ - The `skills install` command installs pre-bundled skills directly from `./skills` without external network or sibling repo requirements.
+ - The `skills sync` command is strictly for maintainers with local checkouts of upstream source repositories.
- Multi-wave development and planning artifacts live under `planning/` following the `wave-orchestration` skill guidelines.
- Prefer small, verifiable changes that are easy to review and maintain.
## Validation
- - Favor the targeted smoke path from the task spec: `npm install` followed by `npx skills --help` and `npm test`.
+ - Favor the targeted smoke path: `npm install` followed by `npx skills --help` and `npm test`.
- If a change affects package metadata, re-run `node -e "require('./package.json')"` before the smoke test.
## References
- `catalog/skills.lock.json` -- authoritative lockfile for curated skills
- `planning/` -- orchestration state, task DAGs, and execution plans
- Reference repo: `D:\workspace\aigb-skills`