Merge research and content skills into kagi-usage, add Claude Code plugin

.claude-plugin/marketplace.json

@@ -0,0 +1,26 @@
+{
+  "name": "kagi-cli",
+  "owner": {
+    "name": "Microck",
+    "url": "https://github.com/Microck"
+  },
+  "metadata": {
+    "description": "Marketplace for the Kagi CLI plugin.",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "kagi",
+      "source": "./",
+      "description": "Kagi CLI skills for research, page content, Assistant, monitoring, and account configuration.",
+      "version": "0.15.0",
+      "author": {
+        "name": "Microck",
+        "url": "https://github.com/Microck"
+      },
+      "homepage": "https://github.com/Microck/kagi-cli#readme",
+      "license": "MIT",
+      "keywords": ["kagi", "search", "cli", "research", "assistant"]
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+	"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "kagi",
+  "version": "0.15.0",
+  "description": "Kagi CLI skills for research, page content, Assistant, monitoring, and account configuration.",
+  "author": {
+    "name": "Microck",
+    "url": "https://github.com/Microck"
+  },
+  "homepage": "https://github.com/Microck/kagi-cli#readme",
+  "repository": "https://github.com/Microck/kagi-cli",
+  "license": "MIT",
+  "keywords": ["kagi", "search", "cli", "research", "assistant"]
+}

CHANGELOG.md

@@ -11,7 +11,8 @@ Before `1.0.0`, breaking changes may still ship in minor releases.
 
 ### Added
 
-- `kagi skills` now includes focused guides for research, page content, Assistant conversations, monitoring and automation, and account configuration.
+- Install the repository as a Claude Code plugin through its bundled marketplace manifest.
+- `kagi skills` now includes a unified `kagi-usage` guide for search and page content, a `kagi-ai` guide for spending Assistant allowance, and focused guides for Assistant conversations, monitoring and automation, and account configuration.
 
 ### Fixed
 

README.md

@@ -170,7 +170,7 @@ for the full command-to-token matrix, use the [`auth-matrix`](https://kagi.micr.
 | --- | --- |
 | `kagi search` | search Kagi with `json` by default, or render as `toon`, `pretty`, `compact`, `markdown`, or `csv` |
 | `kagi agent` | print the embedded agent skill guide for choosing commands, auth paths, and output formats |
-| `kagi skills` | list and load embedded, version-matched agent skills with `skills get kagi` as the agent starting point |
+| `kagi skills` | list and load embedded, version-matched agent skills with `skills get kagi-usage` as the agent starting point |
 | `kagi batch` | run multiple searches in parallel with JSON, TOON, compact, pretty, markdown, or csv output and shared filters |
 | `kagi auth` | launch the auth wizard, or inspect, validate, and save credentials |
 | `kagi completion` | generate or install shell completions for bash, zsh, fish, or PowerShell |

docs/commands/skills.mdx

@@ -10,14 +10,15 @@ Load embedded, version-matched usage guidance for agents and automation.
 The top-level help points agents here first:
 
 ```bash
-kagi skills get kagi
+kagi skills get kagi-usage
 ```
 
 Skills ship with the installed CLI binary, so their command examples and
 credential guidance match that exact `kagi` version.
 
-The `kagi` skill is a router. It points to focused workflow skills so agents do
-not need to load the full command surface for every task.
+The `kagi-usage` skill covers search and page content directly, and points to
+the focused workflow skills so agents do not need to load the full command
+surface for every task.
 
 ## Synopsis
 
@@ -29,7 +30,7 @@ kagi skills path [NAME]
 kagi agent
 ```
 
-`kagi agent` is a convenience alias for `kagi skills get kagi`.
+`kagi agent` is a convenience alias for `kagi skills get kagi-usage`.
 
 ## `kagi skills`
 
@@ -46,33 +47,33 @@ kagi skills list
 Print an embedded skill guide to stdout with frontmatter stripped.
 
 ```bash
-kagi skills get kagi
+kagi skills get kagi-usage
 ```
 
 Available skills:
 
 | Skill | Use for |
 | --- | --- |
-| `kagi` | Route an unclear Kagi task |
-| `kagi-research` | Search, Quick Answer, News, source discovery, and verification |
-| `kagi-content` | Extraction, summarization, page questions, and translation |
+| `kagi-usage` | Search, page content, and routing for any other Kagi task |
+| `kagi-ai` | Paid AI reasoning, coding, research, file analysis, and model selection |
 | `kagi-assistant` | Conversations, threads, attachments, and custom assistants |
 | `kagi-monitoring` | Batch, watch, notifications, history, caching, and MCP |
 | `kagi-account-config` | Auth, profiles, lenses, bangs, redirects, and site preferences |
 
-Load the router when the workflow is unclear, or load a focused skill directly:
+Load `kagi-usage` for search and page work, or load a focused skill directly:
 
 ```bash
-kagi skills get kagi
-kagi skills get kagi-research
-kagi skills get kagi-content
+kagi skills get kagi-usage
+kagi skills get kagi-ai
+kagi skills get kagi-assistant
+kagi skills get kagi-monitoring
 ```
 
 `--full` is accepted for Harbor-style compatibility. The current embedded
 skills have no separate references, so `--full` prints the same body as `get`.
 
 ```bash
-kagi skills get kagi --full
+kagi skills get kagi-usage --full
 ```
 
 ## `kagi skills path`
@@ -81,8 +82,8 @@ Print the embedded skill locator.
 
 ```bash
 kagi skills path
-kagi skills path kagi
-kagi skills path kagi-research
+kagi skills path kagi-usage
+kagi skills path kagi-assistant
 ```
 
 Because Kagi embeds skills into the Rust binary instead of installing a

skills/kagi-account-config/SKILL.md

@@ -9,7 +9,7 @@ allowed-tools: Bash(kagi:*)
 Inspect current state before changing it. Never print, echo, or paste stored
 credential values into output.
 
-## Credential Model
+## Credential model
 
 | Credential | Main capabilities |
 | --- | --- |
@@ -19,9 +19,9 @@ credential values into output.
 
 Environment variables override `.kagi.toml`. `--profile NAME` selects a named
 profile. Base search prefers session auth when both search credentials are
-available unless `preferred_auth = "api"` is configured.
+available, unless `preferred_auth = "api"` is configured.
 
-## Inspect And Verify Auth
+## Inspect and verify auth
 
 ```bash
 kagi auth status
@@ -38,7 +38,7 @@ kagi auth
 kagi auth set --session-token "https://kagi.com/search?token=..."
 ```
 
-Do not pass secrets on a shared shell command line. Prefer the interactive
+Never pass secrets on a shared shell command line. Prefer the interactive
 wizard or protected environment injection in shared environments.
 
 ## Profiles
@@ -50,9 +50,9 @@ kagi --profile work auth status
 kagi --profile personal search "query" --format toon
 ```
 
-Verify the selected profile before any setting mutation.
+Verify the selected profile before changing any setting.
 
-## Search Settings
+## Search settings
 
 Inspect before creating, updating, or deleting:
 
@@ -73,10 +73,10 @@ kagi bang custom create \
   --template "https://docs.rs/releases/search?query=%s"
 ```
 
-Use each command's `--help` for mutation-specific flags. Do not delete or
-overwrite account settings without explicit user intent.
+Use each command's `--help` for the flags a mutation needs. Never delete or
+overwrite an account setting unless the user asked for it.
 
-## Custom Assistants
+## Custom assistants
 
 ```bash
 kagi assistant custom list
@@ -86,12 +86,12 @@ kagi assistant custom get "Researcher"
 Conversation and thread use belongs in `kagi-assistant`. This skill owns the
 account-level configuration of custom assistants.
 
-## Completion Criteria
+## Completion criteria
 
 Configuration work is complete when:
 
-- the active profile and credential source are known;
+- you know the active profile and credential source;
 - the requested setting is visible through its read command;
 - no secret value appears in output or persisted scripts;
 - unrelated account settings remain unchanged; and
-- destructive changes were explicitly requested.
+- you made a destructive change only when the user asked for it.

skills/kagi-ai/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: kagi-ai
+description: "Use Kagi's paid AI allowance for reasoning, coding, research, file analysis, structured generation, or model comparison. Use when a task should spend Assistant value instead of only searching the web or transforming one known page."
+allowed-tools: Bash(kagi:*) Skill(kagi:*)
+---
+
+# Kagi AI
+
+Spend the Assistant allowance on reasoning and synthesis. When the active plan
+includes unlimited Summarizer or Translate usage, use those tools for direct
+transformations and reserve the allowance for harder work.
+
+## Choose the lane
+
+| Need | Lane |
+| --- | --- |
+| Find or verify sources | Load `kagi-usage` and search |
+| Summarize one URL or text | `kagi summarize --subscriber` |
+| Translate supplied text | `kagi translate` |
+| Get a fast cited answer | `kagi quick` |
+| Reason, code, synthesize, or analyze files | `kagi assistant` |
+| Run multi-step research or tool use | An account-visible Research assistant |
+| Manage threads or custom assistants | Load `kagi-assistant` |
+
+The Assistant allowance is separate from API credit. A plan's monthly value
+sets its token allowance across Assistant models. Premium models, web access,
+large files, and long thread histories consume more of that allowance.
+
+## Start with live account state
+
+```bash
+kagi auth status
+kagi assistant models
+kagi assistant custom list
+```
+
+Use only model slugs and assistant names returned by the account. When the
+model catalog is empty, use the account default instead of guessing a slug.
+Kagi Quick and Kagi Research are usable through `--assistant` only when they
+appear in the assistant listing.
+
+## Use Assistant deliberately
+
+Use a closed model call for reasoning that needs no current information:
+
+```bash
+kagi assistant \
+  "find the weakest assumption in this design and propose a simpler one" \
+  --no-web-access \
+  --format markdown
+```
+
+Enable web access when the answer needs current sources:
+
+```bash
+kagi assistant \
+  "compare these database options for this workload and cite current limits" \
+  --web-access \
+  --format markdown
+```
+
+Choose a live model explicitly only when its cost, speed, or capability matters:
+
+```bash
+kagi assistant \
+  "review this migration plan for data-loss risks" \
+  --model MODEL_SLUG \
+  --no-web-access \
+  --format markdown
+```
+
+For a model comparison, send the same bounded prompt to each model in a fresh
+thread. Compare correctness, latency, and usefulness, not prose style alone.
+
+## Analyze files
+
+Attach only the files needed for the answer. Assistant accepts documents,
+spreadsheets, images, and audio; one upload can be at most 30 MB.
+
+```bash
+kagi assistant \
+  --attach ./report.pdf \
+  "extract the decision, evidence, risks, and unresolved questions" \
+  --no-web-access \
+  --format markdown
+```
+
+Uploaded content remains in the thread context. Start a new thread when the
+next task should not inherit it.
+
+## Require structured output
+
+Use a built-in contract for reusable decisions, plans, and checklists:
+
+```bash
+kagi assistant \
+  "decide whether this service is ready to launch" \
+  --contract decision \
+  --format json
+```
+
+Use `--contract-file PATH` when the consumer needs a different small JSON
+shape. Contract mode validates the response and makes one repair attempt.
+
+## Budget discipline
+
+1. Use subscriber Summarizer or Translate for direct transformations when the
+   active plan includes them.
+2. Use the account default or a lower-cost model for simple work.
+3. Disable web access for closed-context work.
+4. Keep prompts specific and attach only relevant files.
+5. Start a new thread for an unrelated task.
+6. Reserve Research assistants and premium models for work that needs their
+   extra tools or reasoning depth.
+
+## Completion criteria
+
+AI work is complete when:
+
+- the selected lane matches the task;
+- every explicit model or assistant came from live account discovery;
+- web access and attachments are limited to what the answer needs;
+- structured output passes its contract when a machine will consume it;
+- the response answers the task instead of spending allowance on avoidable
+  transformations; and
+- you changed or deleted account state only when the user asked.