@qvac/skills 0.0.0 → 0.1.1

package/skills/presentations/references/edit.md

@@ -0,0 +1,314 @@
+# Editing an Existing Deck (python-pptx)
+
+Editing means opening the deck that already exists and changing only what the
+user asked for.
+
+**The first line of an edit is always `Presentation("<staged path>")`.** A bare
+`Presentation()` is only ever for a brand-new deck — it opens the bundled blank
+template, not the user's file, so retyping the slides regenerates their text and
+throws away the original content and design. A rebuilt deck is a failed turn.
+Stage the deck as an input by its real `attachmentId` and open **that staged
+file**. If no attachment id for the deck is available, ask the user to attach it
+again.
+
+## Staging the deck
+
+The id comes from wherever the deck entered the chat: the `exec` result that
+delivered it, or — for a deck the **user uploaded** — the `[Attached file …]`
+line on their message, which names every non-image upload:
+
+```
+[Attached file "quarterly.pptx" (application/vnd.openxmlformats-officedocument.presentationml.presentation) — attachmentId: 4f9c2ab1]
+```
+
+Copy that id verbatim — never placeholders like `att_deck` or any id you made
+up. A `.pptx` is never staged id-less: the id-less form resolves to an uploaded
+*image*, so it cannot reach a deck. An attachment from an earlier turn can be
+used when its attachment id is available in the conversation — from a tool
+result or an `[Attached file …]` line. Otherwise, ask the user to attach the
+file again.
+
+## Read first, then edit
+
+**An edit that writes new prose is two `exec` calls, in this order:** a **read**
+that stages the deck, prints what is on the slides and declares **no `outputs`**;
+then the **edit** that stages the same deck, makes the change and declares the
+output.
+
+The read has to be its own call, because one call cannot inform itself. The words
+you put on a new slide are in the source you submit — fixed before the program
+runs — so a `print` in that same program reports the deck back to you only after
+the slide was already written and saved. A single call can still *compute*
+against the deck (`prs.slides[1].slide_layout`, `len(prs.slides)`), because that
+is code the runtime evaluates against the real file. What it cannot do is let you
+**write** from what the deck says.
+
+A mechanical edit needs no read: a font size, a colour, a slide whose text the
+user already gave you. Read first when the new text has to agree with the deck —
+a conclusion, a summary, a "what changed" slide — and go straight to the edit
+when it does not.
+
+Still forbidden, and unchanged: an `exec` opened *after* the deck is delivered to
+check what you sent. The result you already hold is the whole account of that
+run — that is the loop `Success = stop` closes.
+
+The read call declares **no `outputs`** — it builds nothing, it only reports:
+
+```json
+{
+  "language": "python",
+  "packages": ["python-pptx==1.0.2"],
+  "inputs": [{ "attachmentId": "<id of the deck in this chat>", "path": "deck.pptx" }],
+  "maxOutputChars": 24000,
+  "command": "..."
+}
+```
+
+`maxOutputChars` raises the stdout cap so the whole deck comes back in one
+result — without it stdout is capped at 8 KB. Keep the sample's 24000 (the cap's
+maximum is 65536). A build call prints one line and never needs it.
+
+The edit call is the one that builds, and there is **exactly one** of those:
+
+```json
+{
+  "language": "python",
+  "packages": ["python-pptx==1.0.2"],
+  "inputs": [{ "attachmentId": "<id of the deck in this chat>", "path": "deck.pptx" }],
+  "outputs": ["deck-v2.pptx"],
+  "command": "..."
+}
+```
+
+- `packages` — pin exactly `python-pptx==1.0.2` on every call; an unpinned
+  install resolves a potentially different library version. This exact version
+  ships with the app and installs with no network; any other version has to be
+  downloaded, which fails on a device that is offline.
+- `inputs` — the staged deck. Paths must be unique bare filenames; staged files
+  land in the working directory under those names — reference
+  `Presentation("deck.pptx")` by that name only.
+- `outputs` — the file to deliver. A file you write but do not declare here is
+  discarded. Omit on a read call — a read builds nothing.
+- `command` — the multi-line Python source, with real newline characters. Never
+  collapse it to one line joined by `;` — a `for`/`if`/`with` after a semicolon
+  is a `SyntaxError`.
+
+Both stage the same deck by the same `attachmentId`: the working directory is
+fresh on every call, so the read leaves nothing behind for the edit to reuse.
+
+Name the output after the deck you opened: keep its stem and bump a version —
+`deck.pptx` → `deck-v2.pptx`, and an edit of that one → `deck-v3.pptx`. The
+shared stem reads as one document's history in the chat, and the new name leaves
+the version you opened still openable. Never overwrite the staged input.
+
+## The read call
+
+The read call's whole program is the loop — layout name and every line, so the
+edit that follows can be written against real content:
+
+```python
+from pptx import Presentation
+
+prs = Presentation("deck.pptx")       # the staged input — never Presentation()
+for index, slide in enumerate(prs.slides):
+    lines = [s.text_frame.text.replace("\n", " ") for s in slide.shapes if s.has_text_frame]
+    print(f"{index}: [{slide.slide_layout.name}] {' | '.join(lines)}")
+```
+
+The `replace` is load-bearing: a multi-paragraph body embeds `"\n"` between its
+bullets, and an embedded newline would split one slide across several printed
+lines. Flattened, every printed line is exactly one slide, starting with its
+index and layout name.
+
+It saves nothing and declares no `outputs`. Read its result before writing the
+edit: the layout names decide which layout the new slide copies, and the lines
+decide what it can truthfully say.
+
+**Read the deck before you write into it.** New content has to agree with what
+is already on the slides, and you cannot write a conclusion, a summary, or a
+"what changed" slide from the titles alone — the titles are headings, and the
+substance is in the bodies underneath them. Loop every slide and print every
+shape with `shape.has_text_frame` in the **read** call, then write the edit
+against what came back. A slide written from titles only reads as though it
+belongs to a different deck: it restates the headings, invents specifics the
+deck never claimed, and contradicts the bullets it is supposed to close.
+
+Read through `slide.shapes` **only**. `slide.placeholders` is not a second place
+to look — every placeholder is already in `slide.shapes`, the same shape reached
+by a narrower door, so looping both prints the whole deck twice and doubles what
+you have to read back. Nor can you dedupe your way out of it: python-pptx builds
+a fresh wrapper on each access, so the title reached through `shapes` and the
+title reached through `placeholders` are `==`-distinct objects over one XML
+element — `in`, `is` and `set()` all fail to spot the repeat. One loop over
+`slide.shapes`, guarded by `shape.has_text_frame`, is the whole read.
+
+Print `slide.slide_layout.name`, never the layout object — `print(slide.slide_layout)`
+gives `<pptx.slide.SlideLayout object at 0x…>`, which tells you nothing and leaves
+the layout choice to guesswork. The name is the template's own label, like
+`Title Slide`, `Title and Content`, or `Section Header`.
+
+That same read locates the slide to change: match on the text you printed, and
+edit through the shape you matched. python-pptx has no API to delete or reorder
+slides — say so instead of hacking at the XML.
+
+## The edit call
+
+The edit call then opens the same staged file, changes it in place, and saves
+under the versioned name — never over the staged input:
+
+```python
+from pptx import Presentation
+from pptx.util import Pt
+from pptx.dml.color import RGBColor
+
+prs = Presentation("deck.pptx")       # the staged input — never Presentation()
+before = len(prs.slides)
+
+# Retitle the first slide in place — every other shape keeps its text
+title = prs.slides[0].shapes.title
+title.text = "Why the Sky Is Blue — Revised"
+title.text_frame.paragraphs[0].font.size = Pt(44)
+
+# Recolor existing text through its paragraph font
+first_body = prs.slides[1].placeholders[1].text_frame
+first_body.paragraphs[0].font.color.rgb = RGBColor(0x1A, 0x73, 0xE8)
+
+# One new slide, on the layout a comparable BODY slide uses — never the cover's
+model = prs.slides[1]                 # a content slide; slide 0 is usually the cover
+slide = prs.slides.add_slide(model.slide_layout)
+slide.shapes.title.text = "What Changed"
+tf = slide.placeholders[1].text_frame
+tf.word_wrap = True
+tf.text = "One new closing slide, nothing else touched"
+tf.paragraphs[0].font.size = Pt(20)
+
+prs.save("deck-v2.pptx")              # the declared output — not deck.pptx
+print(f"{before} -> {len(prs.slides)} slides")
+```
+
+**Reuse the deck's own layout — never the blank one.** `prs.slide_layouts[…]`
+indexes the *template's* layout list, and on an uploaded deck those indices mean
+whatever that template says; a slide's own `.slide_layout` is the layout it is
+already built on, so passing that to `add_slide` gives the new slide the same
+placeholders, fonts, colours and positions as its neighbours. Choose the index
+by reading the deck — pick the existing slide that most resembles the one you
+are adding, a content slide for a content slide — and fill the placeholders it
+hands you. The index above is that choice, not a constant: a one-slide deck has
+only `prs.slides[0]`, and `prs.slides[1]` raises `IndexError`.
+
+**Slide 0 is almost always the cover**, on a `Title Slide` layout that owns a big
+centred title and a subtitle and nothing else. Copying *that* layout for a
+conclusion produces a second cover page in the middle of the deck — placeholders
+that fit one line, no bullet body, and title styling that shouts. Take the layout
+from a slide that carries real content — typically `Title and Content` — and reach
+for the cover's layout only when you are genuinely adding another cover. Reaching
+for `slide_layouts[6]` (blank) and hand-placing text boxes on a themed deck
+inherits none of the theme and **guarantees a visual mismatch** with the slides
+beside it.
+
+**Every length is a typed length — `Inches(...)`, `Pt(...)` or `Emu(...)`, never
+a bare number** — for every `add_textbox(left, top, width, height)` argument,
+every `add_picture(...)` position and size, and every margin or offset.
+python-pptx reads a bare number as EMU (914400 to the inch), nothing raises, and
+the deck is delivered with text crammed into the top-left corner or a box that
+has no size. Do not tune the numbers — wrap them:
+
+```python
+from pptx.util import Inches
+
+box = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(8), Inches(1.5))
+# NOT add_textbox(1, 1, 8, 2) — that is 8 EMU wide, an invisible box
+```
+
+Size every paragraph you add (`p.font.size = Pt(20)`, as in the sample) — the
+template's body placeholder inherits 28pt, so an unsized paragraph renders far
+larger than intended. Font color goes through `RGBColor` with **RGB in all
+caps** (never `RgbColor`), on a paragraph's font — a paragraph has no `.fill`.
+For the full slide-authoring API — placeholders vs. text boxes, bullets,
+formatting, backgrounds, pictures — load `references/create.md`.
+
+If an image was staged in `inputs`, embed it in **that** single build with
+`slide.shapes.add_picture` — never deliver a deck and then rebuild to add the
+image. Soft-failing (`try`/`except` around the picture) and saving without it
+is a failed turn, not a success.
+
+## Verify the slide count
+
+**Verify an added slide by the slide count.** Print `before` and `after` as the
+sample does, then read the number back: the delta has to be exactly what the user
+asked for — one added slide is `2 -> 3 slides`, and `2 -> 4 slides` means the
+slide got appended twice. A delta that does not match the request is a **failed
+turn to diagnose, not a result to report**: find the second `add_slide` (or the
+one that never ran) and rerun. Note the count can only ever grow, since there is
+no API to delete a slide. This check is about slides you add — an edit that only
+changes text on existing slides leaves the count flat, and that is correct.
+
+That check lives inside the build, so it takes no extra call: the counts come
+from one `print` in the same `exec` that does the edit. A delivered deck is still
+never reopened to "verify" it.
+
+**This is the one exception to `Success = stop`, and it is not a second call.**
+When the edit added slides, `exitCode: 0` plus an attachment cannot tell the
+edit you were asked for apart from one that fired twice or not at all — every
+one of those produces both. Read the before/after count printed by that same
+run before you reply. The fix is a corrected build, never an `exec` opened to
+inspect what was already delivered.
+
+That corrected build goes out under the **next** version: `deck-v3.pptx` after a
+broken `deck-v2.pptx`. The name you already delivered is refused on a second
+attach — `"deck-v2.pptx" was already attached this turn` — so reusing it turns a
+recoverable turn into a dead one. The broken version stays in the chat either
+way, so name the good file in your reply.
+
+## Errors
+
+- `ModuleNotFoundError: No module named 'pptx'` means `packages` was missing or
+  wrong — add `["python-pptx==1.0.2"]` and rerun. Never try to install it.
+- `attachment … not found in this chat` means `inputs` listed an id that is not
+  in this chat (often a copied placeholder like `att_deck`). Re-copy the exact
+  id from the tool result or the `[Attached file …]` line that names the deck;
+  if neither exists, ask the user to attach it again instead of retrying.
+- Every line showing up twice in the read output means the loop walked
+  `slide.shapes` *and* `slide.placeholders`. Placeholders are already shapes, so
+  the second pass re-reads what the first one found. Drop it — one loop over
+  `slide.shapes` is the whole read.
+- A read result ending in `… [truncated]` means the deck outgrew the cap:
+  answer from what came back and say the answer covers the deck up to that
+  point. Do not rerun the read — it prints the same beginning again.
+- A slide count whose delta does not match the request (`2 -> 4 slides` when one
+  slide was asked for) means `add_slide` ran twice, even at `exitCode 0`. Read the
+  printed before/after count before replying — see Verify the slide count.
+- A new slide that does not match the deck around it — different font, size or
+  colour, bullets missing — was added on the blank layout instead of the deck's
+  own. Read a comparable existing slide, pass its `.slide_layout` to `add_slide`,
+  and fill its placeholders.
+- Text crammed into the top-left corner, or a shape with no visible size, means a
+  bare number reached an argument that required a typed length — wrap every
+  position and size in `Inches(...)` / `Pt(...)` / `Emu(...)` and rerun.
+- `cannot import name 'RgbColor' from 'pptx.dml.color'` means the name is wrong —
+  use `RGBColor` (all-caps RGB). Do not catch the ImportError and save anyway.
+- Never pass an absolute path to `save()`.
+- `SyntaxError: invalid syntax` on a one-line `for`/`if` means the source was
+  collapsed — restore multi-line newlines from the sample and rerun. Underscores
+  in names (`text_frame`, not `textframe`) must stay. Do not switch to `python -c`
+  or change the package pin.
+- `outputs declare a .pptx but command does not build one` means the source never
+  calls `Presentation(...).save(...)` — paste the skill sample (edited for content),
+  not a diagnostic `os.listdir` or shell wrapper.
+- On an `AttributeError` from python-pptx the API name is wrong, and on a `TypeError`
+  about missing positional arguments a required argument was left out — fix either
+  against this file's examples. Do not retry the same call, and do not switch to a shell.
+- `AttributeError: 'Slide' object has no attribute 'add_picture'` (or `addpicture`,
+  `add_textbox`, `addtextbox`) means the call skipped `.shapes` — use
+  `slide.shapes.add_picture(...)` / `slide.shapes.add_textbox(...)`, never
+  `slide.add_*`.
+- Never print the deck's bytes or base64 — stdout is capped and the file travels
+  through `outputs`. A build call prints only the before/after slide count line;
+  only a read call prints slide text.
+
+## Finish
+
+When `exitCode` is `0`, `attachments` lists the `.pptx`, and the printed
+before/after count matches the request, stop tool use and answer with one line:
+file name + slide count from stdout. Exactly one successful build `exec` per
+request — the no-`outputs` read attaches nothing and is not that call.

package/skills/presentations/references/read.md

@@ -0,0 +1,127 @@
+# Reading a Deck to Answer in Chat (python-pptx)
+
+When the user asks what an attached `.pptx` *says* — a summary, a question
+answered, specific content pulled out — the deliverable is your reply in the
+chat, not a file. This is a **read request**: one no-`outputs` read call,
+staged by the deck's real `attachmentId`, is the only `exec` of the turn — no
+build call follows it.
+
+**You cannot summarize in the call that reads.** The words in `command` are
+fixed before the program runs, so one call cannot inform itself: any summary
+written into it was written blind — recalled or invented, not read. Python only
+*transports* the slides; the summarizing happens in your reply, after the
+result comes back.
+
+## Staging the deck
+
+The id comes from wherever the deck entered the chat: the `exec` result that
+delivered it, or — for a deck the **user uploaded** — the `[Attached file …]`
+line on their message, which names every non-image upload:
+
+```
+[Attached file "quarterly.pptx" (application/vnd.openxmlformats-officedocument.presentationml.presentation) — attachmentId: 4f9c2ab1]
+```
+
+Copy that id verbatim — never placeholders like `att_deck` or any id you made
+up. A `.pptx` is never staged id-less: the id-less form resolves to an uploaded
+*image*, so it cannot reach a deck. If no attachment id for the deck is
+available anywhere in the chat, ask the user to attach it again — the working
+directory is fresh on every call, so a file from an earlier call is gone unless
+staged again by its id.
+
+## The exec call
+
+The read call declares **no `outputs`** — it builds nothing, it only reports:
+
+```json
+{
+  "language": "python",
+  "packages": ["python-pptx==1.0.2"],
+  "inputs": [{ "attachmentId": "<id of the deck in this chat>", "path": "deck.pptx" }],
+  "maxOutputChars": 24000,
+  "command": "..."
+}
+```
+
+- `packages` — pin exactly `python-pptx==1.0.2`; this exact version ships with
+  the app and installs with no network; any other version has to be downloaded,
+  which fails on a device that is offline.
+- `inputs` — the staged deck, under a unique bare filename; reference
+  `Presentation("deck.pptx")` by that name only.
+- `maxOutputChars` — raises the stdout cap so the whole deck comes back in one
+  result — without it stdout is capped at 8 KB. Keep the sample's 24000
+  (default 8192, max 65536). Only a read call prints slide text.
+- `command` — the multi-line Python source, with real newline characters.
+  Never collapse it to one line joined by `;`.
+
+## The recipe
+
+The read call's whole program is the loop — layout name and every line:
+
+```python
+from pptx import Presentation
+
+prs = Presentation("deck.pptx")       # the staged input — never Presentation()
+for index, slide in enumerate(prs.slides):
+    lines = [s.text_frame.text.replace("\n", " ") for s in slide.shapes if s.has_text_frame]
+    print(f"{index}: [{slide.slide_layout.name}] {' | '.join(lines)}")
+```
+
+The `replace` is load-bearing: a multi-paragraph body embeds `"\n"` between its
+bullets, and an embedded newline would split one slide across several printed
+lines. Flattened, every printed line is exactly one slide, starting with its
+index and layout name.
+
+A bare `Presentation()` opens the bundled blank template, not the user's file —
+the first line is always the staged path. Loop every slide and print every
+shape guarded by `shape.has_text_frame`: the titles are headings, and the
+substance is in the bodies underneath them.
+
+Read through `slide.shapes` **only**. `slide.placeholders` is not a second place
+to look — every placeholder is already in `slide.shapes`, the same shape reached
+by a narrower door, so looping both prints the whole deck twice and doubles what
+you have to read back. Nor can you dedupe your way out of it: python-pptx builds
+a fresh wrapper on each access, so the title reached through `shapes` and the
+title reached through `placeholders` are `==`-distinct objects over one XML
+element — `in`, `is` and `set()` all fail to spot the repeat. One loop over
+`slide.shapes`, guarded by `shape.has_text_frame`, is the whole read.
+
+## Finish: answer in the chat
+
+**A successful read ends tool use.** When the result prints the slides, reply
+with the summary or the answer as chat text. **Scale the reply to the deck**: a
+summary is much shorter than what it summarizes — a handful of slides earns
+three to five sentences, and only a long deck earns sections. Restating every
+slide is not a summary. Do **not**:
+
+- call `exec` again to "re-check", "read more", or read the same deck a second
+  time;
+- build a summary `.pptx` the user never asked for — an unrequested file is a
+  failed turn, not a bonus.
+
+If stdout ends with `… [truncated]`, the deck is longer than the cap: answer
+from what came back and say the answer covers the deck up to that point. Do not
+rerun the read — it prints the same beginning again.
+
+If the user asks for the summary **as a file**, that is a read followed by a
+build: the read call first, then one build call that writes the new deck from
+the slides you actually read. The build call follows `references/create.md` —
+load it; the read still declares no `outputs`.
+
+## Errors
+
+- `ModuleNotFoundError: No module named 'pptx'` means `packages` was missing or
+  wrong — add `["python-pptx==1.0.2"]` and rerun. Never try to install it.
+- `attachment … not found in this chat` means `inputs` listed an id that is not
+  in this chat (often a copied placeholder like `att_deck`). Re-copy the exact
+  id from the tool result or the `[Attached file …]` line that names the deck;
+  if neither exists, ask the user to attach it again instead of retrying.
+- Every line showing up twice in the read output means the loop walked
+  `slide.shapes` *and* `slide.placeholders`. Placeholders are already shapes —
+  drop the second loop; one loop over `slide.shapes` is the whole read.
+- A read result ending in `… [truncated]` means the deck outgrew the cap:
+  answer from what came back — do not rerun the read.
+- `SyntaxError: invalid syntax` on a one-line `for`/`if` means the source was
+  collapsed — restore multi-line newlines from the sample and rerun. Underscores
+  in names (`text_frame`, not `textframe`) must stay. Do not switch to `python -c`
+  or change the package pin.

package/skills/spotify/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: spotify
+description: Play, search, and control music on Spotify — songs, artists, albums, playlists, and playback.
+emoji: 🎵
+tools: [http_request]
+platform: [darwin, linux, win32, ios, android]
+credentials: [spotify_access_token]
+allow_list: [https://api.spotify.com/v1/]
+metadata:
+  {
+    "openclaw":
+      {
+        "requires":
+          {
+            "credentials": ["spotify_access_token"],
+            "credentialChecks":
+              { "spotify_access_token": { "url": "https://api.spotify.com/v1/me" } }
+          }
+      }
+  }
+---
+
+# Spotify
+
+Use `http_request` against `https://api.spotify.com/v1`. The Spotify credential is attached automatically to every `api.spotify.com` request — **never include an `auth` block**. Never invent track/album/artist URIs — search first and copy `uri` from the JSON response.
+
+```json
+{
+  "url": "https://api.spotify.com/v1/search",
+  "method": "GET",
+  "query": { "q": "Radiohead Creep", "type": "track", "limit": 5 }
+}
+```
+
+## Hard rules
+
+- A bare song/artist/album/playlist name is enough — search immediately, take the top match, and tell the user what you picked. Do not ask "which one?" before searching.
+- Always search before playing by name. Play carries URIs only in the JSON `body` (`"uris": ["…"]`), never as query parameters.
+- A bare `PUT /me/player/play` with no body only resumes paused playback — it never plays a requested song. For an album/artist/playlist use `{ "context_uri": "<uri>" }` instead of `uris`.
+- Do not ask about tokens or setup up front. A **401** means Spotify isn't connected (tell the user to run `/connect spotify`). A **404** from `/me/player` means no active device (tell them to open Spotify).
+
+## Recipe: play a song by name
+
+1. Search:
+
+```json
+{
+  "url": "https://api.spotify.com/v1/search",
+  "method": "GET",
+  "query": { "q": "Radiohead Creep", "type": "track", "limit": 5 }
+}
+```
+
+2. Copy `tracks.items[0].uri` into the play body:
+
+```json
+{
+  "url": "https://api.spotify.com/v1/me/player/play",
+  "method": "PUT",
+  "body": { "uris": ["spotify:track:70LcF31zb1H0PyJoS1Sx1r"] }
+}
+```
+
+## Other operations
+
+All paths are under `https://api.spotify.com/v1`.
+
+| Ask             | Method and path                                                         |
+| --------------- | ----------------------------------------------------------------------- |
+| What's playing? | `GET /me/player/currently-playing`                                      |
+| Pause           | `PUT /me/player/pause`                                                  |
+| Resume          | `PUT /me/player/play` (no body)                                         |
+| Next track      | `POST /me/player/next`                                                  |
+| Add to queue    | `POST /me/player/queue` with `query`: `{ "uri": "spotify:track:<id>" }` |
+| My playlists    | `GET /me/playlists`                                                     |
+| Top tracks      | `GET /me/top/tracks` with `query`: `{ "time_range": "medium_term" }`    |
+| Recently played | `GET /me/player/recently-played`                                        |
+| List devices    | `GET /me/player/devices`                                                |
+
+## Notes
+
+- Keep responses small — they truncate past 8KB, and raw JSON burns tokens on small models. Keep `limit` at 5. On playlist/track endpoints request only what you need with `fields` (e.g. `query`: `{ "fields": "items(track(name,artists(name),uri))" }`). Read just the top item unless the user asked for a list.
+- Present results as a short numbered list — track, artist, album, duration — and devices as `1. Name (active/idle)`. Never dump raw JSON to the user.
+- Playback commands return **204 No Content** on success (empty body). A **204** from currently-playing means nothing is playing.
+- **403** with `PREMIUM_REQUIRED` → user needs Spotify Premium. Other **403**s are usually app-scope/Development Mode limits — report and stop.
+- Never print the token or the `Authorization` header, and don't claim a write succeeded without a successful response in this turn.

package/skills/weather/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: weather
+description: Get current weather and short forecasts for cities via wttr.in.
+tools: [http_request]
+platform: [darwin, linux, win32, ios, android]
+allow_list: [https://wttr.in/]
+---
+
+# Weather
+
+Use `http_request` with wttr.in for current conditions and short forecasts (max 3 days). Pick the smallest format — the tool output is fed back as your next prompt.
+
+## Format guide
+
+**Default to `?format=3` for any "what's the weather…?" / "what about …?" / single-location question.** Only escalate to a multi-day form if the user explicitly says "tomorrow", "weekend", "next N days".
+
+- Current / casual → `?format=3` (one line, smallest)
+- Today's forecast → `?1T`
+- Tomorrow / weekend (2 days) → `?2T`
+- Full 3-day forecast → `?T`
+
+Every wttr.in call MUST end in one of these suffixes. **Never call `https://wttr.in/<location>` with no `?…` suffix** — the bare URL returns a multi-kilobyte response that will overflow the context.
+
+```json
+{ "url": "https://wttr.in/London?format=3", "method": "GET" }
+{ "url": "https://wttr.in/New+York?2T", "method": "GET" }
+```
+
+## Notes
+
+- No API key. Spaces in city → `+` (e.g. `New+York`). Ask for the location if missing.
+- **wttr.in caps at 3 days.** If the user asks for "next week" or longer, say so and offer `?T` (3-day grid). Options like `?7`, `format=11`, `num_of_days=` don't exist.
+- Summarize in plain language. Don't claim live weather unless the request succeeded.