A local-first multi-agent app development platform, built on PenguinHarness
fix(skills): state the penguin-sdk trigger and CLI-first tool wiring (#365)
Yaowei Zheng183178cb1bcf
diff --git a/changelog/unreleased/2026-08-20-penguin-sdk-skill-trigger.md b/changelog/unreleased/2026-08-20-penguin-sdk-skill-trigger.mdnew file mode 100644index 00000000..46a80ef3--- /dev/null+++ b/changelog/unreleased/2026-08-20-penguin-sdk-skill-trigger.md@@ -0,0 +1,25 @@+# penguin-sdk skill: explicit trigger and CLI-first tool wiring++- **Date:** 2026-08-20+- **Type:** process+- **Scope:** `skills`, `docs`+- **PR:** [#365](https://github.com/Prism-Shadow/penguin-harness/pull/365)++[中文版](2026-08-20-penguin-sdk-skill-trigger.zh.md)++Sharpened when the `penguin-sdk` skill fires and what it recommends for wiring in the+user's own tools.++## Details++- The skill's `description` now opens with the trigger: use the skill whenever the user+ wants to build an agent application — their own program with an embedded agent, such as+ an AI, agentic or RAG app. It also states the boundary: application code written on the+ SDK, not configuring an Agent State inside PenguinHarness.+- Added a "Wiring in the user's tools" section: integrate the user's existing tools as+ CLI commands the embedded agent invokes through the built-in `exec_command` tool,+ reserving MCP servers (`tools.mcpServers` in `system_config.yaml`) for integrations a+ CLI wrapper cannot express.+- Extended `short_description` / `short_description_zh` and the bilingual docs skill+ tables to name agent applications and the same boundary, and bumped the skill version+ to 21.diff --git a/changelog/unreleased/2026-08-20-penguin-sdk-skill-trigger.zh.md b/changelog/unreleased/2026-08-20-penguin-sdk-skill-trigger.zh.mdnew file mode 100644index 00000000..ba506459--- /dev/null+++ b/changelog/unreleased/2026-08-20-penguin-sdk-skill-trigger.zh.md@@ -0,0 +1,21 @@+# penguin-sdk skill:明确触发条件与 CLI 优先的工具接入++- **Date:** 2026-08-20+- **Type:** process+- **Scope:** `skills`, `docs`+- **PR:** [#365](https://github.com/Prism-Shadow/penguin-harness/pull/365)++[English](2026-08-20-penguin-sdk-skill-trigger.md)++明确了 `penguin-sdk` skill 的触发时机,以及接入用户已有工具的推荐方式。++## 细节++- skill 的 `description` 现以触发条件开头:只要用户想构建智能体应用(自己交付的、内嵌+ agent 的程序,例如 AI 应用、Agent 形态应用或 RAG 应用),就使用本 skill;并写明边界:+ 这是在 SDK 上写应用代码,而不是在 PenguinHarness 内配置 Agent State。+- 新增「Wiring in the user's tools」一节:把用户已有工具包装成 CLI 命令,由内嵌+ agent 通过内置 `exec_command` 工具调用;仅当 CLI 包装无法表达集成时才使用 MCP+ Server(`system_config.yaml` 中的 `tools.mcpServers`)。+- `short_description` / `short_description_zh` 与 docs 双语技能表同步改为「智能体应用」+ 并写明同一条边界,skill 版本号升至 21。diff --git a/packages/docs/content/skills.en.md b/packages/docs/content/skills.en.mdindex 9997be4b..909ddee1 100644--- a/packages/docs/content/skills.en.md+++ b/packages/docs/content/skills.en.md@@ -66,7 +66,7 @@ The built-in Skills, by group (the group manifest is `SKILL_GROUPS` in `packages| Software Development | `web-design` | Penguin visual language for generated web pages and app UIs: design tokens, components, light/dark themes and chat layouts || | `software-engineering` | Complete software-engineering tasks: investigate and review code, implement fixes, features and refactors with minimal scope, validate changes, and report verified outcomes || | `remote-claude-code` | Run Claude Code on a remote host over SSH — a persistent expect session, headless `-p` with the stdin fix, a tmux-driven interactive TUI (one capture-verified keystroke at a time, user messages relayed verbatim) and multi-turn continuity (not preinstalled: install from the library when needed) |-| AI App Development | `penguin-sdk` | Build AI and RAG apps on the SDK: the createSession/run streaming loop plus a complete retrieval recipe with chunk-revealing citations |+| AI App Development | `penguin-sdk` | Build agent, AI and RAG applications on the SDK — application code, not Agent State configuration: the createSession/run streaming loop, CLI-wrapped user tools, plus a complete retrieval recipe with chunk-revealing citations || | `penguin-cli` | Manage model API keys, default models and per-agent Vault secrets with the penguin CLI || | `agenthub-models` | Call model APIs through `@prismshadow/agenthub`: streaming text, image generation, speech synthesis and embeddings || | `vllm` | Deploy and serve LLMs with vLLM behind an OpenAI-compatible endpoint, with tool calling enabled for agent workloads |diff --git a/packages/docs/content/skills.zh.md b/packages/docs/content/skills.zh.mdindex 21cc6e36..51317483 100644--- a/packages/docs/content/skills.zh.md+++ b/packages/docs/content/skills.zh.md@@ -66,7 +66,7 @@ Skill 库以 npm 包 `@prismshadow/penguin-skills` 发布,tarball 直接携带| 软件开发 | `web-design` | 生成网页与应用界面的 Penguin 视觉语言:设计令牌、组件配方、明暗主题与聊天布局 || | `software-engineering` | 完成软件工程任务:调查与审查代码,以最小改动实现修复、特性与重构,验证改动并报告经过确认的结果 || | `remote-claude-code` | 通过 SSH 在远程主机上驱动 Claude Code:expect 持久会话、headless `-p` 的 stdin 修正、tmux 驱动的交互 TUI(逐个按键并截屏确认,用户消息原样转发)与多轮续接(不预装,按需从技能库安装) |-| AI 应用开发 | `penguin-sdk` | 基于 SDK 构建 AI 与 RAG 应用:createSession/run 流式循环,外加带可溯源引用的完整检索配方 |+| AI 应用开发 | `penguin-sdk` | 基于 SDK 构建智能体应用、AI 与 RAG 应用(写应用代码,而非配置 Agent State):createSession/run 流式循环、以 CLI 形式接入用户已有工具,外加带可溯源引用的完整检索配方 || | `penguin-cli` | 用 penguin CLI 管理模型 API Key、默认模型与各 Agent 的 Vault 密钥 || | `agenthub-models` | 经 `@prismshadow/agenthub` 调用模型 API:流式文本、图像生成、语音合成与 Embedding || | `vllm` | 用 vLLM 部署与服务 LLM,提供 OpenAI 兼容端点,并为 Agent 负载启用工具调用 |diff --git a/packages/skills/skills/penguin-sdk/SKILL.md b/packages/skills/skills/penguin-sdk/SKILL.mdindex 3d84e232..48e62b32 100644--- a/packages/skills/skills/penguin-sdk/SKILL.md+++ b/packages/skills/skills/penguin-sdk/SKILL.md@@ -1,10 +1,10 @@---name: penguin-sdk-description: Build AI apps on the Penguin Harness SDK — self-contained projects, the createSession/run streaming loop with thinking and image messages, and a complete RAG recipe that ingests documents into a knowledge base and answers with citations behind a web UI.-short_description: Build AI and RAG apps on the Penguin Harness SDK.-short_description_zh: 基于 Penguin SDK 构建 AI 与 RAG 应用。-version: 19-updated: 2026-08-06T00:00:00Z+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---# Penguin Harness SDK@@ -120,6 +120,12 @@ Browser flow: `<input type="file" accept="image/*">` plus paste/drag-drop → `F**Other payloads worth handling** (always narrow with the guards first): `partial_tool_call` / `partial_tool_call_output` — surface as an activity line ("running `search`…") in apps that grant tools; `request_end` (event) — a non-`completed` `status` is the error signal (`auth` → ask for a key; `message` carries the failure detail; `retry_in_ms` announces a planned in-run retry, renderable as a countdown); `token_usage` (event) — session-cumulative and last-request counts, if the app shows cost; `compaction_begin` / `compaction_end` (events) — long-lived chats only, show a brief "context being compacted" notice. Everything else is safe to ignore.+## Wiring in the user's tools++When the app's agent must call the user's existing tools (scripts, internal CLIs, anything with an entry point), integrate them as **CLI commands** first: wrap each one as a small executable inside the project (a script under `tools/`, or the user's own binary), and describe it in the embedded agent's persona / `AGENTS.md` — name, what it does, one usage line. The agent invokes it through the built-in `exec_command` tool, so there is nothing to register: no schema to declare, arguments are flags, stdout is the result, the `approve` callback still gates every invocation, and the same command stays testable by hand.++Add an MCP server (`tools.mcpServers` in `system_config.yaml`) only when a CLI wrapper cannot express the integration — a long-lived authenticated connection, or tool schemas the model must see typed. Otherwise the CLI form is the cheaper default and keeps the project self-contained.+## RAG knowledge appThe default recipe when the user wants an app that answers questions over a document set ("docs QA", "knowledge base", "chat with our docs", "become an expert on X"). The core contributes the agent loop only — retrieval is app code. Default to **lexical BM25**: no extra dependencies, no embedding credential, works offline. (Semantic upgrade: embed chunks via `@prismshadow/agenthub` — see the agenthub-models skill — and rank by cosine; only when an embedding-capable key is configured.)