ai-agent-skills 3.5.0 → 4.0.0

package/README.md

@@ -1,43 +1,62 @@
-# AI Agent Skills
+<h1 align="center">AI Agent Skills</h1>
 
-My curated agent skills library.
+<p align="center">
+  <strong>My curated library of agent skills, plus the package to build your own.</strong>
+</p>
 
-There are a lot of skills now. These are the ones I actually keep around.
+<p align="center">
+  The skills I actually keep around, organized the way I work.
+</p>
 
 <!-- GENERATED:library-stats:start -->
-- 55 skills total
-- 5 shelves
-- 8 house copies
-- 47 cataloged upstream
+<p align="center">
+  <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>
+</p>
+
+<p align="center"><sub>8 house copies · 47 cataloged upstream</sub></p>
 <!-- GENERATED:library-stats:end -->
 
-The point is not to be a registry. The point is to be a bookshelf.
+<p align="center"><em>Picked, shelved, and maintained by hand.</em></p>
 
-## What This Is
+## 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` now does two jobs.
 
-The library is organized the way I actually work:
+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.
+
+The bundled library is organized the way I work:
 
 - Start with a shelf like `frontend` or `workflow`
-- See a small set of vetted skills, not every possible match
-- Keep provenance visible so upstream repos stay credited
-- Keep editorial notes visible so the curation is the product
+- Keep the set small enough to browse quickly
+- 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.
+
+## What's New in 4.0.0
 
-If you want the broad open ecosystem, use `skills.sh`.
-If you want my shelves, use this repo.
+- 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
+- Dependency-aware installs with `requires` and `--no-deps`
+- Installed-state visibility across the CLI and the TUI
 
-## Why This Repo Still Exists
+## Why Keep It
 
 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 universal installer. That part still works.
+Originally this repo was that installer. That part still matters.
 
-What makes it worth keeping now is the library itself: the shelves, the provenance, and the editorial judgment. `skills.sh` is the broad open ecosystem. This repo is the smaller personal library I actually reach for.
+I keep it because the library itself has become useful: shelves, provenance, and notes that make the curation legible.
 
-## The Two-Tier Model
+## How It Works
 
-Every skill in the library is one of two things:
+Each skill here is either a house copy or a cataloged upstream pick.
 
 - `House copies`
   Local folders under `skills/<name>/`.
@@ -47,10 +66,12 @@ Every skill in the library is one of two things:
   Metadata in `skills.json` with no local folder.
   These stay upstream and install live from the source repo when you ask for them.
 
-The library stays lean because it does not pretend to own upstream content.
+Upstream work stays upstream. That keeps the library lean.
 
 ## Quick Start
 
+### Use The Bundled Library
+
 ```bash
 # Open the terminal browser
 npx ai-agent-skills
@@ -84,16 +105,54 @@ Default install targets:
 
 Legacy agent-specific targets still work through `--agent <name>`.
 
-## How To Read The 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
+npx ai-agent-skills add frontend-design --area frontend --branch Implementation --why "I want this on my shelf."
+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 now part of the main product surface.
+
+Start with a managed workspace, pull in a few skills, then keep your own shelves current with `add`, `catalog`, `vendor`, `sync`, and `build-docs`.
 
-There are two main ways to browse it:
+```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 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:
 
 | View | Why it exists | Start here |
 | --- | --- | --- |
 | 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` |
 
-Secondary surfaces still exist, but they are not the main taxonomy:
+The other views are still there. They are just secondary:
 
 - `npx ai-agent-skills browse` for the TUI
 - `npx ai-agent-skills list --collection my-picks` for a cross-shelf starter stack
@@ -102,7 +161,7 @@ Secondary surfaces still exist, but they are not the main taxonomy:
 
 ## Shelves
 
-These are the shelves. They are the product.
+The shelves are the main structure.
 
 <!-- GENERATED:shelf-table:start -->
 | Shelf | Skills | What it covers |
@@ -118,22 +177,25 @@ The full map lives in [WORK_AREAS.md](./WORK_AREAS.md).
 
 ## Collections
 
-Collections still exist, but they are secondary. They can be starter stacks or installable packs, but shelves are still the main taxonomy.
+Collections are smaller sets. Useful, but secondary to the shelves.
 
 <!-- GENERATED:collection-table:start -->
 | Collection | Why it exists | Start here |
 | --- | --- | --- |
-| `my-picks` | The smallest cross-shelf starter stack: the skills I would reach for first on a fresh setup. | `frontend-design`, `mcp-builder`, `pdf` |
-| `build-apps` | Frontend and design implementation skills for shipping polished product work. | `frontend-design`, `frontend-skill`, `shadcn` |
-| `swift-agent-skills` | A curated Swift and Apple-platform hub inside ai-agent-skills, collecting the main upstream Swift skills as one installable set. | `swiftui-pro`, `swiftui-ui-patterns`, `swiftui-design-principles` |
-| `build-systems` | Architecture, MCP, backend, and security picks for deeper engineering work. | `mcp-builder`, `backend-development`, `database-design` |
-| `test-and-debug` | The shelf for QA, regression, CI cleanup, observability, and debugging discipline. | `playwright`, `webapp-testing`, `gh-fix-ci` |
-| `docs-and-research` | File-heavy work, writing, docs, and research flows that end in something usable. | `pdf`, `doc-coauthoring`, `docx` |
+| `my-picks` | A short starter stack. These are the skills I reach for first. | `frontend-design`, `mcp-builder`, `pdf` |
+| `build-apps` | Frontend, UI, and design work for shipping polished apps. | `frontend-design`, `frontend-skill`, `shadcn` |
+| `swift-agent-skills` | The main Swift and Apple-platform set in this library. Install it all at once or pick from it. | `swiftui-pro`, `swiftui-ui-patterns`, `swiftui-design-principles` |
+| `build-systems` | Backend, architecture, MCP, and security work. | `mcp-builder`, `backend-development`, `database-design` |
+| `test-and-debug` | QA, debugging, CI cleanup, and observability. | `playwright`, `webapp-testing`, `gh-fix-ci` |
+| `docs-and-research` | Docs, files, research, and writing work. | `pdf`, `doc-coauthoring`, `docx` |
 <!-- GENERATED:collection-table:end -->
 
-## Catalog Curation
+## Curating The Catalog
+
+Use `catalog` when you want to add an upstream skill without vendoring it.
 
-The `catalog` command is how I pull from upstream repos without vendoring everything.
+In a managed workspace, `add` is the simpler front door.
+`catalog` and `vendor` are still the explicit power-user verbs.
 
 ```bash
 npx ai-agent-skills catalog openai/skills --list
@@ -143,15 +205,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
 ```
 
-That command does not copy the upstream skill into this repo.
-It adds metadata and editorial 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 fast loop:
+For existing picks, `curate` is the quick loop:
 
 ```bash
 npx ai-agent-skills curate frontend-design --branch Implementation
@@ -161,7 +223,7 @@ npx ai-agent-skills curate frontend-design --why "A stronger note that matches h
 npx ai-agent-skills curate review
 ```
 
-When I explicitly want a new house copy, `vendor` is the only path that does it:
+When I want a local copy, I use `vendor`:
 
 ```bash
 npx ai-agent-skills vendor <repo-or-path> --skill <name> --area <shelf> --branch <branch> --why "Why this deserves a local copy."
@@ -170,7 +232,7 @@ npx ai-agent-skills vendor <repo-or-path> --skill <name> --area mobile --branch
 
 ## Source Repos
 
-Current source mix:
+Current upstream mix:
 
 <!-- GENERATED:source-table:start -->
 | Source repo | Skills |
@@ -204,8 +266,8 @@ Current source mix:
 | `vanab/swiftdata-agent-skill` | 1 |
 <!-- GENERATED:source-table:end -->
 
-The two major upstream publishers in this library are Anthropic and OpenAI.
-I do not import everything they ship. I browse, pick, and shelve.
+The two biggest upstream publishers in this library are Anthropic and OpenAI.
+I browse, pick, and shelve. I do not mirror everything they publish.
 
 ## Commands
 
@@ -234,7 +296,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
@@ -250,18 +312,16 @@ npx ai-agent-skills vendor <repo-or-path> --skill <name> --area <shelf> --branch
 
 ## Testing
 
-There are two layers on purpose:
-
 - `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.
 
 ## Legacy Agent Support
 
-These still work through `--agent <name>`:
+Still supported through `--agent <name>`:
 
 - `claude`
 - `cursor`
@@ -276,19 +336,17 @@ These still work through `--agent <name>`:
 - `kilocode`
 - `project`
 
-## Why It Feels Different
-
-This repo is opinionated on purpose.
+## What I Care About
 
-- Small shelves beat giant taxonomies
-- Editorial notes beat anonymous tags
-- Provenance should stay visible
-- Upstream repos should stay upstream
-- A curated library should feel maintained, not harvested
+- Small shelves
+- Clear provenance
+- Notes that explain the keep
+- Upstream repos staying upstream
+- A library that looks maintained
 
 ## Contributing
 
-This is a curated library, not an open registry.
+This is a curated library.
 
 Read [CURATION.md](./CURATION.md) before opening a PR.