@genspark/cli 1.0.24 → 1.0.26

package/docs/skills.md

@@ -1,6 +1,213 @@
 # GSK CLI Skills Index
 
 > Auto-generated by `python -m backend.genspark_tool_cli.generate_skills`. Do not edit manually.
+>
+> **Exception — the section below.** The `gsk skills <verb>` command group
+> (design: `docs/plans/2026-07-05-gsk-skills-universal-design.md`) is
+> registered behind `requires_gk="gk_skills_cli"`, and the generator skips
+> every gated tool (`generate_skills.py`: `if config.requires_gk: continue`),
+> so these verbs never appear in the auto-generated table below and have no
+> other doc home yet. This section is maintained by hand until that gap is
+> closed; re-running `python -m backend.genspark_tool_cli.generate_skills`
+> overwrites the whole file, so re-add this section if it goes missing.
+
+## `gsk skills` command group
+
+Ten verbs — `list`, `info`, `team`, `install`, `uninstall`, `upgrade`,
+`pull`, `sync`, `save`, `publish` — over the shared `SkillsService` catalog
+(personal / community / team skills). Gated by `gk_skills_cli` (employees +
+mainfunc allowlist during rollout); with the flag off, none of the
+`skills_*` tools are discoverable via `GET /api/tool_cli/tools` and the CLI
+reports them as unknown commands.
+
+Mutating verbs (`install`, `uninstall`, `upgrade`, `save`, `publish`) reject
+agent-principal (DE-runtime) tokens with `FORBIDDEN: agent-principal tokens
+cannot modify user skills` — a caller can only ever mutate its own catalog,
+never another user's. Read/export verbs (`list`, `info`, `team`, `pull`,
+`sync`) carry no such check.
+
+### `pull` vs `sync` — authoring-only vs. runtime materialization
+
+These two verbs look similar (both write a skill's files to local disk) but
+serve opposite purposes and must not be conflated:
+
+- **`pull <ref> [--out <dir>]`** is an authoring/export/debug flow only. It
+  writes one skill's full tree plus a `.genspark-skill.json` provenance
+  sidecar (`{ref, owner, slug, commit, publisher_type, pulled_at,
+  file_count, content_hash}`) so the directory can be identified and
+  refreshed on a later re-pull. It is **never** a runtime consumption or
+  boot path — a sandbox does not `pull` its enabled skills. A refresh
+  (re-pull into a directory that already has the sidecar) that fails
+  mid-write leaves the destination **emptied**, not restored to its prior
+  contents — refresh clears the target first, so the next `pull` rebuilds
+  it from scratch.
+- **`sync [--check] [--store-dir <d>] [--mount-dir <d>]`** is the runtime
+  materialization path: it makes local disk match the caller's *entire*
+  enabled-skill set, incrementally, and is the verb a boot script or agent
+  host runs on every startup.
+
+Put another way: `pull` moves one skill to a place you choose, for editing;
+`sync` moves your whole enabled set to a fixed place, for running.
+
+### `sync` — materialize your enabled skills
+
+`gsk skills sync [--check] [--store-dir <dir>] [--mount-dir <dir>]`
+
+The CLI keeps a local `{slug: sha}` digest map at
+`<storeDir>/skills-sync-state.json` (default store dir: `~/.gsk/skills-store`;
+default mount dir: `~/.opencode/skills`). Each `sync` call sends that digest
+to the server, which diffs it against the caller's enabled-skill set and
+returns only what changed:
+
+- **State file self-heal.** A missing state file, unparseable JSON, OR a
+  valid-JSON-but-wrong-shape map (a non-object, or any entry whose key isn't
+  a valid slug / whose value isn't a string) is treated as an empty `{}`
+  digest, which forces a full re-fetch of every enabled skill on the next
+  `sync` rather than risk skipping a change against state that can't be
+  trusted. The shape check matters because the server rejects the entire
+  sync on a single bad key — without it a corrupt state file would wedge
+  every future `sync`.
+- **Disk-truth re-materialization.** `sync` trusts DISK over the state file:
+  when the server reports a slug `unchanged` (its digest matched) but the
+  slug is no longer materialized on disk — the `<storeDir>/<slug>` dir was
+  hand-deleted, or a state file was restored from backup without its store —
+  the slug is dropped from the digest map so the next `sync` sees a miss and
+  re-fetches it. This keeps the "make local disk match the entire enabled
+  set" contract true even after out-of-band tampering with the store.
+- **Symlink merge rules.** Fetched content lands in
+  `<storeDir>/<slug>/`, written to a sibling temp directory first and then
+  `rename`d into place (never a half-written skill on a dropped
+  connection), then symlinked from `<mountDir>/<slug>`. A stale symlink at
+  the mount path is freely repointed — same outcome as `setup.sh`'s
+  `rm -rf` + `ln -sfn` at sandbox boot. A pre-existing **real** directory at
+  the mount path (an inline-tar built-in skill, or user content), however,
+  is a deliberate **deviation** from `setup.sh`: `setup.sh` unconditionally
+  `rm -rf`s the mount path before symlinking, so the synced skill always
+  wins there. This CLI-side materializer instead never clobbers a real
+  directory it didn't create — the sync reports that slug as failed
+  instead — because it runs against a user's laptop filesystem, not a
+  disposable sandbox. When the mount is refused this way, the fetched
+  content is still **materialized in the store** and its sha is recorded, so
+  the server stops re-sending that slug on every subsequent `sync` — the
+  user sees the "stored but not mounted" warning once per content change,
+  not a re-download each run.
+- **`--check`** reports the diff without writing anything to disk (a dry
+  run / shadow comparison), and sets the process exit code so scripts don't
+  need to parse output: **exit 0** when every entry is `unchanged`, **exit
+  3** when at least one slug would update, be removed, or errored.
+- **Batching.** The server bounds each response to an 8 MiB soft budget
+  (`max_response_bytes`), checked *before* starting a skill's package
+  rather than mid-file — so a single batch can overshoot 8 MiB by up to one
+  skill's package, itself capped at 25 MiB (`per_skill_cap_bytes`). A
+  response with `"complete": false` means more changed skills remain; the
+  CLI calls `sync` again carrying forward the digest state it has applied
+  so far, and repeats until `"complete": true`. The client loop aborts
+  after 20 batches without completing (`exit 1`) as a runaway guard.
+- Idempotent: an immediate second `sync` reports all-`unchanged`, zero
+  writes — including slugs whose mount was refused (their store is already
+  materialized and the sha recorded, so they too report `unchanged` with no
+  re-download).
+- **Exit codes** (a boot script keys off these instead of parsing output):
+  - **0** — fully clean. For a real (non-`--check`) sync every slug was
+    applied/removed/unchanged with zero failures; for `--check`, everything
+    was `unchanged`.
+  - **3** — `--check` only: at least one slug would update, be removed, or
+    errored (a diff exists). No disk writes happened.
+  - **4** — a real sync finished but at least one slug **failed** (mount
+    refused because a real dir occupies the mount path, a write error, or a
+    server `error` row). The rest were applied; this code tells a boot
+    script "some skills didn't materialize" as distinct from a clean run.
+    **Exit 4 is retryable / non-fatal, not a hard failure.** In particular a
+    fresh sandbox whose enabled slug collides with a tar-baked builtin
+    directory exits 4 on its FIRST sync (real-dir-wins → that slug reported
+    `failed`, its content stored-but-not-mounted), then exits 0 on every
+    subsequent sync (the recorded sha suppresses re-sends and the builtin
+    keeps winning) — it self-heals. A symlink-unsupported filesystem
+    (Windows without Developer Mode, exFAT/FAT/SMB — `symlinkSync` throws)
+    is the PERSISTENT variant: the store is downloaded once and never
+    re-downloaded, but the mount can't be created, so that slug stays
+    `failed` and the sync keeps exiting 4 on every run. Both are the same
+    "downloaded but not mounted" condition. A boot-script consumer MUST NOT
+    treat exit 4 as a boot-blocking error: log it and continue.
+  - **1** — the sync loop itself aborted: a mid-loop batch call failed, or
+    it exceeded the 20-batch runaway guard without completing.
+
+### `upgrade` — refresh an installed skill to the latest published version
+
+`gsk skills upgrade <slug>`
+
+Re-pins one installed skill to its publisher's latest version (a team skill
+to the org-**approved** sha, never the author's latest candidate; a curated
+or peer install to the source's current version). Idempotent — an
+already-current skill reports `changed: false`, and a self-authored skill is
+a benign skip (you edit those via `save`, not `upgrade`).
+
+**Local edits are replaced.** If you `pull`ed an installed copy, edited it,
+and `save`d the edits back to that same slug, `upgrade` **overwrites those
+local edits** with the publisher's version — there is no divergence warning
+today. To keep a customized fork, `pull`/`save` it under a **separate slug**
+so `upgrade` on the original never touches your fork.
+
+### `save` — write a local directory back to your catalog
+
+`gsk skills save [path]` (default `path`: current directory)
+
+The sentinel-protocol successor: SAS's retired `.save_to_self` file
+convention told the sandbox host to zip a skill directory and upload it
+out-of-band. `save` reads the directory itself and ships the encoded bytes
+inline — works on any host, including git-less ones.
+
+**Directory contract:**
+
+- A root `SKILL.md` is required; the server rejects a save without one
+  anyway (frontmatter validation), so the CLI fails fast locally.
+- Symlinks are never followed (skipped outright) — a save must not escape
+  the directory or loop on a cyclic link.
+- `node_modules/` and `.git/` directories are never walked or shipped, at
+  any depth — they are never part of a skill, can blow the byte cap on junk,
+  and `.git` would leak history.
+- At the root only, dotfiles are excluded from the upload except
+  `.gitignore` (ordinary authoring content) and the pull provenance sidecar
+  `.genspark-skill.json` (metadata, not a skill file). Dotfiles in
+  subdirectories **are** uploaded (only root-level dotfiles are excluded), so
+  clean any secret files out of subdirectories before `save`.
+- The upload is capped at 25 MiB total (mirrored client- and server-side,
+  so an oversized save fails locally instead of round-tripping first).
+
+**Fork warning.** If the target directory carries a
+`.genspark-skill.json` sidecar (i.e. it was previously populated by `pull`)
+with a recorded `owner`, `save` prints a warning that saving will fork the
+skill into your own catalog — and then proceeds. This warning fires for
+**any** previously-pulled directory, including one that was pulled from
+your *own* catalog: the CLI has no "whoami" to compare the sidecar's owner
+against the caller's identity, so it cannot distinguish "this is someone
+else's skill" from "this is mine, re-pulled." Treat the warning as
+informational, not necessarily a fork.
+
+**Overwrite semantics.** `save` always overwrites the caller's existing
+copy of the resulting slug — there is no separate create-only mode; a
+brand-new slug is a create either way. The response's `outcome` field is
+either `"unchanged"` (identical tree, no-op) or `"updated"` — note that the
+very first save of a slug that doesn't exist yet in the caller's catalog
+also reports `outcome: "updated"`, since `upload_skill_with_outcome` has no
+distinct "created" outcome today.
+
+### Known follow-ups (not fixed in S1)
+
+Tracked here so they're on record; deliberately out of scope for the initial
+`gsk skills` landing:
+
+- **Large payloads are (de)serialized on the event loop.** `pull` / `sync` /
+  `save` bodies are `json.loads`'d in the CLI executor and `json.dumps`'d in
+  the router, and `save`'s request body is parsed on the event loop
+  downstream of the adaptor's own `to_thread` hop. This is a cross-cutting
+  `tool_cli`-infra concern (bounded today by the 25 MiB payload caps and the
+  employee-gated rollout) to be addressed in a shared executor PR, not
+  per-verb here.
+- **`sync --check` prints only the first batch's diff.** A multi-batch diff
+  (`complete: false`) shows only the first batch's per-slug lines in `--check`
+  mode, though the exit code is still correct (3 if anything would change).
+  Full multi-batch `--check` reporting is a follow-up.
 
 **Total skills:** 97
 
@@ -8,7 +215,7 @@
 
 | Skill | Description |
 |-------|-------------|
-| [gsk-aidrive](../skills/gsk-aidrive/SKILL.md) | AI-Drive file storage and management. Actions: ls, mkdir, rm, move, get_readable_url, download_video, download_audio, do |
+| [gsk-aidrive](../skills/gsk-aidrive/SKILL.md) | AI-Drive file storage and management. Actions: ls, find, mkdir, rm, move, get_readable_url, download_video, download_aud |
 | [gsk-analyze-media](../skills/gsk-analyze-media/SKILL.md) | Analyze various types of media content including images, audio, and video. |
 | [gsk-audio-generation](../skills/gsk-audio-generation/SKILL.md) | Generate audio content including TTS, sound effects, and music. |
 | [gsk-audio-processing](../skills/gsk-audio-processing/SKILL.md) | Preprocess audio: remove background noise, extract specific sounds, or enhance quality. |
@@ -92,6 +299,7 @@
 | [gsk-social-twitter](../skills/gsk-social-twitter/SKILL.md) | Search and retrieve data from Twitter/X: posts, users, comments, retweets, and more. |
 | [gsk-stock-price](../skills/gsk-stock-price/SKILL.md) | Retrieve real-time stock price information for a specific company. |
 | [gsk-summarize-large-document](../skills/gsk-summarize-large-document/SKILL.md) | Analyze and answer questions about large documents (PDFs, web pages, Word docs, etc.). |
+| [gsk-task-status](../skills/gsk-task-status/SKILL.md) | Look up an existing task project previously created with create_task: returns its status, page URL (task_url), and extra |
 | [gsk-teams-create-chat](../skills/gsk-teams-create-chat/SKILL.md) | Create a new Microsoft Teams chat. |
 | [gsk-teams-list-channels](../skills/gsk-teams-list-channels/SKILL.md) | List channels in a Microsoft Teams team. |
 | [gsk-teams-list-chats](../skills/gsk-teams-list-chats/SKILL.md) | List recent Microsoft Teams chats. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genspark/cli",
-  "version": "1.0.24",
+  "version": "1.0.26",
   "description": "CLI tool for Genspark Tool API - search, crawl, analyze images, generate media",
   "type": "module",
   "main": "dist/index.js",
@@ -18,6 +18,7 @@
     "build": "tsc",
     "dev": "ts-node src/index.ts",
     "start": "node dist/index.js",
+    "test": "npm run build && node --test tests/*.test.mjs",
     "lint": "eslint src/**/*.ts",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run build"

package/skills/gsk-aidrive/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: gsk-aidrive
 version: 1.0.0
-description: 'AI-Drive file storage and management. Actions: ls, mkdir, rm, move,
-  get_readable_url, download_video, download_audio, download_file, upload.'
+description: 'AI-Drive file storage and management. Actions: ls, find, mkdir, rm,
+  move, get_readable_url, download_video, download_audio, download_file, upload. `ls`
+  lists ONE directory (non-recursive) — to locate files by name anywhere in the drive,
+  use `find` (one indexed query) instead of walking directories with repeated `ls`.'
 metadata:
   category: general
   requires:
@@ -15,7 +17,7 @@ metadata:
 
 **PREREQUISITE:** Read `../gsk-shared/SKILL.md` for auth, global flags, and security rules.
 
-AI-Drive file storage and management. Actions: ls, mkdir, rm, move, get_readable_url, download_video, download_audio, download_file, upload.
+AI-Drive file storage and management. Actions: ls, find, mkdir, rm, move, get_readable_url, download_video, download_audio, download_file, upload. `ls` lists ONE directory (non-recursive) — to locate files by name anywhere in the drive, use `find` (one indexed query) instead of walking directories with repeated `ls`.
 
 ## Usage
 
@@ -29,8 +31,9 @@ gsk drive [options]
 
 | Flag | Required | Description |
 |------|----------|-------------|
-| `<action>` (positional) | Yes | Action to perform (string, one of: ls, mkdir, rm, move, get_readable_url, download_video, download_audio, download_file, upload) |
-| `-p`, `--path` | No | Path to file or folder for actions: ls, mkdir, rm, move, get_readable_url. For compress: folder path to compress. For decompress: archive file path to decompress (string) |
+| `<action>` (positional) | Yes | Action to perform (string, one of: ls, find, mkdir, rm, move, get_readable_url, download_video, download_audio, download_file, upload) |
+| `-p`, `--path` | No | Path to file or folder for actions: ls, mkdir, rm, move, get_readable_url. For compress: folder path to compress. For decompress: archive file path to decompress. For find: directory to search within (default '/' searches everywhere). (string) |
+| `-q`, `--query` | No | Filename search keyword for find action. Matches files and directories whose name contains the keyword. Case-insensitive. Supports partial matches. (string) |
 | `-f`, `--filter_type` | No | Filter by entry type for ls action (improves performance): all (default), file, directory. Use 'file' when only need files. (string, one of: all, file, directory) |
 | `--file_type` | No | Filter by file MIME type for ls action (improves performance): all (default), audio, video, image. Combine with filter_type='file' for best results. (string, one of: all, audio, video, image) |
 | `--target_path` | No | Destination path, for move action only (string) |

package/skills/gsk-audio-generation/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: gsk-audio-generation
 version: 1.0.0
-description: Generate audio content including TTS, sound effects, and music.
+description: Generate audio (TTS, sound effects, music) with per-model params; query
+  get_model_info for each model's params_schema.
 metadata:
   category: general
   requires:
@@ -14,7 +15,7 @@ metadata:
 
 **PREREQUISITE:** Read `../gsk-shared/SKILL.md` for auth, global flags, and security rules.
 
-Generate audio content including TTS, sound effects, and music.
+Generate audio (TTS, sound effects, music) with per-model params; query get_model_info for each model's params_schema.
 
 ## Usage
 
@@ -28,16 +29,23 @@ gsk audio [options]
 
 | Flag | Required | Description |
 |------|----------|-------------|
-| `<query>` (positional) | No | For text-to-speech generation: - For Gemini TTS (google/gemini-3.1-flash-tts-preview): Can use script_url field or query field. When using multi-speaker, include speaker prefixes like 'Speaker1: Hello there! Speaker2: Hi back!' - For elevenlabs/v3-tts: Supports both single and multi-speaker generation. For multi-speaker, include speaker prefixes like 'Speaker 1: Hello there! Speaker 2: Hi back!' - For other TTS models (Minimax): Use plain text without character names (e.g., use 'That's not what she meant, fatass.' instead of 'STAN: That's not what she meant, fatass.' as the character name will be pronounced). For sound effects, provide a detailed description of the audio to generate (e.g., 'A keyboard typing sound, rain, wind, etc.').For background music, provide a detailed description of the music to generate.must be in English if choosing CassetteAI/music-generator music generation.(e.g., 'Smooth chill hip-hop beat with mellow piano melodies, deep bass, and soft drums, perfect for a night drive. Key: D Minor, Tempo: 90 BPM.'). (string) |
-| `-m`, `--model` | Yes | The model to use for audio generation. google/gemini-3.1-flash-tts-preview: Best, high-quality TTS with enhanced expressivity and granular audio tags ([whispers], [excited], [laughs], [sighs]). Supports inline expression control and multi-speaker dialogue with speaker prefixes (e.g., 'Speaker1: text, Speaker2: text').elevenlabs/v3-tts: Advanced multilingual text-to-speech model with multi-speaker dialogue support. Supports emotional tags like [excited], [whispers], [laughs]. Best for expressive content and conversations.fal-ai/elevenlabs/tts/multilingual-v2: High-quality multilingual text-to-speech model. For English, this is a preferred model.fal-ai/minimax/speech-2.8-hd: High-quality multilingual text-to-speech model. For Chinese, 'Chinese,Yue', Japanese, Korean, this is a preferred model. Note: Only one speaker can be used per generation. For multiple characters, please generate them one by one in sequence. elevenlabs/sound-effects: Sound effect generation model. Minimum duration is 0.1 seconds, maximum is 22 seconds.elevenlabs/music: ElevenLabs music generation model. Supports both instrumental music AND songs with vocals/singing. NOTE: Does NOT support custom lyrics - lyrics are auto-generated. Minimum duration is 10 seconds, maximum is 5 minutes (300 seconds). Professional music production quality.elevenlabs/voice-clone: ElevenLabs voice cloning model. Clone a voice from audio samples. Returns voice ID for use in TTS generation.elevenlabs/voice-changer: ElevenLabs voice changer model. Transform audio from one voice to another. Requires source audio and target voice ID.CassetteAI/music-generator: Background music generation model. minimum duration is 10 seconds, maximum is up to 180 seconds.fal-ai/minimax-music/v2.6: Song generation with lyrics using MiniMax Music 2.6. High-fidelity audio with humanized vocals. Supports markers (Verse), (Chorus), (Bridge), (Outro), (Instrumental intro). Requires both style prompt and lyrics.mureka/song-generator: Professional song generation with lyrics. Supports style prompts, reference tracks, vocal and melody inputs. Generate full songs with vocals. Maximum duration is 180 seconds.mureka/instrumental-generator: Instrumental music generation. Create background music and instrumental tracks without vocals. Supports style prompts and reference tracks. Maximum duration is 180 seconds.google/lyria-music: Google's Lyria 3 music generation model. High-quality 44.1kHz stereo output with vocals and lyrics support. Use sub_model='lyria-3-clip' for 30s clips or 'lyria-3-pro' for full songs (~3min). Supports custom lyrics with section tags like [Verse], [Chorus], [Bridge]. Multilingual vocals: English, Chinese, Japanese, French, Spanish, Korean, etc. (string, one of: google/gemini-3.1-flash-tts-preview, elevenlabs/v3-tts, fal-ai/elevenlabs/tts/multilingual-v2, fal-ai/minimax/speech-2.8-hd, elevenlabs/sound-effects, elevenlabs/music, elevenlabs/voice-clone, elevenlabs/voice-changer, CassetteAI/music-generator, fal-ai/minimax-music/v2.6, mureka/song-generator, mureka/instrumental-generator, google/lyria-music) |
-| `-r`, `--requirements` | No | Required parameters for TTS generation. If you know the speaker name, you can also pass it in the requirementsDetailed description of how the TTS should be generated, including voice characteristics, emotion, pacing, accent, tone, etc. For example: 'A calm, professional female voice with British accent reading at moderate pace'.or 'Speaker1: Algenib, Speaker2: Kore' if you want to use specific speakersThis will be used by the agent to determine the appropriate voice and style parameters (string) |
-| `--previous_audio_params` | No | Required parameters for TTS generation. The `generated_audios[].params` object from previous generation,get from previous tool call, when you need to fix the voice of a specific character, it will be useful. (object) |
-| `-d`, `--duration` | No | The desired duration of the generated audio in seconds. Only applicable for sound effects generation.Default is 0, which means the model will determine the appropriate duration.For background music generation, set default to 30 seconds. (number, default: `0`) |
-| `--custom_voice_id` | No | Custom voice ID for: 1. Minimax TTS - voice ID from voice cloning, 2. ElevenLabs Voice Changer - target voice ID to change to (string) |
-| `--voice_files` | No | URLs or paths to voice sample files for voice cloning. Multiple samples improve clone quality. Required for ElevenLabs voice cloning model. (array) |
-| `--source_audio_file` | No | URL or path to the source audio file for voice transformation. Required for ElevenLabs voice changer model. This is the audio that will be transformed to the target voice. (string) |
-| `--image_urls` | No | The URLs of the images to use as a reference for the audio generation.(default is [], if the task is based on one or more reference images, it is required) (array) |
-| `-l`, `--lyrics` | No | Lyrics for song generation. For google/lyria-music: custom lyrics with section tags like [Verse], [Chorus], [Bridge]. Works with both Clip and Pro. For Mureka song generator and MiniMax Music 2.6: required for vocal generation. (string) |
+| `<prompt>` (positional) | No | What to generate: narration text for TTS (model-specific format — see the model's prompting guide), or a description for music / sound effects. For voice-clone models this text is narrated with the cloned voice. (string) |
+| `-m`, `--model` | No | Model id. Query get_model_info with it before generating. (string, one of: CassetteAI/music-generator, bytedance/seed-audio-1.0, elevenlabs/music, elevenlabs/sound-effects, elevenlabs/v3-tts, elevenlabs/voice-changer, elevenlabs/voice-clone, fal-ai/elevenlabs/sound-effects, fal-ai/elevenlabs/tts/multilingual-v2, fal-ai/minimax-music/v2.6, fal-ai/minimax/speech-2.8-hd, fal-ai/minimax/voice-clone, fal-ai/vibevoice/7b, google/gemini-3.1-flash-tts-preview, google/lyria-music, mureka/instrumental-generator, mureka/song-generator, nova-sr) |
+| `-p`, `--params` | No | Model-specific parameters (speakers, speed/pitch/volume, duration, voice_files, lyrics, composition_plan, output_format, ...). MUST follow the `params_schema` that get_model_info returns for the chosen model. (object) |
+| `-f`, `--file_name` | No | Name for the generated audio. (string, default: `audio`) |
+| `--audio_type` | No |  (string, one of: speech, music, sound_effect, default: `speech`) |
+| `--query_file` | No | Optional repo-relative path to a UTF-8 text file used verbatim as the prompt (long scripts by path). Requires `repo_id`. (string) |
+| `--repo_id` | No | Optional Second Brain repo id; required only when URL fields use repo-relative paths. (string) |
+| `--speaker` | No | Model-specific preset voice (prefer putting it in `params`). (string) |
+| `-d`, `--duration` | No | Duration in seconds for sound-effect/music models (prefer `params`). (integer) |
+| `-l`, `--lyrics` | No | Lyrics for song models (prefer `params`). (string) |
+| `--voice_files` | No | Voice sample URLs for cloning models (prefer `params`). (array) |
+| `--source_audio_file` | No | Source audio URL for voice-changer / enhancement models (prefer `params`). (string) |
+| `--custom_voice_id` | No | Cloned voice id for TTS models (prefer `params`). (string) |
+| `--image_urls` | No | Deprecated: first entry maps to image conditioning when the model supports it. (array) |
+| `-r`, `--requirements` | No | Deprecated inner-agent field; ignored. Use `params` per the model's params_schema. (string) |
+| `--query` | No | Deprecated alias of `prompt` (pre-refactor scripts); ignored when `prompt` is set. (string) |
+| `--previous_audio_params` | No | A prior generation's `params` dict, replayed for voice consistency (explicit `params` wins on conflict). (object) |
 
 ## Local File Support
 

package/skills/gsk-crawler/SKILL.md

@@ -29,7 +29,9 @@ gsk crawl [options]
 | Flag | Required | Description |
 |------|----------|-------------|
 | `<url>` (positional) | Yes | http/https url (string) |
-| `--render_js` | No | Enable JavaScript rendering to bypass anti-bot protection (Cloudflare, 403 errors, dynamically loaded content). Use only when the site blocks plain HTTP crawlers or returns no content — this costs significantly more credits than the default crawler. Default: false. (boolean) |
+| `--render_js` | No | Enable JavaScript rendering to bypass anti-bot protection (Cloudflare, 403 errors, dynamically loaded content). Use only when the site blocks plain HTTP crawlers or returns no content — this costs significantly more credits than the default crawler. Ignored when raw=true. Default: false. (boolean) |
+| `--raw` | No | Return the original response body as decoded text (no markdown conversion). Use when you need raw HTML, meta tags, JSON, or other unprocessed content. Text-only: requests with a binary Content-Type (image/video/audio/pdf/zip/Office) are refused — use the sandbox bash tool with curl/wget for those. Returns at most 10000 bytes per call — pass offset to fetch the next chunk. Default: false. (boolean) |
+| `--offset` | No | Byte offset to start reading from when raw=true. Use to fetch subsequent chunks of the raw body (e.g. offset=10000 for bytes 10000-19999). Maximum 1048576 (1 MiB) — beyond that, switch to the sandbox bash tool with curl/wget. Ignored when raw=false. Default: 0. (integer, default: `0`) |
 
 ## Local File Support
 

package/skills/gsk-create-task/SKILL.md

@@ -3,7 +3,9 @@ name: gsk-create-task
 version: 1.0.0
 description: Create and execute tasks using specialized AI agents. Supports super_agent,
   podcasts, docs, slides, deep_research, website, video_generation, audio_generation,
-  meeting_notes, cross_check.
+  meeting_notes, cross_check. The returned data.task_url is owner-only until shared
+  from that page. To re-fetch a created task's link or outcome, use task_status —
+  re-running create_task creates and bills a new task.
 metadata:
   category: general
   requires:
@@ -16,7 +18,7 @@ metadata:
 
 **PREREQUISITE:** Read `../gsk-shared/SKILL.md` for auth, global flags, and security rules.
 
-Create and execute tasks using specialized AI agents. Supports super_agent, podcasts, docs, slides, deep_research, website, video_generation, audio_generation, meeting_notes, cross_check.
+Create and execute tasks using specialized AI agents. Supports super_agent, podcasts, docs, slides, deep_research, website, video_generation, audio_generation, meeting_notes, cross_check. The returned data.task_url is owner-only until shared from that page. To re-fetch a created task's link or outcome, use task_status — re-running create_task creates and bills a new task.
 
 ## Usage
 

package/skills/gsk-get-model-info/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: gsk-get-model-info
+version: 1.0.0
+description: 'Detailed generation-model info: capabilities, params_schema, available
+  speakers and prompting guides (audio/video/image/3d).'
+metadata:
+  category: general
+  requires:
+    bins:
+    - gsk
+  cliHelp: gsk model-info --help
+---
+
+# gsk-get-model-info
+
+**PREREQUISITE:** Read `../gsk-shared/SKILL.md` for auth, global flags, and security rules.
+
+Detailed generation-model info: capabilities, params_schema, available speakers and prompting guides (audio/video/image/3d).
+
+## Usage
+
+```bash
+gsk model-info [options]
+```
+
+**Aliases:** `model-info`
+
+## Flags
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `<model_names>` (positional) | Yes | Array of model names/IDs to query. Each must be one of the available model names. (array) |
+
+## See Also
+
+- [gsk-shared](../gsk-shared/SKILL.md) — Authentication and global flags

package/skills/gsk-github/SKILL.md

@@ -27,25 +27,32 @@ gsk github [options]
 
 | Flag | Required | Description |
 |------|----------|-------------|
-| `<action>` (positional) | Yes | Action to perform. 'list_repos': List repositories for the authenticated user; 'search_issues': Search issues and pull requests; 'create_issue': Create a new issue; 'update_issue': Update an existing issue (string, one of: list_repos, search_issues, create_issue, update_issue) |
+| `<action>` (positional) | Yes | Action to perform. 'list_repos': List repositories for the authenticated user; 'list_commits': List a repo's commits, filterable by author and ISO 8601 time range; 'get_commit': Read one commit's message, stats, and changed files; 'list_prs': List a repo's pull requests with author, state, and merged_at; 'list_contributors': List a repo's contributors (logins + commit counts) — the raw material for resolving a person's name to their GitHub login; 'user_activity': Recent activity feed (pushes/PRs/reviews/comments) for a GitHub login; private repos covered for the authenticated user only; 'search_issues': Search issues and pull requests; 'get_issue': Read a single issue by number; 'create_issue': Create a new issue; 'update_issue': Update an existing issue; 'list_comments': List comments on an issue or pull request; 'create_comment': Post a new comment on an issue or pull request; 'update_comment': Edit an existing comment by id (string, one of: list_repos, list_commits, get_commit, list_prs, list_contributors, user_activity, search_issues, get_issue, create_issue, update_issue, list_comments, create_comment, update_comment) |
 | `--visibility` | No | [list_repos] Filter by repository visibility. Default: all. (string, one of: all, public, private) |
 | `--affiliation` | No | [list_repos] Comma-separated list of affiliation types: owner, collaborator, organization_member. Default: owner,collaborator,organization_member. (string) |
-| `--sort` | No | [list_repos] How to sort the results. Default: updated. \| [search_issues] How to sort results. Default: best match. (string, one of: created, updated, pushed, full_name) |
-| `--direction` | No | [list_repos] Sort direction. Default: desc (except for full_name). (string, one of: asc, desc) |
-| `--per_page` | No | [list_repos] Number of results per page (max 100). Default: 30. \| [search_issues] Number of results per page (max 100). Default: 30. (integer) |
-| `--page` | No | [list_repos] Page number of the results. Default: 1. \| [search_issues] Page number of the results. Default: 1. (integer) |
+| `--sort` | No | [list_repos] How to sort the results. Default: updated. \| [list_prs] How to sort the results. Default: created. \| [search_issues] How to sort results. If omitted, defaults to 'created' (newest-first) so recent issues surface first instead of GitHub's relevance ranking. Pass 'updated' to sort by last-updated, or another value to override. (string, one of: created, updated, pushed, full_name) |
+| `--direction` | No | [list_repos] Sort direction. Default: desc (except for full_name). \| [list_prs] Sort direction. Default: desc. (string, one of: asc, desc) |
+| `--per_page` | No | [list_repos] Number of results per page (max 100). Default: 30. \| [list_commits] Number of results per page (max 100). Default: 30. \| [list_prs] Number of results per page (max 100). Default: 30. \| [list_contributors] Number of results per page (max 100). Default: 30. \| [user_activity] Number of events per page (max 100). Default: 30. \| [search_issues] Number of results per page (max 100). Default: 30. \| [list_comments] Number of results per page (max 100). Default: 30. (integer) |
+| `--page` | No | [list_repos] Page number of the results. Default: 1. \| [list_commits] Page number of the results. Default: 1. \| [list_prs] Page number of the results. Default: 1. \| [list_contributors] Page number of the results. Default: 1. \| [user_activity] Page number of the results. Default: 1. \| [search_issues] Page number of the results. Default: 1. \| [list_comments] Page number of the results. Default: 1. (integer) |
+| `--owner` | No | [list_commits] The account owner of the repository (username or organization name). \| [get_commit] The account owner of the repository (username or organization name). \| [list_prs] The account owner of the repository (username or organization name). \| [list_contributors] The account owner of the repository (username or organization name). \| [get_issue] The account owner of the repository (username or organization name). \| [create_issue] The account owner of the repository (username or organization name). \| [update_issue] The account owner of the repository (username or organization name). \| [list_comments] The account owner of the repository (username or organization name). \| [create_comment] The account owner of the repository (username or organization name). \| [update_comment] The account owner of the repository (username or organization name). (string) |
+| `--repo` | No | [list_commits] The name of the repository (without the owner prefix). \| [get_commit] The name of the repository (without the owner prefix). \| [list_prs] The name of the repository (without the owner prefix). \| [list_contributors] The name of the repository (without the owner prefix). \| [search_issues] Repository in 'owner/repo' format to search within. Will be added to the query. \| [get_issue] The name of the repository (without the owner prefix). \| [create_issue] The name of the repository (without the owner prefix). \| [update_issue] The name of the repository (without the owner prefix). \| [list_comments] The name of the repository (without the owner prefix). \| [create_comment] The name of the repository (without the owner prefix). \| [update_comment] The name of the repository (without the owner prefix). (string) |
+| `--author` | No | [list_commits] Filter by commit author — a GitHub login or an email address. Omit to list all authors' commits. (string) |
+| `--since` | No | [list_commits] Only commits after this ISO 8601 timestamp (e.g. '2026-06-27T00:00:00Z'). \| [list_comments] Only return comments updated at or after this ISO-8601 timestamp (e.g. '2025-01-01T00:00:00Z'). Useful for incremental polling. (string) |
+| `--until` | No | [list_commits] Only commits before this ISO 8601 timestamp. (string) |
+| `--path` | No | [list_commits] Only commits touching this file or directory path. (string) |
+| `--sha` | No | [get_commit] The commit SHA (full or abbreviated) or a ref name. (string) |
+| `--state` | No | [list_prs] Filter by PR state. Default: all. \| [search_issues] Filter by issue state. Will be added to the query. \| [update_issue] State of the issue. Use 'closed' to close the issue, 'open' to reopen it. (string, one of: open, closed, all) |
+| `--username` | No | [user_activity] The GitHub login whose activity to fetch. (string) |
 | `--q` | No | [search_issues] Search query using GitHub search syntax. Examples: 'repo:owner/repo is:issue is:open', 'author:username', 'label:bug', 'state:closed' (string) |
-| `--repo` | No | [search_issues] Repository in 'owner/repo' format to search within. Will be added to the query. \| [create_issue] The name of the repository (without the owner prefix). \| [update_issue] The name of the repository (without the owner prefix). (string) |
-| `--state` | No | [search_issues] Filter by issue state. Will be added to the query. \| [update_issue] State of the issue. Use 'closed' to close the issue, 'open' to reopen it. (string, one of: open, closed, all) |
 | `--labels` | No | [search_issues] Comma-separated list of labels to filter by. \| [create_issue] Labels to associate with this issue (e.g., ['bug', 'enhancement']). \| [update_issue] Labels to set on this issue (replaces existing labels). (string) |
 | `--assignee` | No | [search_issues] Filter by assignee username. (string) |
 | `--order` | No | [search_issues] Sort order. Default: desc. (string, one of: asc, desc) |
-| `--owner` | No | [create_issue] The account owner of the repository (username or organization name). \| [update_issue] The account owner of the repository (username or organization name). (string) |
+| `--issue_number` | No | [get_issue] The number of the issue to read (required). \| [update_issue] The number of the issue to update (required). \| [list_comments] The number of the issue (required). \| [create_comment] The number of the issue to comment on (required). (integer) |
 | `--title` | No | [create_issue] The title of the issue (required). \| [update_issue] New title of the issue. (string) |
-| `--body` | No | [create_issue] The contents/description of the issue. Supports Markdown. \| [update_issue] New contents/description of the issue. Supports Markdown. (string) |
+| `--body` | No | [create_issue] The contents/description of the issue. Supports Markdown. \| [update_issue] New contents/description of the issue. Supports Markdown. \| [create_comment] The contents of the comment. Supports Markdown. \| [update_comment] New contents of the comment. Supports Markdown. (string) |
 | `--assignees` | No | [create_issue] Logins/usernames of users to assign to this issue. \| [update_issue] Logins/usernames to assign to this issue (replaces existing assignees). (array) |
 | `--milestone` | No | [create_issue] The milestone number to associate with this issue. \| [update_issue] The milestone number to associate with this issue. Set to null to remove milestone. (integer) |
-| `--issue_number` | No | [update_issue] The number of the issue to update (required). (integer) |
+| `--comment_id` | No | [update_comment] The id of the comment to update (NOT the issue number — that's a different identifier). Get this from github_create_comment's response or github_list_comments. (integer) |
 
 ## See Also
 

package/skills/gsk-task-status/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: gsk-task-status
+version: 1.0.0
+description: 'Look up an existing task project previously created with create_task:
+  returns its status, page URL (task_url), and extracted result artifacts. Use this
+  — never a new create_task call — when you need the link or outcome of a task you
+  already created.'
+metadata:
+  category: general
+  requires:
+    bins:
+    - gsk
+  cliHelp: gsk task_status --help
+---
+
+# gsk-task-status
+
+**PREREQUISITE:** Read `../gsk-shared/SKILL.md` for auth, global flags, and security rules.
+
+Look up an existing task project previously created with create_task: returns its status, page URL (task_url), and extracted result artifacts. Use this — never a new create_task call — when you need the link or outcome of a task you already created.
+
+## Usage
+
+```bash
+gsk task_status [options]
+```
+
+## Flags
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `<project_id>` (positional) | Yes | The project_id returned by create_task (data.project_id in its response). (string) |
+
+## See Also
+
+- [gsk-shared](../gsk-shared/SKILL.md) — Authentication and global flags