feat(skills): vendor skills-CLI packages via lockfile

.gitignore

@@ -15,6 +15,9 @@
 # Agent build output
 build/
 
+# skills CLI project staging (canonical copies live in skills/; lock in skills-lock.json)
+.agents/
+
 # Node.js
 node_modules/
 

AGENTS.md

@@ -18,20 +18,23 @@ agents/
 ├── plugins/                        # Git submodules (skill sources, owner-repo format)
 │   ├── anthropics-skills/          # github.com/anthropics/skills
 │   └── mitsuhiko-agent-stuff/      # github.com/mitsuhiko/agent-stuff
-├── skills/                         # Custom skills (local)
+├── skills/                         # Custom + vendored skills (local)
 │   └── <skill-name>/
 │       ├── SKILL.md                # Skill definition (YAML frontmatter + markdown)
 │       └── <additional files>      # Supporting scripts/resources
+├── skills-lock.json                # npx skills lockfile (ecosystem packages)
 ├── skill-overrides/                # Agent-specific appends
 │   └── <skill>-<agent>.md          # Appended to SKILL.md during build
 ├── pi-extensions/                  # Custom Pi extensions (local)
 │   ├── protected-paths/
 │   └── <extension-name>/index.ts
 ├── scripts/
-│   └── build.py                    # Python build system (requires Python 3.11+)
+│   ├── build.py                    # Python build system (requires Python 3.11+)
+│   └── skill_lock.py               # skills CLI lock + vendor bridge
 ├── tests/                          # Test suite
 │   ├── test-helpers.sh             # Shared test utilities
 │   ├── test-make.sh                # Makefile tests
+│   ├── test-skill-lock.sh          # skills CLI lock + vendor tests
 │   ├── test-pi-skills-config.sh    # Pi config tests
 │   ├── test-pi-extensions.sh       # Pi extensions type-check tests
 │   └── run-all.sh                  # Run all tests
@@ -82,12 +85,26 @@ make install
 | `make install-extensions` | Install Pi extensions only |
 | `make clean` | Remove all installed artifacts and build directory |
 | `make plugin-update` | Update all plugin submodules to latest |
+| `make skill-add SOURCE=owner/repo` | Add a skills-CLI package, lock it, and vendor into `skills/` |
+| `make skill-vendor` | Copy staged `.agents/skills` entries from `skills-lock.json` into `skills/` |
+| `make skill-update` | Update locked project skills via `npx skills`, then re-vendor |
+| `make skill-sync` | Restore from `skills-lock.json`, then vendor |
 | `make agents-config` | Configure all agents to use their own skills directories (avoid duplicates) |
 
+### Skills CLI packages (lock + vendor)
+Ecosystem skills installed with [`npx skills`](https://github.com/vercel-labs/skills) are tracked in committed `skills-lock.json` and copied into `skills/` for the normal build pipeline.
+
+- Staging: `.agents/skills/` (gitignored)
+- Canonical copies: `skills/<name>/` (committed)
+- Bridge script: `scripts/skill_lock.py`
+
+Prefer `make skill-add SOURCE=owner/repo` over installing skills only into home agent dirs. Hand-written skills still live directly under `skills/`; large multi-skill repos can remain plugin submodules in `plugins.toml`.
+
 ### Testing
 ```bash
 ./tests/run-all.sh          # Run all tests
 ./tests/test-make.sh        # Test Makefile commands
+./tests/test-skill-lock.sh  # Test skills-CLI lock + vendor bridge
 ./tests/test-pi-skills-config.sh  # Test Pi config command
 ./tests/test-pi-extensions.sh     # Test Pi extensions type-checking
 ```
@@ -183,6 +200,13 @@ Extensions use the unified `ExtensionAPI` which provides:
 1. Create `skill-overrides/<skill-name>-<agent>.md` (agent: `claude` or `pi`)
 2. Content will be appended to the skill during build
 
+### Adding a Skills CLI Package (`npx skills`)
+1. Run `make skill-add SOURCE=owner/repo` (optional `SKILL=name` or `ALL_SKILLS=1`)
+2. This updates committed `skills-lock.json`, stages under gitignored `.agents/skills/`, and vendors copies into `skills/`
+3. Run `make install` so home agent dirs pick up the new skill
+4. Update README.md under notable custom / lockfile skills
+5. To refresh later: `make skill-update` or `make skill-sync`
+
 ### Adding an Extension (Pi only)
 1. Fetch the [Pi Coding Agent extensions documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/extensions.md) for the current API
 2. Create `pi-extensions/<extension-name>/index.ts` following the documentation

Makefile

@@ -15,7 +15,11 @@ HOME_LINKS := .gitconfig .ideavimrc .psqlrc .tmux.conf .tmuxinator .vscode
 # .config directories to symlink entirely
 CONFIG_DIRS := alacritty stylua lvim zellij direnv atuin ghostty
 
+SKILL_LOCK_SCRIPT := $(CURDIR)/scripts/skill_lock.py
+SKILL_ADD_FLAGS := $(if $(SKILL),--skill $(SKILL),)$(if $(ALL_SKILLS), --all-skills,)
+
 .PHONY: all install install-non-interactive install-tools install-skills install-amp-plugins install-extensions install-prompts install-themes install-configs amp-plugin-types amp-plugin-check package-manager-security-config build clean help submodule-init plugin-update check-python \
+	skill-add skill-vendor skill-update skill-sync \
 	dot-all dot-install dot-home-symlinks dot-config-symlinks dot-platform-defaults dot-macos-defaults dot-clean
 
 all: help
@@ -41,6 +45,14 @@ help:
 	@echo "  make plugin-update           Update all plugin submodules to latest"
 	@echo "  make clean                   Remove all installed skills, extensions, and build artifacts"
 	@echo ""
+	@echo "Skills CLI (npx skills) lock + vendor:"
+	@echo "  make skill-add SOURCE=owner/repo   Add via npx skills, vendor into skills/"
+	@echo "  make skill-add SOURCE=owner/repo SKILL=name"
+	@echo "  make skill-add SOURCE=owner/repo ALL_SKILLS=1"
+	@echo "  make skill-vendor                 Copy .agents/skills -> skills/ from lockfile"
+	@echo "  make skill-update                 Update locked project skills, then vendor"
+	@echo "  make skill-sync                   Restore from skills-lock.json, then vendor"
+	@echo ""
 	@echo "Dotfiles:"
 	@echo "  make dot-all                Run all dotfile setup tasks"
 	@echo "  make dot-install            Install required Homebrew/Linuxbrew packages and tmux plugins"
@@ -110,6 +122,24 @@ plugin-update:
 	@git submodule update --remote --merge
 	@echo "Plugins updated"
 
+# Skills CLI lockfile bridge: stage via npx skills into .agents/skills, vendor into skills/
+skill-add: check-python
+	@if [ -z "$(SOURCE)" ]; then \
+		echo "Usage: make skill-add SOURCE=owner/repo [SKILL=name] [ALL_SKILLS=1]"; \
+		exit 1; \
+	fi
+	@$(PYTHON) "$(SKILL_LOCK_SCRIPT)" add "$(SOURCE)" $(SKILL_ADD_FLAGS)
+
+skill-vendor: check-python
+	@$(PYTHON) "$(SKILL_LOCK_SCRIPT)" vendor
+
+skill-update: check-python
+	@$(PYTHON) "$(SKILL_LOCK_SCRIPT)" update $(SKILL)
+
+skill-sync: check-python
+	@$(PYTHON) "$(SKILL_LOCK_SCRIPT)" sync
+
+
 # Helper: create symlink or error if non-symlink exists
 # Usage: $(call safe_symlink,source,target)
 define safe_symlink

README.md

@@ -48,6 +48,38 @@ make install-configs
 make build                   # build agent artifacts only
 make clean                   # clean agent build/install artifacts
 make plugin-update           # update plugin submodules
+
+# Skills CLI packages (npx skills) — lockfile + vendored copies
+make skill-add SOURCE=github/gh-stack
+make skill-add SOURCE=owner/repo SKILL=name
+make skill-vendor            # copy staged .agents/skills -> skills/ from skills-lock.json
+make skill-update            # npx skills update (project) then re-vendor
+make skill-sync              # restore from skills-lock.json then vendor
+```
+
+### Skills CLI packages (`npx skills`)
+
+Third-party skills from the [skills](https://github.com/vercel-labs/skills) ecosystem are tracked in `skills-lock.json` and **vendored as copies** under `skills/` so `make install` stays offline and multi-agent.
+
+| Piece | Role |
+|-------|------|
+| `skills-lock.json` | Committed lockfile (source + content hash from `npx skills`) |
+| `.agents/skills/` | Staging only (gitignored); written by `npx skills add` |
+| `skills/<name>/` | Canonical vendored copy; consumed by `scripts/build.py` |
+
+```bash
+# Preferred: one-shot add + vendor
+make skill-add SOURCE=github/gh-stack
+
+# Or manually:
+npx skills add github/gh-stack --agent universal --copy -y
+make skill-vendor
+
+# On a new machine, if skills/ copies are already in git, just:
+make install
+
+# To re-fetch locked skills into staging and re-vendor:
+make skill-sync
 ```
 
 External native tools are pinned under `[external_tools]` in `plugins.toml`. They are installed into `~/.local/bin` without allowing upstream installers to modify agent settings; this repository owns those settings through `make install-configs`. The full `make install` workflow installs tools before configs.
@@ -99,6 +131,7 @@ pi
 - `zmx` — guidance for managing persistent background terminal work
 - `tmux` — remote control tmux sessions through the active server, with an agent-neutral fallback socket when no server is running
 - `buildr-artifacts` — publish browser-viewable Buildr artifacts as static S3-hosted HTML/assets or stateful Vite apps served from Codexbox with `bld.run` URLs
+- `gh-stack` — stacked PR workflow for the `gh-stack` GitHub CLI extension (from `github/gh-stack` via `skills-lock.json`)
 
 ### Notable plugin skills
 
@@ -132,14 +165,16 @@ pi
 ```text
 dotfiles/
 ├── .config/                 # shell/editor/terminal configs
-├── skills/                  # custom agent skills
+├── skills/                  # custom + vendored agent skills
+├── skills-lock.json         # npx skills lockfile (ecosystem packages)
 ├── amp-configs/             # managed Amp settings
 ├── amp-plugins/             # custom Amp plugins
 ├── pi-extensions/           # Pi extensions
 ├── pi-themes/               # Pi themes
 ├── prompts/                 # Pi prompt templates
 ├── plugins/                 # plugin submodules
 ├── scripts/build.py         # agent build/install system
+├── scripts/skill_lock.py    # skills CLI lock + vendor bridge
 ├── tests/                   # agent tooling tests
 └── Makefile                 # dotfiles + agent commands
 ```