@gpambrozio/paseo-skills 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+Notable changes to `skills`. The other plugins in this repository version separately.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the version numbers
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Every version is published to npm
+as `@gpambrozio/paseo-skills` and tagged here, so a version is something to install and a line to
+read before you move.
+
+## [0.1.2] — 2026-09-19
+
+### Added
+
+- **Installs from npm.** On Paseo 0.9 and newer,
+  `paseo plugin install npm:@gpambrozio/paseo-skills` fetches the plugin from the npm
+  registry — no clone, no repository path to remember. Installing from this repository keeps
+  working, and nothing about what the plugin does has changed.
+
+## [0.1.1] — 2026-09-16
+
+### Fixed
+
+- **The Skills pill is back above the composer.** It vanished on Paseo 0.8.0, which changed the way
+  a plugin adds one. Nothing else about it has changed: it still counts what the panel will list,
+  and pressing it still opens that agent's skills. ⌘K and **Skills** worked throughout, if you need
+  the panel before you update.
+
+## [0.1.0] — 2026-09-08
+
+The first numbered release. The plugin itself is older than this entry — it simply had no version
+until now, so everything it does is listed here rather than split across releases it never had. See
+the git history for how each part arrived.
+
+### Added
+
+- **A Skills pill above an agent's composer**, badged with how many skills that agent can use. Press
+  it for the full list. ⌘K and **Skills** reaches the same panel, with a workspace tab holding an
+  agent in focus.
+- **Every skill the agent can actually use, grouped by where it comes from** — the project, the
+  repository, your personal folder, your machine, or a plugin — so two skills with the same name are
+  told apart by origin rather than guessed at. A search box filters by name and description.
+- **What a skill actually says.** Opening one shows its description, the file it lives in, and its
+  full instructions as written. **Copy path** takes the location, for when you want to edit it.
+- **Invoke, with optional arguments.** Runs the skill on the agent you opened the panel from, and
+  takes you to that agent so you can watch it work. A double press cannot send it twice.
+- **Skills the agent can use but you cannot run yourself** are listed with a note saying so, instead
+  of a button that would not have worked.
+- **Works with every provider.** Claude and Codex additionally have their skill files read from
+  disk, which is what gives a skill its origin, its location, and its full text; every other
+  provider lists what its running session reports — a name, a description, and an argument hint.
+- **Requires Paseo 0.8.0 or newer**, on the computer running the daemon *and* on whatever you view
+  the panel in. On anything older the plugin reports itself as incompatible rather than half
+  working.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Ambrozio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# paseo-skills
+
+A Paseo plugin that lists the agent skills available to an agent session, shows where each one
+comes from, renders its `SKILL.md`, and invokes it.
+
+Works with every provider. Claude and Codex additionally get their skill files scanned off disk,
+which is what gives a skill a source, a path, and a rendered body; every other provider shows what
+its running session reports.
+
+## Install
+
+Requires the [Paseo](https://paseo.sh) CLI and a running daemon, both **0.8.0 or newer** — as well
+as the app you view the panel in, which checks the version itself.
+
+```bash
+paseo plugin install npm:@gpambrozio/paseo-skills
+```
+
+That is the shortest route on **Paseo 0.9 or newer**, which installs plugins straight from npm; add
+`@<version>` to pin one. On 0.8, install from this repository instead:
+
+```bash
+paseo plugin add gpambrozio/paseo-plugins --path skills
+```
+
+This repository holds five plugins, hence `--path`. The daemon clones it under `$PASEO_HOME/plugins`
+and runs no package manager — the plugin is source only, and everything it imports at runtime the
+host provides. Pin a release with `--ref <tag>`; later, `paseo plugin status` and
+`paseo plugin update skills` follow the branch.
+
+To hack on it instead, install from a clone of your own:
+
+```bash
+git clone https://github.com/gpambrozio/paseo-plugins.git
+cd paseo-plugins/skills
+npm install
+npm run typecheck && npm test
+paseo plugin install "$PWD"
+```
+
+`install` records the directory, so keep that clone where it is — the daemon loads the plugin from
+that path every time it starts. `npm install` is for the typecheck and the tests; installing needs
+none of it.
+
+The daemon needs `"pluginsEnabled": true` in its `config.json`. Run `paseo reload` after changing
+it. Plugin code is trusted and unsandboxed: the server half reads the daemon machine's filesystem
+and the client half runs inside the Paseo app. Read the source before installing this or any other
+plugin.
+
+## Use
+
+Press the **Skills** pill above an agent's composer — its badge counts what the panel will list.
+The Command Center reaches the same panel: focus a workspace tab holding an agent, press ⌘K, and
+pick **Skills**.
+
+## Demo
+
+
+
+https://github.com/user-attachments/assets/cbb0166e-d981-4367-a5b4-5b12d2e7c14c
+
+
+
+## Develop
+
+```bash
+npm test                     # vitest, resolvers only
+npm run typecheck
+paseo plugin reload skills   # after any source change
+paseo plugin logs skills     # load errors and stderr
+```
+
+A failed reload stays failed; Paseo does not restore the previous code.
+
+## Layout
+
+| File                                | Owns                                                       |
+| ----------------------------------- | ---------------------------------------------------------- |
+| `index.client.tsx`                  | Client wiring: the panel, the Command Center item, the pills. |
+| `index.server.ts`                   | Server wiring: the two RPC handlers.                        |
+| `shared/skills.ts`                  | zod RPC contracts, imported by both runtimes.               |
+| `server/skills.ts`                  | RPC handlers; resolves the agent, dispatches by provider.   |
+| `server/resolve/claude.ts`          | Claude project, repository, personal, and plugin skills.    |
+| `server/resolve/codex.ts`           | Codex project, repository, personal, and admin skills.      |
+| `server/resolve/repo-root.ts`       | Walks up for `.git`, and lists the directories in between.  |
+| `server/resolve/skill-directory.ts` | Scans one `skills` directory, and a whole search path.      |
+| `server/resolve/skill-entry.ts`     | Entry types, skill id construction, first-wins dedupe.      |
+| `server/resolve/frontmatter.ts`     | `SKILL.md` frontmatter parsing.                             |
+| `server/resolve/reported.ts`        | Splits session-reported entries discovery did not find.     |
+| `client/panel.tsx`                  | The panel: list, search, detail, invoke.                    |
+| `client/pill.tsx`                   | The composer pill and the registration loop that owns it.   |
+| `client/skills-query.tsx`           | The `skills.list` query the panel and the pill share.       |
+
+`docs/design.md` records why it is shaped this way. Read it before changing discovery.
+
+## License
+
+MIT — see [LICENSE](LICENSE).