From f7d26e855b97052f738403219e09989ef60a9ec0 Mon Sep 17 00:00:00 2001
From: Shun Kakinoki <shunkakinoki@gmail.com>
Date: Sun, 2 Aug 2026 15:47:49 +0800
Subject: [PATCH] fix(skills): propagate re-lock failure, document
 prerequisites

---
 Makefile                   | 2 +-
 README.md                  | 3 ++-
 rules/skills-management.md | 3 +++
 3 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 9822042..566c159 100644
--- a/Makefile
+++ b/Makefile
@@ -124,7 +124,7 @@ skills-install: ## Install external skills declared in SKILLS.txt (skips already
 	done; \
 	rm -f "$$tmp_missing"; \
 	if [ -f "$(SKILLS_GLOBAL_LOCK)" ]; then \
-		$(MAKE) skills-lock; \
+		$(MAKE) skills-lock || failed=1; \
 	fi; \
 	exit $$failed
 
diff --git a/README.md b/README.md
index 67d8858..d6af106 100644
--- a/README.md
+++ b/README.md
@@ -22,12 +22,13 @@ make skills-install
 make skills-update
 
 # Regenerate skills-lock.json from SKILLS.txt without installing
+# (requires ~/.agents/.skill-lock.json, created by the first global install)
 make skills-lock
 
 # Force a reinstall of everything in the lock
 make skills-refresh
 ```
 
-To add skills: edit `SKILLS.txt`, run `make skills-install`, and commit both files. To remove: delete from `SKILLS.txt`, run `bunx skills remove <name> --global --yes`, then `make skills-lock`.
+To add skills: edit `SKILLS.txt`, run `make skills-install`, and commit both files. Install-all repos (no selection) need a one-time bootstrap before they appear in the lock: `bunx skills add owner/repo --global --yes --skill '*'` (the `make skills-lock` warning prints the exact command), then `make skills-lock`. To remove: delete from `SKILLS.txt`, run `bunx skills remove <name> --global --yes`, then `make skills-lock`.
 
 Installs track each source's default branch: the skills CLI does not record commit SHAs in its lock yet, so entries are not pinned to a commit.
diff --git a/rules/skills-management.md b/rules/skills-management.md
index c72d8e3..dde442e 100644
--- a/rules/skills-management.md
+++ b/rules/skills-management.md
@@ -26,6 +26,9 @@ bunx skills add owner/repo --global --list
 # 3. Install (regenerates skills-lock.json from SKILLS.txt automatically)
 cd dotagents && make skills-install
 
+# Install-all repos (no selection) need a one-time bootstrap to enter the lock:
+# bunx skills add owner/repo --global --yes --skill '*'
+
 # 4. Commit SKILLS.txt and skills-lock.json together
 ```