@pikku/skills 0.12.64 → 0.12.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.64",
+  "version": "0.12.66",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-addon/SKILL.md

@@ -200,7 +200,10 @@ npx pikku new addon stripe --display-name Stripe --category Payments --dir addon
 ```
 
 **Handed an OpenAPI or Swagger spec?** Don't hand-write the functions —
-`pikku new addon <name> --openapi <spec>` generates one function per operation,
+`pikku new addon <name> --openapi <spec>` generates one function per operation
+(`<spec>` is a path, a URL, or a registry catalogue name such as
+`amazonaws.com:applicationcostprofiler`; inside an app,
+`pikku addons add <catalogue-name>` does the same and picks `--auth` for you),
 with its schemas, service and credential. Read `references/openapi.md`.
 
 This generates `package.json` (exports `.pikku/*` + `dist/`), `pikku.config.json` (`addon: true`), `tsconfig.json` (`#pikku` path mapping), `src/services.ts`, `src/functions/`, and `types/application-types.d.ts`. For the full file contents/exports you rarely hand-edit, read `references/addon-package-manifest.md`.
@@ -421,18 +424,27 @@ export default definePlugin({
   addons only; Studio enforces that). `layout: 'bare'` renders without the shell.
 - Titles are message keys in the addon's `messages/{locale}.json`, found by
   convention next to its `package.json`; there is no field for them.
+- `agent: 'name'` makes that agent answer in Studio's chat panel (a second tab
+  beside the general chat) while the screen is open. It resolves to
+  `agents/<name>.md` at the addon's package root: the agent's instructions,
+  which name the skills it follows (plain folders `skills/<name>/SKILL.md`).
+  `agent: 'studio:<name>'` instead picks an agent Studio ships; `pikku all` only
+  checks the format and looks up no file.
+  The file starts with frontmatter whose `title` and `description` are message
+  keys in `messages/en.json`. The name matches `/^[a-z][a-z0-9-]*$/`.
 - `scopes` only hide the screen. The addon's functions must enforce the same
   scopes.
 
 The inspector reads every field statically, so each must be a literal.
 `pikku all` fails on:
 
-| Code   | When                                                         |
-| ------ | ------------------------------------------------------------ |
-| PKU345 | a field is not a literal (variable, call, spread, bad value) |
-| PKU357 | two screens of the addon use the same path                   |
-| PKU358 | a title key is missing from `messages/en.json`               |
-| PKU359 | `nav.badge` names no function of the addon                   |
+| Code   | When                                                                                                 |
+| ------ | ---------------------------------------------------------------------------------------------------- |
+| PKU345 | a field is not a literal (variable, call, spread, bad value)                                         |
+| PKU357 | two screens of the addon use the same path                                                           |
+| PKU358 | a title or agent frontmatter key is missing from `messages/en.json`                                  |
+| PKU359 | `nav.badge` names no function of the addon                                                           |
+| PKU365 | `agent` is neither a name nor `studio:<name>`, or a name has no non-empty `agents/<name>.md`, or no frontmatter `title` and `description` |
 
 A key missing from another locale's catalog is a warning.
 

package/skills/pikku-addon/references/openapi.md

@@ -11,7 +11,8 @@
 - 6 — Check the spec against the real API
 - Then
 
-When you are handed an OpenAPI or Swagger spec — a file, or a URL to one — the
+When you are handed an OpenAPI or Swagger spec — a file, a URL to one, or the
+name of one in the registry's catalogue (`https://www.pikku.dev/openapis`) — the
 API it describes becomes an addon: one function per operation, each with its
 input and output schemas, behind one service that makes the HTTP calls. Say so
 before starting ("This is an OpenAPI spec — I'll turn it into an addon first"),
@@ -26,7 +27,23 @@ A JSON or YAML document with a top-level `openapi` key (3.x) or `swagger` key
 
 ## 1 — Look at the spec first
 
-`--openapi` takes a path or a URL. A spec published only to signed-in callers
+`--openapi` takes a path, a URL, or a catalogue name such as
+`amazonaws.com:applicationcostprofiler`. A name is anything that is neither a
+URL, a path, nor a `.json`/`.yaml` file; it is looked up in the registry
+(`--registry`, else `pikku.config.json`'s `registry`, else
+`https://api.pikkustudio.app`) and generated from the entry's spec URL. A name
+the registry does not know is refused before anything is written. On the
+website the page URL is a slug (`amazonaws-com-applicationcostprofiler`); the
+name to pass is the one the page's command shows, with its `.` and `:`.
+
+For a catalogue entry inside an app, the short form is
+`pikku addons add amazonaws.com:applicationcostprofiler`. It names the addon
+after the entry (`amazonaws-applicationcostprofiler`) and takes `--auth` from
+what the registry records: `none` for a public API, `user` for OAuth or a key
+each user brings, `shared` for a key the app holds, and `user` when the registry
+does not know. It prints the mode it picked; pass `--auth` to override it.
+
+A spec published only to signed-in callers
 takes the key the way the API reads it: `--openapi-header "NAME: value"`
 (repeatable), or in the URL's query string when the API reads it there
 (Dolibarr's explorer takes `?DOLAPIKEY=`). A 401 while fetching says which.
@@ -40,7 +57,7 @@ Keep a copy in `specs/` as the record of what the addon was generated from.
 ## 2 — Generate, from the app's root
 
 ```bash
-bunx --bun pikku new addon <name> --openapi <path-or-url>
+bunx --bun pikku new addon <name> --openapi <path-url-or-catalogue-name>
 ```
 
 One command. Inside an app it writes `packages/addon-<name>` as