Create agent skills for each package

packages/diffs/README.md

@@ -27,6 +27,15 @@ JavaScript and React components.
 pnpm add @pierre/diffs
 ```
 
+## Agent skill
+
+Install the agent skill for this package with the
+[Skills CLI](https://skills.sh/docs/cli):
+
+```bash
+npx skills add pierrecomputer/pierre --skill diffs
+```
+
 ## Development
 
 We use pnpm for workspace package management and Bun for tests.

packages/theme/README.md

@@ -45,6 +45,15 @@ Usage:
 
 ```
 
+## Agent skill
+
+Install the agent skill for this package with the
+[Skills CLI](https://skills.sh/docs/cli):
+
+```bash
+npx skills add pierrecomputer/pierre --skill theme
+```
+
 Contributing:
 
 - Development, build, and testing: [CONTRIBUTING.md](CONTRIBUTING.md)

packages/theming/README.md

@@ -68,6 +68,15 @@ pnpm add @pierre/theming
 Add the optional peers only for the entries you use, e.g., `react` for `/react`,
 and `@pierre/theme`, `@shikijs/themes`, and `shiki` for `/themes`.
 
+## Agent skill
+
+Install the agent skill for this package with the
+[Skills CLI](https://skills.sh/docs/cli):
+
+```bash
+npx skills add pierrecomputer/pierre --skill theming
+```
+
 ## Collections and catalogs
 
 The core entry exports two closely-related composition primitives:

packages/trees/README.md

@@ -19,6 +19,15 @@ path strings, not internal numeric IDs.
 pnpm add @pierre/trees
 ```
 
+## Agent skill
+
+Install the agent skill for this package with the
+[Skills CLI](https://skills.sh/docs/cli):
+
+```bash
+npx skills add pierrecomputer/pierre --skill trees
+```
+
 ## Vanilla usage
 
 ```ts

skills/INDEX.md

@@ -0,0 +1,18 @@
+# Pierre package skills
+
+Use these skills when an app or site consumes a Pierre package. Read the
+selected `SKILL.md` first. Load only the API or recipe reference that matches
+the task.
+
+| Skill                       | Use it for                                                                                          |
+| --------------------------- | --------------------------------------------------------------------------------------------------- |
+| [diffs](diffs/SKILL.md)     | Render or edit code files, diffs, patches, and merge conflicts with `@pierre/diffs`.                |
+| [theme](theme/SKILL.md)     | Select and load a Pierre syntax or editor theme from `@pierre/theme`.                               |
+| [theming](theming/SKILL.md) | Build runtime theme collections, resolvers, controllers, and color mappings with `@pierre/theming`. |
+| [trees](trees/SKILL.md)     | Render and control an interactive file tree with `@pierre/trees`.                                   |
+
+## Package relationship
+
+`@pierre/theme` supplies theme objects. `@pierre/theming` selects, resolves, and
+maps those objects. `@pierre/diffs` and `@pierre/trees` render code and file
+trees with the selected theme.

skills/diffs/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: diffs
+description:
+  Use when an app uses @pierre/diffs to render or edit code files, diffs,
+  patches, merge conflicts, or CodeView review surfaces, including React,
+  vanilla JavaScript, SSR, workers, annotations, selection, and custom Shiki
+  languages or themes.
+---
+
+# `@pierre/diffs`
+
+Use `@pierre/diffs` to render syntax-highlighted files and diffs. Use its
+optional editor, SSR, and worker entries for those capabilities.
+
+## Install
+
+```bash
+pnpm add @pierre/diffs
+```
+
+Install `react` and `react-dom` when the app uses the React entry.
+
+## Select an API reference
+
+| Surface                                                      | Reference                                              |
+| ------------------------------------------------------------ | ------------------------------------------------------ |
+| Root components, parsing, and file extension APIs            | [Core API](references/api-core.md)                     |
+| Languages, themes, highlighter state, and streams            | [Highlighting API](references/api-highlighting.md)     |
+| Renderers, managers, DOM helpers, comparisons, and constants | [Low-level rendering API](references/api-rendering.md) |
+| Shared data, option, render, selection, and editor types     | [Shared types](references/api-types.md)                |
+| `@pierre/diffs/react`                                        | [React API](references/api-react.md)                   |
+| `@pierre/diffs/editor`                                       | [Editor API](references/api-editor.md)                 |
+| `@pierre/diffs/ssr`                                          | [SSR API](references/api-ssr.md)                       |
+| `@pierre/diffs/worker` and worker scripts                    | [Worker API](references/api-worker.md)                 |
+
+## Select a recipe
+
+| Task                                | Recipe                                                                   |
+| ----------------------------------- | ------------------------------------------------------------------------ |
+| Render a file or diff in React      | [Render with React](references/recipe-react.md)                          |
+| Render a file or diff without React | [Render with vanilla JavaScript](references/recipe-vanilla.md)           |
+| Build a virtualized review surface  | [Use CodeView](references/recipe-code-view.md)                           |
+| Edit a React surface or CodeView    | [Edit with React](references/recipe-edit-react.md)                       |
+| Edit a vanilla surface or CodeView  | [Edit with vanilla JavaScript](references/recipe-edit-vanilla.md)        |
+| Preload markup on the server        | [Use SSR](references/recipe-ssr.md)                                      |
+| Highlight through a worker pool     | [Use workers](references/recipe-workers.md)                              |
+| Add line annotations and selection  | [Add annotations and selection](references/recipe-annotations.md)        |
+| Register a Shiki language or theme  | [Register custom highlighting](references/recipe-custom-highlighting.md) |