ai-agent-skills 4.0.0 → 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

@@ -13,20 +13,26 @@
   <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` now does two jobs.
+`ai-agent-skills` does two things.
 
-It ships my curated bundled library, and it gives you the CLI and TUI to build a managed library of your own.
-It works with Claude Code, Codex, Cursor, and other SKILL.md-compatible agents.
+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:
 
@@ -35,24 +41,24 @@ The bundled library is organized the way I work:
 - Keep provenance visible
 - Keep notes that explain why a skill is here
 
-Use `skills.sh` when you want the broad ecosystem.
-Use `ai-agent-skills` when you want a kept set, shelves, provenance, and a library you can manage yourself.
+Use `skills.sh` for the broad ecosystem.
+Use `ai-agent-skills` when you want a smaller library with shelves, provenance, and notes.
 
 ## What's New in 4.0.0
 
 - 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, with `update` kept as an alias
+- `sync [name]` as the main refresh command; `update` stays as an alias
 - Dependency-aware installs with `requires` and `--no-deps`
-- Installed-state visibility across the CLI and the TUI
+- Installed status in both the CLI and TUI
 
-## Why Keep It
+## 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
 
@@ -64,13 +70,54 @@ 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
+### Use the bundled library
 
 ```bash
 # Open the terminal browser
@@ -82,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
@@ -91,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
@@ -105,15 +152,16 @@ Default install targets:
 
 Legacy agent-specific targets still work through `--agent <name>`.
 
-### Start Your Own Library
+### Start your own library
 
 ```bash
 # Create a managed workspace
 npx ai-agent-skills init-library my-library
 cd my-library
 
-# Add a bundled pick, refresh it, and rebuild the docs
+# 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
@@ -121,15 +169,16 @@ npx ai-agent-skills build-docs
 
 ## Workspace Mode
 
-Workspace mode is now part of the main product surface.
+Workspace mode is part of the normal flow now.
 
-Start with a managed workspace, pull in a few skills, then keep your own shelves current with `add`, `catalog`, `vendor`, `sync`, and `build-docs`.
+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
@@ -152,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
@@ -169,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).
@@ -190,12 +239,12 @@ 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, `add` is the simpler front door.
-`catalog` and `vendor` are still the explicit power-user verbs.
+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
@@ -213,7 +262,7 @@ It adds metadata and placement in the active library:
 - 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
@@ -238,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 |
@@ -317,7 +366,7 @@ npx ai-agent-skills vendor <repo-or-path> --skill <name> --area <shelf> --branch
 - `npm run test:live`
   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
 
@@ -340,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