Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(skills): ollama, vllm and penguin-sdk teach openai-chat, not the alias (#417)

Myriad-Dreamin2a3f253bee3c
diff --git a/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.md b/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.md
new file mode 100644
index 00000000..4edaf2c6
--- /dev/null
+++ b/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.md
@@ -0,0 +1,22 @@
+# Library skills spell the OpenAI client type `openai-chat`
+
+- **Date:** 2026-08-23
+- **Type:** process
+- **Scope:** `skills`
+- **PR:** [#417](https://github.com/Prism-Shadow/penguin-harness/pull/417)
+
+[中文版](2026-08-23-skills-teach-openai-chat-client-type.zh.md)
+
+The `ollama`, `vllm` and `penguin-sdk` skills registered OpenAI-compatible endpoints with
+`--client-type openai`, the pre-AgentHub-0.4.2 spelling that `agenthub-models` documents as a
+deprecated alias. All five occurrences now read `openai-chat` (`ollama` and `vllm` at `v2`,
+`penguin-sdk` at `v22`).
+
+## Details
+
+- Both the prose step and the full command example were updated in `ollama` and `vllm`; the
+ `penguin-sdk` setup recipe was updated in the optional flag and in the recommendation that
+ follows it.
+- The alias keeps working — `canonicalClientType` normalizes it on read and on write, and the
+ CLI already writes `openai-chat` for a new OpenAI-routed entry — so this changes what the
+ library teaches, not what an existing config does.
diff --git a/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.zh.md b/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.zh.md
new file mode 100644
index 00000000..069e9776
--- /dev/null
+++ b/changelog/unreleased/2026-08-23-skills-teach-openai-chat-client-type.zh.md
@@ -0,0 +1,19 @@
+# 库内 skill 统一使用 `openai-chat` 作为 OpenAI 客户端类型
+
+- **Date:** 2026-08-23
+- **Type:** process
+- **Scope:** `skills`
+- **PR:** [#417](https://github.com/Prism-Shadow/penguin-harness/pull/417)
+
+[English](2026-08-23-skills-teach-openai-chat-client-type.md)
+
+`ollama`、`vllm`、`penguin-sdk` 三个 skill 在注册 OpenAI 兼容端点时写的是 `--client-type openai`,
+即 AgentHub 0.4.2 之前的拼法,而 `agenthub-models` 早已把它记作废弃别名。五处全部改为 `openai-chat`
+(`ollama`、`vllm` 升到 `v2`,`penguin-sdk` 升到 `v22`)。
+
+## 细节
+
+- `ollama` 与 `vllm` 的说明步骤和完整命令示例都做了改动;`penguin-sdk` 改的是配置流程里的可选参数
+ 及紧随其后的推荐写法。
+- 该别名仍然可用——`canonicalClientType` 在读和写两侧都会归一化,CLI 为新的 OpenAI 路由条目本来就
+ 写入 `openai-chat`——所以变的是库教什么,不是既有配置的行为。
diff --git a/packages/skills/skills/ollama/SKILL.md b/packages/skills/skills/ollama/SKILL.md
index e4dac8ef..d3b76560 100644
--- a/packages/skills/skills/ollama/SKILL.md
+++ b/packages/skills/skills/ollama/SKILL.md
@@ -3,8 +3,8 @@ name: ollama
description: Deploy and serve local models with Ollama — pull and run them, then expose the OpenAI-compatible endpoint to apps and agents.
short_description: Run local models with Ollama.
short_description_zh: 用 Ollama 运行本地模型。
-version: 1
-updated: 2026-07-22T00:00:00Z
+version: 2
+updated: 2026-08-23T15:42:44Z
---
# Ollama Serving
@@ -32,7 +32,7 @@ If port 11434 is already serving, reuse that instance — never kill an existing
2. Pick the engine the user prefers: Ollama is the default; vLLM covers high-throughput GPU serving.
3. Install Ollama if missing, then `ollama pull qwen3.5:0.8b`.
4. Verify with `curl http://localhost:11434/v1/models`.
-5. Register the endpoint: `penguin config model add ... --client-type openai --base-url http://localhost:11434/v1` — a pulled Ollama model is not visible to Penguin until added.
+5. Register the endpoint: `penguin config model add ... --client-type openai-chat --base-url http://localhost:11434/v1` — a pulled Ollama model is not visible to Penguin until added.
6. Confirm the new entry with `penguin config model list`.
## Install
@@ -85,7 +85,7 @@ ollama create qwen3.5-32k -f Modelfile
Model configuration is the penguin CLI's job — `penguin config model add` registers an endpoint and `penguin config model list` shows what has been registered. A pulled Ollama model is not visible to Penguin until you add it:
```bash
-penguin config model add --provider custom --client-type openai \
+penguin config model add --provider custom --client-type openai-chat \
--base-url http://localhost:11434/v1 --model-id qwen3.5:0.8b --api-key ollama
penguin config model list # the new entry should now be listed
```
diff --git a/packages/skills/skills/penguin-sdk/SKILL.md b/packages/skills/skills/penguin-sdk/SKILL.md
index 1941c6ae..14901a12 100644
--- a/packages/skills/skills/penguin-sdk/SKILL.md
+++ b/packages/skills/skills/penguin-sdk/SKILL.md
@@ -3,8 +3,8 @@ name: penguin-sdk
description: Use whenever the user wants to build an agent application — their own program with an embedded agent, such as an AI app, an agentic app or a RAG app. This is writing application code on the Penguin Harness SDK, not configuring an Agent State inside PenguinHarness. Covers self-contained projects, the createSession/run streaming loop with thinking and image messages, wiring the user's existing tools in as CLI commands, and a complete RAG recipe that ingests documents into a knowledge base and answers with citations behind a web UI.
short_description: Build agent, AI and RAG applications on the Penguin Harness SDK.
short_description_zh: 基于 Penguin SDK 构建智能体应用、AI 与 RAG 应用。
-version: 21
-updated: 2026-08-21T00:00:00Z
+version: 22
+updated: 2026-08-23T15:42:44Z
---
# Penguin Harness SDK
@@ -55,7 +55,7 @@ If the package is not on your npm registry (it is developed in the PenguinHarnes
Configure a model for the app's data root, in this order — stop at the first that works:
-1. `penguin config model add --root <data_dir> --provider <group> --model-id <id> --api-key <key> [--base-url <url>] [--client-type openai] --set-default` — prefer `--client-type openai --base-url <endpoint>` (works with any OpenAI-compatible endpoint; exact ids in the agenthub-models skill). `--provider` is required: a model is always the `(provider, model_id)` pair and the group is never inferred from the id (`custom` for an endpoint outside the built-in groups).
+1. `penguin config model add --root <data_dir> --provider <group> --model-id <id> --api-key <key> [--base-url <url>] [--client-type openai-chat] --set-default` — prefer `--client-type openai-chat --base-url <endpoint>` (works with any OpenAI Chat Completions compatible endpoint; exact ids in the agenthub-models skill). `--provider` is required: a model is always the `(provider, model_id)` pair and the group is never inferred from the id (`custom` for an endpoint outside the built-in groups).
2. Environment variables cover the **credential only** (`DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, …) — model selection still comes from the project config, whose preset default is `deepseek-v4-flash`. Env-only setup therefore works out of the box only with `DEEPSEEK_API_KEY`; for another vendor either run the CLI command above or pass a configured `{ provider, modelId }` pair to `createSession`.
Keep model API keys **project-local**: configure them with the penguin CLI into the app's own data root under the working directory, so the project stays self-contained and movable. When building an AI app, **always pass `--root <data_dir>` pointing at the app's data directory inside the current working directory** (the same path you give `createAgent({ root })`, e.g. `./penguin_data`) — never run `penguin config ...` without `--root`, or it writes to the global `~/.penguin/data` instead of the project. Never read, copy or fall back to model keys stored in the user's global `~/.penguin` directory — that config belongs to the person running Penguin, not to the app you are building.
diff --git a/packages/skills/skills/vllm/SKILL.md b/packages/skills/skills/vllm/SKILL.md
index cbd36796..a2efe368 100644
--- a/packages/skills/skills/vllm/SKILL.md
+++ b/packages/skills/skills/vllm/SKILL.md
@@ -3,8 +3,8 @@ name: vllm
description: Deploy and serve LLMs with vLLM behind an OpenAI-compatible endpoint, with tool calling enabled for agent workloads.
short_description: Serve models locally with vLLM.
short_description_zh: 用 vLLM 部署本地模型服务。
-version: 1
-updated: 2026-07-22T00:00:00Z
+version: 2
+updated: 2026-08-23T15:42:44Z
---
# vLLM Serving
@@ -32,7 +32,7 @@ The model must fit the available VRAM — model size and context length drive th
2. Pick the engine the user prefers: vLLM for high-throughput GPU serving; Ollama is the simple default and the choice on macOS or CPU-only machines.
3. Serve on a free port, with the tool-calling flags whenever agents will call it (see below).
4. Verify with `curl http://localhost:8000/v1/models`.
-5. Register the endpoint: `penguin config model add ... --client-type openai --base-url http://localhost:8000/v1` — a served model is not visible to Penguin until added.
+5. Register the endpoint: `penguin config model add ... --client-type openai-chat --base-url http://localhost:8000/v1` — a served model is not visible to Penguin until added.
6. Confirm the new entry with `penguin config model list`.
## Install
@@ -82,7 +82,7 @@ curl http://localhost:8000/v1/models
Model configuration is the penguin CLI's job — `penguin config model add` registers an endpoint and `penguin config model list` shows what has been registered. A served model is not visible to Penguin until you add it:
```bash
-penguin config model add --provider custom --client-type openai \
+penguin config model add --provider custom --client-type openai-chat \
--base-url http://localhost:8000/v1 --model-id <served-model-name> --api-key <key>
penguin config model list # the new entry should now be listed
```