docs: lead Get Started with the Agent, not the human

README.md

@@ -1,10 +1,8 @@
 <h1 align="center">
 <a href="https://skilld.dev"><picture>
-<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/skilld-dev/skilld/main/.github/logos/logo-mark.svg">
-<img alt="" src="https://raw.githubusercontent.com/skilld-dev/skilld/main/.github/logos/logo-mark-light.svg" width="90">
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/skilld-dev/skilld/main/.github/logos/logo.svg">
+<img alt="skilld" src="https://raw.githubusercontent.com/skilld-dev/skilld/main/.github/logos/logo-light.svg" width="220">
 </picture></a>
-<br>
-skilld
 </h1>
 
 <p align="center">
@@ -17,15 +15,17 @@ Open source, privacy friendly Agent Skills, curated by humans.<br>Search, run, i
 <a href="https://github.com/skilld-dev/skilld/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/github/license/skilld-dev/skilld?style=flat&labelColor=1c1917&color=e11d48"></a>
 </p>
 
-<p align="center">
+<div align="center">
 <table>
 <tbody>
+<tr>
 <td align="center">
-<sub>Made possible by my <a href="https://github.com/sponsors/harlan-zw">Sponsor Program 💖</a><br> Follow me <a href="https://twitter.com/harlan_zw">@harlan_zw</a> 🐦 • Join <a href="https://discord.gg/275MBUBvgP">Discord</a> for help</sub><br>
+<sub>Made possible by my <a href="https://github.com/sponsors/harlan-zw">Sponsor Program 💖</a><br> Follow me <a href="https://twitter.com/harlan_zw">@harlan_zw</a> 🐦 • Join <a href="https://discord.gg/275MBUBvgP">Discord</a> for help</sub>
 </td>
+</tr>
 </tbody>
 </table>
-</p>
+</div>
 
 ## Features
 
@@ -52,21 +52,48 @@ Skill authoring lives in visible [skilld-maintained Skills](#author-a-skill) and
 
 ## Get Started
 
-Run a Skill once. You need no install and no project files:
+Give your Agent a Skill URL. There is nothing to install:
+
+> Use this Skill: https://skilld.dev/gh/antfu/skills/vue
+
+Your Agent reads the page and follows it for that session.
+Nothing is written to your project. Add `.md` to any Skill URL for the raw `SKILL.md`.
+
+Find one on [skilld.dev](https://skilld.dev/skills).
+[Trending Skills](https://skilld.dev/skills/trending) shows what is moving this month.
+Every Skill page credits its author and links the source file on GitHub.
+[Curators](https://skilld.dev/community) publish named collections.
+
+### Run it from your terminal
+
+Same transient run, from a shell. You need no install and no project files:
 
 ```sh
 npx skilld search vue
 npx skilld run antfu/skills/vue
 ```
 
 `skilld run` prints `SKILL.md` to stdout and writes no file.
-Ask your Agent to run the command and follow the printed instructions.
-If you run it yourself, pass the output to your Agent.
+Pass the output to your Agent.
 
-Install a Skill only when you want it in every session:
+### Set it up properly
+
+Once a Skill earns its place, install the CLI and teach your Agent to drive it:
 
 ```sh
-npx skilld install antfu/skills/vue
+npm install --global skilld
+skilld install skilld --global
+```
+
+Your Agent then searches the registry and loads Skills on its own.
+Ask for what you need, in your own words:
+
+> Find a skilld Skill for Vue and use it
+
+Keep a Skill in every session of one project:
+
+```sh
+skilld install antfu/skills/vue
 ```
 
 An install writes files. If an Agent runs the install, it asks you first.
@@ -83,24 +110,13 @@ An install writes files. If an Agent runs the install, it asks you first.
 
 Start with `skilld run`. Install when you reach for the same Skill again.
 
-If you use skilld often, install the CLI globally:
-
-```sh
-npm install --global skilld
-```
-
-Teach your Agent the CLI with the skilld-maintained `skilld` Skill:
-
-```sh
-skilld install skilld --global
-```
+### Agent targets
 
-Use `--agent` when you want an explicit Agent target.
-Repeat it for several targets. Use `--agent all` for every known target.
+Use `--agent` to name a target. Repeat it for several, or use `--agent all`.
 `-g` is the short form of `--global`.
 
 ```sh
-skilld install skilld --global --agent codex
+skilld install skilld -g --agent codex
 skilld install skilld -g --agent kiro --agent zed
 skilld install skilld -g --agent all
 ```