ai-agent-skills 3.5.1 → 4.2.0

package/FOR_YOUR_AGENT.md

@@ -0,0 +1,219 @@
+# For Your Agent
+
+Use this when you want an agent to build and share a managed skills library for you, not just make a local folder of `SKILL.md` files.
+
+For detailed workflow guidance, install the skill: `npx ai-agent-skills install curate-a-team-library`.
+
+The companion workflow skills are:
+
+- `npx ai-agent-skills install install-from-remote-library`
+- `npx ai-agent-skills install curate-a-team-library`
+- `npx ai-agent-skills install share-a-library`
+- `npx ai-agent-skills install browse-and-evaluate`
+- `npx ai-agent-skills install update-installed-skills`
+- `npx ai-agent-skills install build-workspace-docs`
+- `npx ai-agent-skills install review-a-skill`
+- `npx ai-agent-skills install audit-library-health`
+- `npx ai-agent-skills install migrate-skills-between-libraries`
+
+## Paste this into your agent
+
+```text
+Set up a managed team skills library for me with `ai-agent-skills`.
+
+Use this repo for reference if you need docs or examples:
+https://github.com/MoizIbnYousaf/Ai-Agent-Skills
+https://github.com/MoizIbnYousaf/Ai-Agent-Skills/blob/main/FOR_YOUR_AGENT.md
+
+Use the CLI with `npx`. Do not ask me to open the repo or link you to anything else.
+Do not hand-edit `skills.json`, `README.md`, or `WORK_AREAS.md` if the command already exists.
+
+Follow this curator decision protocol:
+
+1. Create a new workspace with `npx ai-agent-skills init-library <name>`, unless I already gave you a library name.
+2. Move into that workspace and keep working there.
+3. Ask me at most 3 short questions before acting:
+   - what kinds of work the library needs to support
+   - whether the first pass should stay small and opinionated or aim broader
+   - whether this should end as a local draft only or a shareable GitHub repo
+4. Use these 5 work areas as the shelf system:
+   - `frontend` for web UI, browser work, design systems, visual polish
+   - `backend` for APIs, databases, security, infrastructure, runtime systems
+   - `mobile` for iOS, Android, React Native, Expo, device testing, app delivery
+   - `workflow` for docs, testing, release work, files, research, planning
+   - `agent-engineering` for prompts, evals, tools, orchestration, agent runtime design
+5. Map the user's stack to shelves before adding anything.
+   - Example: "I build mobile apps with React Native and a Node backend" maps to `mobile` + `backend`.
+   - Add `workflow` only when testing, release, docs, or research are clearly part of the job.
+   - Add `agent-engineering` only when the user is building AI features, agents, prompts, evals, or toolchains.
+   - Make sure the first pass covers every primary shelf the user explicitly named. Do not let `mobile` crowd out `backend` if they asked for both.
+6. Run a discovery loop before curating:
+   - use `npx ai-agent-skills list --area <work-area>` to browse a shelf
+   - use `npx ai-agent-skills search <query>` when the user names a stack, tool, or capability
+   - use `npx ai-agent-skills collections` to inspect starter packs that may already exist
+   - keep machine-readable reads tight with `--fields name,tier,workArea`
+   - use `--limit 10` on larger result sets before asking for more
+   - if the user named multiple primary shelves, browse each of them before deciding what to add
+7. Keep the first pass small, around 3 to 8 skills.
+8. Choose the right mutation path:
+   - use `add` first for bundled picks and simple GitHub imports when the CLI can route it for you
+   - use `catalog` when you want an upstream entry without copying files into `skills/`
+   - use `vendor` only for true house copies you want to edit or own locally
+9. Keep branch names consistent and useful.
+   - Examples: `React Native / UI`, `React Native / QA`, `Node / APIs`, `Node / Data`, `Docs / Release`
+   - Use branches to group related picks inside a shelf, not as free-form notes
+10. Every mutation must include explicit curator metadata like `--area`, `--branch`, and `--why`.
+11. Write `whyHere` notes as concrete curation reasoning, not placeholders.
+   - good: "Covers React Native testing so the mobile shelf has a real device-validation option."
+   - bad: "I want this on my shelf."
+12. Use `--featured` sparingly.
+   - keep it to about 2 to 3 featured skills per shelf
+   - reserve it for skills you would tell a new teammate to install first
+13. After the library has about 5 to 8 solid picks, create a `starter-pack` collection.
+   - add new entries with `--collection starter-pack`
+   - or use `npx ai-agent-skills curate <skill> --collection starter-pack` for existing entries
+14. Sanity-check the library before finishing.
+   - run `npx ai-agent-skills list --area <work-area>` for each primary shelf you touched
+   - if you created `starter-pack`, run `npx ai-agent-skills collections` and confirm the install command looks right
+15. Run `npx ai-agent-skills build-docs` before finishing.
+16. If the user wants the library shared, turn it into a GitHub repo:
+   - `git init`
+   - `git add .`
+   - `git commit -m "Initialize skills library"`
+   - `gh repo create <owner>/<repo> --public --source=. --remote=origin --push`
+17. End by telling me:
+   - what you added
+   - which shelves you used and why
+   - which skills are featured
+   - what the `starter-pack` includes, if you created one
+   - the shareable install command
+   - use `npx ai-agent-skills install <owner>/<repo> --collection starter-pack -p` when a starter pack exists
+   - otherwise use `npx ai-agent-skills install <owner>/<repo> -p`
+```
+
+## Curator Decision Framework
+
+Start with the workspace, not manual file edits. The job is to produce a library that another person or agent can actually browse, trust, and install.
+
+### Shelf Mapping Rules
+
+- `frontend`: web interfaces, design systems, browser automation, UI polish, app-shell UX.
+- `backend`: APIs, auth, databases, data pipelines, infra, services, runtime behavior.
+- `mobile`: React Native, Expo, SwiftUI, Kotlin, simulators, device QA, store delivery.
+- `workflow`: testing, release work, docs, research, content ops, file transforms, planning.
+- `agent-engineering`: prompts, evals, tool use, orchestration, memory, agent runtime patterns.
+
+If a user gives a mixed stack, map it to more than one shelf. Do not force every skill into one branch. If the stack is "React Native + Node backend", the first shelves are `mobile` and `backend`, and you only pull in `workflow` or `agent-engineering` when the actual work justifies it.
+
+The first pass should include at least one strong anchor skill for each primary shelf the user explicitly named.
+
+### Discovery Loop
+
+Before curating, inspect what already exists.
+
+- Browse shelves with `npx ai-agent-skills list --area <work-area>`.
+- Search by tools or capabilities with `npx ai-agent-skills search <query>`.
+- Check `npx ai-agent-skills collections` when a ready-made pack may already cover part of the use case.
+- In machine-readable flows, prefer `--fields name,tier,workArea` first so the response stays small.
+- Add `--limit 10` when a shelf or search looks broad, then page further only if needed.
+- If the user named multiple primary shelves, browse each one before you start curating.
+
+Do not jump straight from `init-library` to a few guessed names unless the user already told you the exact skills they want.
+
+### Add vs Catalog vs Vendor
+
+- Use `add` as the default front door inside a workspace.
+- Use `catalog` when the right move is "track this upstream skill in our library, but do not copy its files into `skills/`."
+- Use `vendor` when the right move is "we want our own editable house copy in this library."
+
+If the user wants a repo they can share across a team, prefer upstream catalog entries for third-party skills and reserve house copies for true internal ownership.
+
+### Branch Naming
+
+Keep branch labels consistent so the shelves stay readable.
+
+- Good: `React Native / UI`, `React Native / QA`, `Node / APIs`, `Node / Data`, `Docs / Release`
+- Bad: `stuff`, `misc`, `my notes`
+
+### Writing Good `whyHere` Notes
+
+`whyHere` is curator judgment. It should explain why this skill belongs in this library, on this shelf, for this team.
+
+- Mention the actual gap it fills.
+- Mention the stack or workflow it supports.
+- Be honest about why it is here instead of a nearby alternative.
+- Never use placeholders like "I want this" or "looks useful."
+
+### Featured Skills
+
+Featured picks are the shelf anchors.
+
+- Keep featured picks to about 2 to 3 per shelf.
+- Feature the skills a new teammate should notice first.
+- Do not feature everything.
+
+### Collections
+
+Once the library has a meaningful first pass, create a `starter-pack` collection.
+
+- Put the first recommended 3 to 5 skills in it.
+- Make it cross-shelf when that helps onboarding.
+- Use `curate --collection starter-pack` to retrofit membership onto skills that are already in the catalog.
+
+### Final Sanity Check
+
+Before you hand the library back:
+
+- Run `npx ai-agent-skills list --area <work-area>` for each primary shelf you touched.
+- Run `npx ai-agent-skills collections` if you created `starter-pack`.
+- Make sure the resulting library still reflects the user’s actual stack and does not over-index on one shelf.
+
+### Sharing Step
+
+A library is not really shared until it is in Git and has an install command you can hand to someone else.
+
+After `build-docs`, if the user wants sharing:
+
+```bash
+git init
+git add .
+git commit -m "Initialize skills library"
+gh repo create <owner>/<repo> --public --source=. --remote=origin --push
+```
+
+Then give them the actual install command to share, for example:
+
+```bash
+npx ai-agent-skills install <owner>/<repo> --collection starter-pack -p
+```
+
+If you did not create a `starter-pack` yet, share the whole library instead:
+
+```bash
+npx ai-agent-skills install <owner>/<repo> -p
+```
+
+## Direct Shell Fallback
+
+```bash
+npx ai-agent-skills init-library my-library
+cd my-library
+
+npx ai-agent-skills list --area mobile
+npx ai-agent-skills search react-native
+npx ai-agent-skills search testing
+
+npx ai-agent-skills add frontend-design --area frontend --branch Implementation --why "Anchors the frontend shelf with stronger UI craft and production-ready interface direction."
+npx ai-agent-skills add anthropics/skills --skill webapp-testing --area workflow --branch Testing --why "Adds browser-level validation so the workflow shelf covers end-to-end checks." --collection starter-pack
+npx ai-agent-skills catalog conorluddy/ios-simulator-skill --skill ios-simulator-skill --area mobile --branch "React Native / QA" --why "Gives the mobile shelf a concrete simulator workflow for app-level testing." --collection starter-pack --featured
+
+npx ai-agent-skills build-docs
+
+git init
+git add .
+git commit -m "Initialize skills library"
+gh repo create <owner>/my-library --public --source=. --remote=origin --push
+
+# Share this with teammates:
+npx ai-agent-skills install <owner>/my-library --collection starter-pack -p
+```

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  A smaller library for Claude Code, Codex, Cursor, and other <code>SKILL.md</code>-compatible agents.
+  The skills I actually keep around, organized the way I work.
 </p>
 
 <!-- GENERATED:library-stats:start -->
@@ -13,19 +13,28 @@
   <a href="https://github.com/MoizIbnYousaf/Ai-Agent-Skills"><img alt="GitHub stars" src="https://img.shields.io/github/stars/MoizIbnYousaf/Ai-Agent-Skills?style=for-the-badge&label=stars&labelColor=313244&color=89b4fa&logo=github&logoColor=cdd6f4" /></a>
   <a href="https://www.npmjs.com/package/ai-agent-skills"><img alt="npm version" src="https://img.shields.io/npm/v/ai-agent-skills?style=for-the-badge&label=version&labelColor=313244&color=b4befe&logo=npm&logoColor=cdd6f4" /></a>
   <a href="https://www.npmjs.com/package/ai-agent-skills"><img alt="npm total downloads" src="https://img.shields.io/npm/dt/ai-agent-skills?style=for-the-badge&label=downloads&labelColor=313244&color=f5e0dc&logo=npm&logoColor=cdd6f4" /></a>
-  <a href="https://github.com/MoizIbnYousaf/Ai-Agent-Skills#shelves"><img alt="Library structure" src="https://img.shields.io/badge/library-55%20skills%20%C2%B7%205%20shelves-cba6f7?style=for-the-badge&labelColor=313244&logo=bookstack&logoColor=cdd6f4" /></a>
+  <a href="https://github.com/MoizIbnYousaf/Ai-Agent-Skills#shelves"><img alt="Library structure" src="https://img.shields.io/badge/library-64%20skills%20%C2%B7%205%20shelves-cba6f7?style=for-the-badge&labelColor=313244&logo=bookstack&logoColor=cdd6f4" /></a>
 </p>
 
-<p align="center"><sub>8 house copies · 47 cataloged upstream</sub></p>
+<p align="center"><sub>17 house copies · 47 cataloged upstream</sub></p>
 <!-- GENERATED:library-stats:end -->
 
 <p align="center"><em>Picked, shelved, and maintained by hand.</em></p>
 
+<p align="center">
+  <a href="./docs/workflows/start-a-library.md"><strong>Build your own library</strong></a>
+  ·
+  <a href="./FOR_YOUR_AGENT.md"><strong>For your agent</strong></a>
+</p>
+
 ## Library
 
-`ai-agent-skills` is a CLI library of agent skills for tools like Claude Code, Codex, Cursor, and other SKILL.md-compatible agents.
+`ai-agent-skills` does two things.
 
-I organize it the way I work:
+It ships my curated library, and it gives you the CLI and TUI to build and manage your own.
+It works with any Agent Skills-compatible agent.
+
+The bundled library is organized the way I work:
 
 - Start with a shelf like `frontend` or `workflow`
 - Keep the set small enough to browse quickly
@@ -33,15 +42,23 @@ I organize it the way I work:
 - Keep notes that explain why a skill is here
 
 Use `skills.sh` for the broad ecosystem.
-Use this repo for my kept set.
+Use `ai-agent-skills` when you want a smaller library with shelves, provenance, and notes.
+
+## What's New in 4.0.0
 
-## Why Keep It
+- Managed library workspaces with `init-library`
+- `add <source>` for bringing bundled picks, upstream repo skills, or house copies into your own library
+- `sync [name]` as the main refresh command; `update` stays as an alias
+- Dependency-aware installs with `requires` and `--no-deps`
+- Installed status in both the CLI and TUI
+
+## What It Is Now
 
 I launched this on December 17, 2025, before `skills.sh` existed and before the ecosystem had a clear default universal installer.
 
-Originally this repo was that installer. That part still matters.
+Originally this repo was that installer. It still does that.
 
-I keep it because the library itself has become useful: shelves, provenance, and notes that make the curation legible.
+What started as an installer is now a place to build and manage your own library of skills.
 
 ## How It Works
 
@@ -53,12 +70,55 @@ Each skill here is either a house copy or a cataloged upstream pick.
 
 - `Cataloged upstream`
   Metadata in `skills.json` with no local folder.
-  These stay upstream and install live from the source repo when you ask for them.
+  These stay upstream and install from the source repo when you ask for them.
 
 Upstream work stays upstream. That keeps the library lean.
 
+## For Your Agent
+
+Tell your agent to build you a library. Paste this, or just point it at this repo — the protocol below has everything it needs.
+
+Full protocol with curator decision framework: [FOR_YOUR_AGENT.md](./FOR_YOUR_AGENT.md)
+
+### Paste this into your agent
+
+```text
+Set up a managed team skills library for me with `ai-agent-skills`.
+
+Read the full agent protocol here before starting:
+https://raw.githubusercontent.com/MoizIbnYousaf/Ai-Agent-Skills/main/FOR_YOUR_AGENT.md
+
+Use the CLI with `npx`. Do not hand-edit `skills.json`, `README.md`, or `WORK_AREAS.md` if the command already exists.
+
+1. Fetch and read FOR_YOUR_AGENT.md above — it has the full curator decision protocol.
+2. Create a workspace with `npx ai-agent-skills init-library <name>`.
+3. Ask me at most 3 short questions: what kinds of work, small or broad, local draft or shared repo.
+4. Map my stack to shelves: frontend, backend, mobile, workflow, agent-engineering.
+5. Run a discovery loop: `list --area <shelf>`, `search <query>`, `collections`.
+6. Add 3-8 skills with explicit `--area`, `--branch`, and `--why` on every mutation.
+7. Run `npx ai-agent-skills build-docs` before finishing.
+8. If I want it shared: `git init && git add . && git commit -m "Initialize skills library" && gh repo create`.
+9. Tell me what you added, which shelves, and the install command for teammates.
+```
+
+The companion workflow skills (installed automatically when you use the library):
+
+```
+npx ai-agent-skills install install-from-remote-library
+npx ai-agent-skills install curate-a-team-library
+npx ai-agent-skills install share-a-library
+npx ai-agent-skills install browse-and-evaluate
+npx ai-agent-skills install update-installed-skills
+npx ai-agent-skills install build-workspace-docs
+npx ai-agent-skills install review-a-skill
+npx ai-agent-skills install audit-library-health
+npx ai-agent-skills install migrate-skills-between-libraries
+```
+
 ## Quick Start
 
+### Use the bundled library
+
 ```bash
 # Open the terminal browser
 npx ai-agent-skills
@@ -69,7 +129,7 @@ npx ai-agent-skills list
 # Install a skill from the library
 npx ai-agent-skills install frontend-design
 
-# Install the Swift hub straight to Claude + Codex
+# Install the Swift hub to the default global targets
 npx ai-agent-skills swift
 
 # Install an entire curated pack
@@ -78,7 +138,7 @@ npx ai-agent-skills install --collection swift-agent-skills -p
 # Install to the project shelf
 npx ai-agent-skills install pdf -p
 
-# Install all skills from an upstream repo straight to Claude + Codex
+# Install all skills from an upstream repo to the default global targets
 npx ai-agent-skills anthropics/skills
 
 # Browse a repo before adding or installing from it
@@ -92,6 +152,46 @@ Default install targets:
 
 Legacy agent-specific targets still work through `--agent <name>`.
 
+### Start your own library
+
+```bash
+# Create a managed workspace
+npx ai-agent-skills init-library my-library
+cd my-library
+
+# Add a bundled pick, install it, refresh it, and rebuild the docs
+npx ai-agent-skills add frontend-design --area frontend --branch Implementation --why "I want this on my shelf."
+npx ai-agent-skills install frontend-design -p
+npx ai-agent-skills sync frontend-design -p
+npx ai-agent-skills add anthropics/skills --skill webapp-testing --area workflow --branch Testing --why "I use this when I want browser-level checks in the workspace."
+npx ai-agent-skills build-docs
+```
+
+## Workspace Mode
+
+Workspace mode is part of the normal flow now.
+
+Start with a managed workspace, add a few skills, then keep your shelves current with `add`, `catalog`, `vendor`, `sync`, and `build-docs`.
+
+```bash
+npx ai-agent-skills init-library my-library
+cd my-library
+
+npx ai-agent-skills add frontend-design --area frontend --branch Implementation --why "I want this on my shelf."
+npx ai-agent-skills install frontend-design -p
+npx ai-agent-skills add anthropics/skills --skill webapp-testing --area workflow --branch Testing --why "I use this when I want browser-level checks in the workspace."
+npx ai-agent-skills sync frontend-design -p
+npx ai-agent-skills build-docs
+```
+
+Workflow guides:
+
+- [Start a library](./docs/workflows/start-a-library.md)
+- [Add an upstream skill](./docs/workflows/add-an-upstream-skill.md)
+- [Make a house copy](./docs/workflows/make-a-house-copy.md)
+- [Organize shelves](./docs/workflows/organize-shelves.md)
+- [Refresh installed skills](./docs/workflows/refresh-installed-skills.md)
+
 ## Browse
 
 Most browsing starts in one of two places:
@@ -101,7 +201,7 @@ Most browsing starts in one of two places:
 | Shelves | The main way to understand the library: start with the kind of work, then drill into the small set of picks on that shelf. | `npx ai-agent-skills list` |
 | Sources | The provenance view: see which publishers feed which shelves and branches. | `npx ai-agent-skills info frontend-design` |
 
-The other views are still there. They are just secondary:
+The other views are still useful, just more situational:
 
 - `npx ai-agent-skills browse` for the TUI
 - `npx ai-agent-skills list --collection my-picks` for a cross-shelf starter stack
@@ -118,8 +218,8 @@ The shelves are the main structure.
 | Frontend | 10 | Interfaces, design systems, browser work, and product polish. |
 | Backend | 5 | Systems, data, security, and runtime operations. |
 | Mobile | 24 | Swift, SwiftUI, iOS, and Apple-platform development, with room for future React Native branches. |
-| Workflow | 10 | Files, docs, planning, release work, and research-to-output flows. |
-| Agent Engineering | 6 | MCP, skill-building, prompting discipline, and LLM application work. |
+| Workflow | 11 | Files, docs, planning, release work, and research-to-output flows. |
+| Agent Engineering | 14 | MCP, skill-building, prompting discipline, and LLM application work. |
 <!-- GENERATED:shelf-table:end -->
 
 The full map lives in [WORK_AREAS.md](./WORK_AREAS.md).
@@ -139,10 +239,13 @@ Collections are smaller sets. Useful, but secondary to the shelves.
 | `docs-and-research` | Docs, files, research, and writing work. | `pdf`, `doc-coauthoring`, `docx` |
 <!-- GENERATED:collection-table:end -->
 
-## Curating The Catalog
+## Curating the catalog
 
 Use `catalog` when you want to add an upstream skill without vendoring it.
 
+In a managed workspace, start with `add`.
+Use `catalog` and `vendor` when you want more control.
+
 ```bash
 npx ai-agent-skills catalog openai/skills --list
 npx ai-agent-skills catalog openai/skills --skill linear --area workflow --branch Linear
@@ -151,15 +254,15 @@ npx ai-agent-skills catalog conorluddy/ios-simulator-skill --skill ios-simulator
 npx ai-agent-skills catalog shadcn-ui/ui --skill shadcn --area frontend --branch Components
 ```
 
-It does not copy the skill into this repo.
-It adds metadata and placement:
+It does not create a local copy.
+It adds metadata and placement in the active library:
 
 - which shelf it belongs on
 - what branch it lives under
 - why it earned a place
 - how it should install later
 
-For existing picks, `curate` is the quick loop:
+For existing picks, use `curate` for quick edits:
 
 ```bash
 npx ai-agent-skills curate frontend-design --branch Implementation
@@ -184,12 +287,12 @@ Current upstream mix:
 | Source repo | Skills |
 | --- | --- |
 | `anthropics/skills` | 11 |
+| `MoizIbnYousaf/Ai-Agent-Skills` | 11 |
 | `openai/skills` | 9 |
 | `Dimillian/Skills` | 4 |
 | `wshobson/agents` | 4 |
 | `rgmez/apple-accessibility-skills` | 3 |
 | `ComposioHQ/awesome-claude-skills` | 2 |
-| `MoizIbnYousaf/Ai-Agent-Skills` | 2 |
 | `andrewgleave/skills` | 1 |
 | `arjitj2/swiftui-design-principles` | 1 |
 | `AvdLee/Core-Data-Agent-Skill` | 1 |
@@ -242,7 +345,7 @@ npx ai-agent-skills install ./local-path
 npx ai-agent-skills install <skill-name> --dry-run
 
 # Maintain
-npx ai-agent-skills update [name]
+npx ai-agent-skills sync [name]
 npx ai-agent-skills uninstall <name>
 npx ai-agent-skills check
 npx ai-agent-skills doctor
@@ -261,9 +364,9 @@ npx ai-agent-skills vendor <repo-or-path> --skill <name> --area <shelf> --branch
 - `npm test`
   Fast regression coverage for CLI behavior, schema rules, routing, and local install flows.
 - `npm run test:live`
-  No-mock live verification. Clones the real upstream repos, captures raw `SKILL.md` frontmatter and file manifests, runs real install/update/uninstall flows in isolated temp homes and projects, drives the TUI through a real PTY, and writes a report to `tmp/live-test-report.json`.
+  No-mock live verification. Clones the real upstream repos, captures raw `SKILL.md` frontmatter and file manifests, runs real install/sync/uninstall flows in isolated temp homes and projects, drives the TUI through a real PTY, and writes a report to `tmp/live-test-report.json`.
 - `npm run test:live:quick`
-  Smaller live matrix for faster iteration while keeping the same no-mock pipeline.
+  A smaller live matrix for faster iteration with the same no-mock pipeline.
 
 ## Legacy Agent Support
 
@@ -286,9 +389,9 @@ Still supported through `--agent <name>`:
 
 - Small shelves
 - Clear provenance
-- Notes that explain the keep
+- Notes that explain why something stays
 - Upstream repos staying upstream
-- A library that looks maintained
+- A library that looks cared for
 
 ## Contributing