Add helper scripts for use, sync, and freshness

README.md

@@ -18,12 +18,14 @@ The Library is a single skill whose only job is to manage other skills. It's a c
 
 Think of it as a `package.json` for agent capabilities — but instead of packages, you're managing skills, agents, and prompts. Instead of a registry, you're pointing at your own private GitHub repos and local paths.
 
-**This is a pure agent application.** There are no scripts, no CLIs, no dependencies, no build tools. The entire application is encoded in `SKILL.md` and a set of cookbook instructions that teach the agent exactly what to do. The agent IS the runtime. This matters because:
+**This is primarily an agent application.** The core behavior is still encoded in `SKILL.md` and the cookbook instructions, but the repo can also ship small helper scripts for repeatable operations such as `use`, `sync`, and `freshness`. The agent remains the orchestration layer.
+
+This matters because:
 
 - Any agent harness that reads skill files can run it (Claude Code, Pi, etc.)
-- You can modify behavior by editing markdown, not code
+- You can keep high-level behavior in markdown while using scripts for repeatable file operations
 - The skill can be extended, forked, and adapted instantly
-- An orchestrator agent can chain library commands without any tooling overhead
+- An orchestrator agent can chain library commands without having to re-implement low-level copy and compare logic each time
 
 ## Why It Exists
 
@@ -214,6 +216,7 @@ Pull the latest version of all installed items:
 | `/library remove <name>`    | Remove from catalog and optionally delete local copy       |
 | `/library list`             | Show full catalog with install status                      |
 | `/library sync`             | Re-pull all installed items from source                    |
+| `/library freshness`        | Check if installed items match their sources               |
 | `/library search <keyword>` | Find entries by name or description                        |
 
 ### Justfile Shortcuts
@@ -226,6 +229,7 @@ just use my-skill          # Pull a skill
 just push my-skill         # Push changes back
 just add "name: foo, description: bar, source: /path/to/SKILL.md"
 just sync                  # Re-pull all installed items
+just freshness             # Check whether installed items are current
 just search "keyword"
 ```
 

SKILL.md

@@ -33,6 +33,7 @@ The Library is a catalog of references to your agentics. The `library.yaml` file
 | `/library remove <name>`    | Remove from catalog and optionally local |
 | `/library list`             | Show full catalog with install status    |
 | `/library sync`             | Re-pull all installed items from source   |
+| `/library freshness`        | Check if installed items match source    |
 | `/library search <keyword>` | Find entries by keyword                  |
 
 ## Cookbook
@@ -48,10 +49,13 @@ Each command has a detailed step-by-step guide. **Read the relevant cookbook fil
 | remove  | [cookbook/remove.md](cookbook/remove.md)   | User wants to remove an entry from the catalog               |
 | list    | [cookbook/list.md](cookbook/list.md)       | User wants to see what's available and what's installed      |
 | sync    | [cookbook/sync.md](cookbook/sync.md)       | User wants to refresh all installed items at once            |
+| freshness | [cookbook/freshness.md](cookbook/freshness.md) | User wants to check if installed items are up-to-date        |
 | search  | [cookbook/search.md](cookbook/search.md)   | User is looking for a skill but doesn't know the exact name |
 
 **When a user invokes a `/library` command, read the matching cookbook file first, then execute the steps.**
 
+For `/library use`, `/library sync`, and `/library freshness`, preserve the user's project context. If the catalog uses relative `default_dirs`, run the script with `--project-root "$PWD"` from the target project root, or pass an explicit `--target` or `--global` where supported. Do not `cd` into the library repo and run these scripts there unless you intend to target that repo explicitly.
+
 ## Source Format
 
 The `source` field in `library.yaml` supports these formats (auto-detected):