skills-atlas-cli 0.1.0 → 0.1.2

package/README.md

@@ -1,58 +1,96 @@
 # skills-atlas-cli
 
-Search, install and learn AI agent skills from the terminal — powered by the
-[Skills Atlas](https://zita-go.github.io/Skills-Atlas/) catalog (hundreds of
-Claude Code / Codex skills across 100+ source repos).
+[![npm](https://img.shields.io/npm/v/skills-atlas-cli)](https://www.npmjs.com/package/skills-atlas-cli)
+[![license](https://img.shields.io/npm/l/skills-atlas-cli)](https://github.com/Zita-Go/Skills-Atlas/blob/main/LICENSE)
+
+**Stop guessing which agent skill to use.** Find, install, and learn the right
+specialized skill for the task — in seconds, straight into Claude Code.
+
+Powered by the [**Skills Atlas**](https://zita-go.github.io/Skills-Atlas/) catalog:
+hundreds of Claude Code / Codex skills across 100+ source repos, organized by what
+they actually do.
+
+<img src="https://raw.githubusercontent.com/Zita-Go/Skills-Atlas/main/docs/cli-demo.png" alt="skills-atlas: search then install a skill" width="760">
+
+## 🌐 Browse the whole catalog online
+
+<table>
+<tr>
+<td><a href="https://zita-go.github.io/Skills-Atlas/"><img src="https://raw.githubusercontent.com/Zita-Go/Skills-Atlas/main/docs/screenshot-light.png" alt="Skills Atlas — light theme" width="400"></a></td>
+<td><a href="https://zita-go.github.io/Skills-Atlas/"><img src="https://raw.githubusercontent.com/Zita-Go/Skills-Atlas/main/docs/screenshot-dark.png" alt="Skills Atlas — dark theme" width="400"></a></td>
+</tr>
+</table>
+
+**[→ zita-go.github.io/Skills-Atlas](https://zita-go.github.io/Skills-Atlas/)** —
+explore by category, then install what you find with the CLI.
+
+## Install
 
 ```bash
-npx skills-atlas-cli search seo
-npx skills-atlas-cli install brainstorming --global
+npm install -g skills-atlas-cli      # adds the `skills-atlas` command (alias: `sa`)
 ```
 
-Zero runtime dependencies. The catalog snapshot ships with the package and works
-offline; `update` refreshes it from the public feed.
+Or run it without installing: `npx skills-atlas-cli search seo`
 
-## Commands
+## Usage
 
-```text
-skills-atlas <command> [args]
-
-search <query>     find skills      (-c category, -p persona, -t type, --chain, --limit, --json)
-info <skill>       description, usage guidance, sources & install command   (--json)
-install <skill>    download the skill folder into .claude/skills/
-                     -g/--global (default ~/.claude/skills)  --project (./.claude/skills)
-                     -s/--source <id>  -f/--force  -y/--yes  --dry-run  --json
-update             refresh the catalog from the public data feed
-categories         list the top-level categories
-list [category]    list skill groups (optionally within one category)
-
-global flags: --en (English output), --json, -h/--help
+```bash
+# 🔍 Find a skill
+skills-atlas search seo                        # keyword, ranked by relevance + stars
+skills-atlas search "pdf 翻译"                  # multiple words & loose phrases work
+skills-atlas search test --chain -c marketing  # filters: --chain, -c/-p/-t
+
+# 📖 Learn what it does + when to use it
+skills-atlas info brainstorming
+
+# 📥 Install it (into .claude/skills/)
+skills-atlas install brainstorming             # → ~/.claude/skills/   (default, all projects)
+skills-atlas install brainstorming --project   # → ./.claude/skills/   (this project only)
+skills-atlas install brainstorming --dry-run   # preview the files, write nothing
+
+# 🗂️ Browse & refresh
+skills-atlas categories                        # the 20 top-level categories
+skills-atlas list marketing                    # skill groups within a category
+skills-atlas update                            # pull the latest catalog
 ```
 
+Output is English by default; add `--zh` for Chinese, or `--json` to any command for machine-readable output.
+After installing a skill, start a new Claude Code session to load it.
+
 ## How install works
 
-Every skill in the catalog records the **exact in-repo path** of its `SKILL.md`.
-`install` reads that, lists the skill's folder via one GitHub API call, then
-downloads each file (preserving subfolders) into `<target>/.claude/skills/<skill>/`.
+The real value is the **catalog**: `search` / `info` / `categories` work fully
+offline and map *which* skill fits — function-organized, bilingual, tagged with
+use-case / when-to-use / personas / ⛓ chains. That's what `npx skills add` and
+GitHub search don't give you.
 
-- Unlike `git clone`, it fetches **only that skill's folder**, not the whole repo.
-- If a skill has several sources, the best installable one is auto-picked
-  (pass `--source <id>` to choose); use `--yes` for non-interactive runs.
-- Some sources are whole-repo / marketplace / CLI installers with no per-skill
-  folder — for those, `install` prints the exact command to run (e.g.
-  `npx skills add owner/repo`, `/plugin marketplace add owner/repo`).
-- Set `GITHUB_TOKEN` to raise the GitHub API rate limit (60/h → 5000/h).
+On top of that, `install` can place a skill straight into `.claude/skills/`:
 
-After installing, start a new Claude Code session to load the skill.
+- For a repo that exposes a **per-skill folder**, it downloads only that folder
+  (via the repo archive — **no GitHub API rate limit**) into
+  `<target>/.claude/skills/<skill>/`, not the whole repo.
+- Several sources? The best installable one is auto-picked — `--source <id>` to
+  choose, `--yes` for non-interactive runs.
+- Other sources (whole-repo / marketplace) print their official command instead
+  (e.g. `npx skills add owner/repo`).
+- `GITHUB_TOKEN` is only needed if you fall back to the API and hit its 60/h limit.
 
-## Data
+## Keeping the catalog fresh
 
-Offline-first. The bundled snapshot is `data.json` (built from the canonical
-`docs/data.json`). `update` caches a fresh copy under
-`~/.cache/skills-atlas/` (or `$XDG_CACHE_HOME`).
+The catalog ships inside the package and works offline. `skills-atlas update` pulls
+the latest from the public feed (cached under `~/.cache/skills-atlas/`).
 
 ## In Claude Code
 
-See [`plugin/`](./plugin) for a thin Claude Code plugin that exposes
-`/skills-atlas:skill-search`, `:skill-info`, and `:skill-install` so Claude can do
-all of this in-conversation.
+A thin [Claude Code plugin](./plugin) lets Claude do all of this in-conversation —
+just describe what you need, or use `/skills-atlas:skill-search`, `:skill-info`,
+`:skill-install`:
+
+```text
+/plugin marketplace add Zita-Go/Skills-Atlas
+/plugin install skills-atlas@skills-atlas
+```
+
+## License
+
+MIT. Each installed skill keeps its own source repository's license.

package/bin/skills.js

@@ -22,7 +22,7 @@ commands:
   categories         list the top-level categories
   list [category]    list skill groups (optionally within one category)
 
-global flags: --en (English output), --json (machine output), -h/--help
+global flags: --zh (中文 output; English by default), --json (machine output), -h/--help
 docs: https://zita-go.github.io/Skills-Atlas/`;
 
 async function main() {