@prismshadow/penguin-skills 0.0.1

package/skills/agent-evaluation/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: agent-evaluation
+description: Run and score exactly one Benchmark Case run with CLI execution, Trace provenance checks, and private Rubric isolation.
+short_description: Run and score one isolated Benchmark Case.
+short_description_zh: 隔离执行并评分一个 Benchmark Case。
+version: 1
+updated: 2026-07-17T17:08:17Z
+---
+
+# Agent Evaluation
+
+Act as an internal leaf worker. For one valid request, run and score exactly one Benchmark Case once, then return minimal protocol metadata. Do not design or refine the Benchmark, modify the Test Agent State, or write `scoreboard.yaml`. Do not use `run_subagent` or `input_subagent`.
+
+## Before you start
+
+This Skill is invoked by `benchmark-design` or Benchmark mode in `agent-optimization`. Require one unambiguous protocol request containing every identity field below. If the request is missing, duplicated, or conflicting, return `invalid_request` without creating a Workspace or launching the Test Agent. Do not ask an interactive clarification from this leaf worker.
+
+## Privacy boundary
+
+Before the final protocol YAML, emit no assistant text; use private reasoning and tool calls only. Never serialize Statement or artifact contents, Rubric items, expected values, correct outcomes, per-item scoring, diagnostics, secret configuration, Workspace paths, or Trace paths into an assistant message. The final assistant message is the protocol YAML only. It may echo the public identity fields supplied by the caller.
+
+A valid request contains exactly one value for each field:
+
+```text
+protocol_version: 1
+case_id: <case_id>
+run: <1_based_run_index>
+expected_version: <tested_agent_state_version>
+test_agent_id: <test_agent_id>
+benchmark_dir: <absolute_benchmark_dir>
+provider: <provider>
+model_id: <upstream_model_id>
+```
+
+## Validate and prepare
+
+Resolve the Project, Test Agent, Benchmark, and Case only from the explicit request and Environment Project Dir. Reject traversal, symlink escape, or any path outside the requested Test Agent. Never read a Project configuration file, credential, or vault.
+
+Require:
+
+```text
+<test_agent_dir>/agent_state/system_config.yaml
+<benchmark_dir>/benchmark_config.toml
+<benchmark_dir>/<case_id>/statement/README.md
+<benchmark_dir>/<case_id>/rubric/README.md
+```
+
+Require `benchmark_config.toml` to contain a positive integer `runs`; the requested `run` must be within `1..runs`. The canonical State version is the top-level `version` in `system_config.yaml`, defaulting to 1, and must equal `expected_version`.
+
+Read and retain the exact Statement and Rubric bytes before launch. Reject an unusable, contradictory, non-atomic, or unbounded Rubric. The Rubric must declare a finite Case maximum; the returned score must fall within `0..case_max`.
+
+Create a collision-checked Workspace at `<test_agent_dir>/workspaces/tmp-<8hex>`. Copy only the contents of `statement/` into it. Never copy, link, or disclose `rubric/`, and never reuse another Case or run's Workspace.
+
+## Launch and bind the Test Session
+
+Use an existing verified Penguin CLI or repository-local launcher already available in the runtime. Do not install a CLI and do not use `penguin run` as a probe. If no launcher is available, return `cli_failed`.
+
+Run the Test Agent exactly once in the foreground with a fresh top-level Session:
+
+```bash
+PROJECT_DIR="<project_dir>"
+PROJECT_ID="$(basename "$PROJECT_DIR")"
+PENGUIN_HOME="$(dirname "$PROJECT_DIR")"
+WORKSPACE="$PROJECT_DIR/agents/<test_agent_id>/workspaces/<unique_workspace_id>"
+export PENGUIN_HOME
+penguin run --message "Read README.md in the current Workspace and complete the task exactly as specified there." \
+  --provider "<provider>" --model-id "<model_id>" --project-id "$PROJECT_ID" \
+  --agent-id "<test_agent_id>" --workspace "$WORKSPACE" --approve allow-all
+```
+
+Use the exact Project, Test Agent, Model pair, and Workspace. Do not fall back to another value. Poll the same process until it exits. A nonzero, interrupted, or misrouted launch is `cli_failed`, not score zero. Do not relaunch within the same run or target processes by a global name or pattern.
+
+Read the canonical State version before and after the Test run; any change is `version_changed`. Confirm the Statement and Rubric bytes are unchanged before scoring.
+
+Search only the explicitly requested Test Agent's `traces/` tree and never inspect another Agent's traces. Group rotated shards by Session. Evaluate every Session group that could contain the exact Workspace match; never infer ownership from recency or a fixed-size latest subset. Bind the Test Trace mechanically from `session_meta`:
+
+- `payload.workspace` equals the unique Workspace;
+- `payload.agent_state` equals the exact Test Agent State path;
+- `payload.provider` equals the requested provider;
+- `payload.model_id` equals the requested model id.
+
+When matching Test subagents exist, exclude child ids referenced by subagent events and require one unique matching root Test Session. Unrelated concurrent traces are not conflicts. Missing, multiple, malformed, or identity-mismatched roots are `provenance_mismatch`.
+
+## Score and account
+
+Inspect only the unique Test Workspace, its bound Test Trace, and the retained private Rubric. Apply every atomic item exactly and normalize only allowed equivalents. A missing, malformed, wrong-type, or incorrect Test artifact is ordinary scored Test Agent behavior: apply the Rubric's zero or partial credit and return `status: ok`. Only a changed or unusable Rubric, or a non-finite/out-of-range result, is `invalid_score`. Detailed reasoning remains in Evaluator Trace.
+
+Compute `duration_ms` from the bound root Test Session, not from the Evaluator. Compute cost only from that root and child Sessions mechanically referenced by subagent events whose traces are available within the explicitly requested Test Agent's `traces/` tree. For each included Session, use final cumulative token usage rather than summing intermediate cumulative events, and apply the matching public `(provider, model_id)` pricing. If any referenced child trace or usage is unavailable there, including because the Test Session delegated to another Agent, or if any included usage is unpriced, return `cost: null` rather than inspecting another Agent or reporting a known partial sum as complete cost.
+
+## Return protocol
+
+Emit exactly one plain YAML document beginning with `protocol_version:` and stop. Do not use a code fence or add explanations.
+
+On success:
+
+```text
+protocol_version: 1
+status: ok
+case_id: <case_id>
+run: <run>
+expected_version: <version>
+provider: <provider>
+model_id: <model_id>
+score: <0_to_case_max>
+cost: <number_or_null>
+duration_ms: <non_negative_integer>
+session_id: <test_session_id>
+```
+
+On failure:
+
+```text
+protocol_version: 1
+status: infrastructure_failure
+case_id: <case_id>
+run: <run>
+expected_version: <version>
+provider: <provider>
+model_id: <model_id>
+failure_code: <stable_failure_code>
+```
+
+Stable codes are `invalid_request`, `invalid_statement`, `invalid_rubric`, `cli_failed`, `provenance_mismatch`, `version_changed`, and `invalid_score`. Do not include score, cost, duration, Session id, private data, or optimization advice on failure.

package/skills/agent-evaluation/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M8 4h8" />
+  <path d="M9 3h6v3H9z" />
+  <rect x="5" y="5" width="14" height="16" rx="2" />
+  <path d="m8.5 13 2.2 2.2 4.8-5" />
+</svg>

package/skills/agent-optimization/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: agent-optimization
+description: Improve an Agent State from direct feedback or versioned multi-Case Benchmark scores and score-linked Traces.
+short_description: Improve an Agent from feedback or measured Benchmark results.
+short_description_zh: 根据反馈或 Benchmark 结果改进 Agent。
+version: 1
+updated: 2026-07-17T17:08:17Z
+---
+
+# Agent Optimization
+
+Improve an existing Agent State. Use one-shot feedback mode for a direct correction, or Benchmark optimization mode for a measured loop. Do not mix their execution paths. One-shot mode does not require Agent Evaluator. Benchmark mode evaluates every configured Case run through Agent Evaluator and never launches or scores the Test Agent directly.
+
+## Before you start
+
+If the request supplies neither concrete feedback nor an explicit Test Agent and Benchmark, ask what to improve. Determine the mode before editing anything.
+
+Benchmark mode requires a top-level Session with `run_subagent`, a complete baseline series in `scoreboard.yaml`, and `agent-evaluation` installed on the current Agent. If any requirement is missing, stop and explain what the user must provide or install. Do not begin a partial optimization round.
+
+## Pick the target Agent
+
+A one-shot request normally names the target. A delegated request begins with `Caller agent: <agent_id>`, and an @-mention handoff contains `<handoff_from>`. When one-shot mode has no explicit target, use that caller or origin; if neither exists, ask. Benchmark mode always requires an explicit Test Agent and Benchmark.
+
+Resolve paths from the Environment's Project Dir without recursively discovering the Project:
+
+```text
+PROJECT_DIR = <project_dir>
+PROJECT_ID = <basename_of_project_dir>
+PENGUIN_HOME = <parent_of_project_dir>
+TARGET = <project_dir>/agents/<test_agent_id>
+STATE = <target>/agent_state
+TRACES = <target>/traces
+BENCHMARK = <target>/benchmarks/<benchmark_id>
+SCOREBOARD = <benchmark>/scoreboard.yaml
+```
+
+Never read a Project configuration file, credential, vault, private Rubric, Agent Evaluator State, Evaluator Workspace, or Evaluator Trace.
+
+## State editing policy
+
+Make the smallest complete edit supported by evidence and preserve unrelated instructions and files.
+
+- Behavioral, workflow, role, or domain guidance belongs in `agent_state/AGENTS.md` unless a relevant target-owned Skill already owns that reusable capability.
+- Update a relevant target-owned `SKILL.md` when the behavior is a reusable capability shared across tasks.
+- Create a narrowly named Skill only when the capability is reusable and no suitable Skill exists. Installing its directory is sufficient; do not register Skill metadata in AGENTS.md.
+- Runtime limits belong in safe `system_config.yaml` fields. Do not edit `system_prompt` unless the user explicitly asks.
+- Never modify a library-provided Skill such as `penguin-sdk` to carry target-specific behavior.
+
+Every edit must generalize beyond the observed run. Do not encode Case ids, exact expected outputs, Benchmark-specific constants, private criteria, or a guessed answer. Keep a recovered mapping, threshold, or formula only when repeated public evidence supports it as a durable rule; otherwise encode the reasoning and validation method.
+
+## Version and rollback discipline
+
+Before changing Agent State, read its canonical top-level `version` from `system_config.yaml`, defaulting to 1. The system owns Agent State snapshot archives and exposes them through Web export and import. Do not create, import, extract, or replace snapshot archives yourself. Require `<target>/snapshots/v<version>.tar.gz` to exist; if it is missing, stop and ask the user to export the current Agent State from Agent settings before continuing.
+
+For each file the edit will change, record its exact original bytes and whether it existed in a temporary directory outside `STATE`. Never include `.vault.toml`, an unrelated State file, or a snapshot archive. Write each candidate file through a temporary sibling, validate it, and rename it into place. Set the State version to `current + 1` exactly once before evaluation.
+
+If the candidate is rejected or a valid comparison cannot complete, restore only those recorded files, remove files created by the candidate, and verify that the prior version is active. If the active version or a candidate-owned file no longer matches the value written by this round, treat it as a concurrent mutation and stop without overwriting it. If rollback cannot be verified, stop and ask the user to restore the system snapshot through Web import.
+
+## One-shot feedback mode
+
+Use the user's feedback and relevant recent Trace when available. Turn that evidence into the smallest targeted change:
+
+- behavior, workflow, role, or domain guidance → update AGENTS.md or the relevant target-owned Skill;
+- a missing reusable capability → install or update a narrowly scoped Skill;
+- a runtime limit → adjust the relevant `system_config.yaml` field.
+
+Require the current-version system snapshot and record the exact originals of files being changed before editing. Increment the version once after the complete edit. If the edit cannot complete, roll back only those files. Report the evidence, changed State surface, new version, and reason. Do not claim measured improvement because this mode has no Benchmark comparison.
+
+## Benchmark optimization mode
+
+Require `benchmark_config.toml` with a positive integer `runs` and a complete baseline evaluation. The baseline Case set is frozen for optimization. Each reference or candidate evaluation must include exactly `runs` uniquely numbered runs for every frozen Case.
+
+Use the reference evaluation's `(provider, model_id)` pair unchanged so scores remain comparable. If the user wants a different Model, stop and ask for a new baseline series rather than comparing across Models.
+
+Before any candidate edit, read the canonical top-level State version and select a reference evaluation in the existing `(provider, model_id)` series. The selected reference is valid only when its `version` equals the active State version and its Cases and runs form the complete frozen Case × `runs` matrix. Never compare a candidate against an older-version, incomplete, or mixed-Model evaluation.
+
+If the active State has no such evaluation, measure it before optimizing: leave State unchanged, run the complete frozen matrix with the existing series' exact `(provider, model_id)` pair, and validate the results under the same rules used for a candidate. Retain the exact Scoreboard bytes and active State version before dispatch; append the completed no-edit reference through a temporary sibling, YAML validation, and atomic rename only if both remain unchanged. This appended evaluation becomes the reference. If any cell remains invalid after the allowed retry, provenance does not match, State or Scoreboard changes, or the atomic append cannot complete, stop before editing Agent State.
+
+You may inspect the complete target `agent_state/`, public Case Statements, the Scoreboard, and all Test traces referenced by the Scoreboard runs. Use only those explicit Case and Session ids. Never edit the Benchmark, Test traces, Project configuration, or another Agent.
+
+Scoreboard v2 uses this shape:
+
+```yaml
+evaluations:
+  - time: "2026-07-17T00:00:00Z"
+    version: 2
+    provider: deepseek
+    model_id: deepseek-v4-pro
+    summary_title: "Improved evidence validation"
+    summary: "Added a reusable validation step; all Cases improved without new instability."
+    score: 24
+    cost: 0.04
+    duration_ms: 60000
+    cases:
+      - case: CASE-001-example
+        score: 24
+        cost: 0.04
+        duration_ms: 60000
+        runs:
+          - score: 23
+            cost: 0.03
+            duration_ms: 58000
+            session_id: session-1
+          - score: 24
+            cost: 0.04
+            duration_ms: 60000
+            session_id: session-2
+          - score: 25
+            cost: 0.05
+            duration_ms: 62000
+            session_id: session-3
+```
+
+Case metrics are the means of valid `runs`; evaluation totals are the sums of Case means. Omit cost when any contributing run has unknown cost. `summary_title` and `summary` may describe public State changes, gains, regressions, and instability, but must not reveal private Rubric or Gold content, expected answers, or private scoring reasoning.
+
+## Optimization loop
+
+For each round:
+
+1. Reconfirm that the reference version equals the active top-level State version and that it contains the complete frozen Case × `runs` matrix. Then analyze its aggregate, Case scores, repeated runs, and every score-linked Test Trace. Use repeated runs to separate stable failure from variation; never select a convenient Trace.
+2. State one falsifiable behavioral hypothesis connecting public evidence to a minimal State change. If no credible hypothesis remains, stop.
+3. Confirm the current-version system snapshot exists, record the exact originals of every candidate-owned file, make the candidate edit, and set `version` to `current + 1` once.
+4. Retain the exact Scoreboard bytes and candidate version. Build the complete Case-run matrix before dispatch.
+5. Start one child per cell with `run_subagent`, and omit `agent_id` so the child reuses the current Agent. Each prompt begins with the caller identity and the sentence: Use the `agent-evaluation` Skill. Then it contains one request:
+
+   ```text
+   Caller agent: <current_agent_id>
+   Use the `agent-evaluation` Skill. Return only its terminal protocol YAML.
+   protocol_version: 1
+   case_id: <case_id>
+   run: <1_based_run_index>
+   expected_version: <candidate_agent_state_version>
+   test_agent_id: <test_agent_id>
+   benchmark_dir: <absolute_benchmark_dir>
+   provider: <reference_provider>
+   model_id: <reference_upstream_model_id>
+   ```
+
+   For N Cases and R runs, emit all N × R independent calls in the same parallel tool-call group before waiting. Continue an active child through `input_subagent`; never duplicate it.
+6. Parse only each child's last terminal `protocol_version: 1` YAML mapping. Keep every identity-matched `status: ok` result. Retry invalid cells once, dispatching all retries together with identical State, Model, Benchmark, and run identities. Never retry a valid scored cell. If any retry remains invalid, reject the round and roll back the candidate files.
+7. Compute Case means and evaluation sums. Retain every score, cost when complete, duration, and Test Session id. Re-read State version and exact Scoreboard bytes, and verify that every candidate-owned file still matches the value written by this round. If State changed concurrently, stop without overwriting it. If only the Scoreboard changed, reject the round and roll back the candidate files.
+8. Accept only a score strictly higher than the comparable reference evaluation. On improvement, keep the candidate State and append one evaluation through a temporary sibling, YAML validation, and atomic rename. On an equal or lower score, roll back the candidate files and append nothing.
+
+Each accepted round becomes the next reference. Stop when the user's target or round limit is met, no credible evidence-backed hypothesis remains, or infrastructure prevents another valid comparison. Do not mutate State as random search.
+
+At the end, report the accepted score curve, State versions and changes, rejected hypotheses and rollbacks, Test Session ids, stop reason, and limitations. Distinguish the active tested State from any unscored State; never claim a Scoreboard score applies to a later untested edit.

package/skills/agent-optimization/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M5 15.5a7 7 0 0 1 14 0" />
+  <path d="M12 8.5v1.8" />
+  <path d="M7.05 10.55l1.27 1.27" />
+  <path d="M12 15.5l3.8-3.8" />
+  <circle cx="12" cy="15.5" r="1.1" />
+</svg>

package/skills/agenthub-models/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: agenthub-models
+description: Call model APIs through @prismshadow/agenthub — streaming text generation, image generation, speech synthesis and embeddings with one client.
+short_description: Call model APIs with one AgentHub client.
+short_description_zh: 用一个 AgentHub 客户端调用模型 API。
+version: 1
+updated: 2026-07-17T00:00:00Z
+---
+
+# AgentHub Model APIs
+
+`@prismshadow/agenthub` is a unified TypeScript client for model APIs: streaming text, image generation, speech synthesis and embeddings behind one entry point.
+
+```bash
+npm install @prismshadow/agenthub
+```
+
+The only entry point is `AutoLLMClient`:
+
+```ts
+import { AutoLLMClient } from "@prismshadow/agenthub";
+
+const client = new AutoLLMClient({ model: "<model_id>", apiKey: "<key>", baseUrl: "<url>", clientType: "<type>" });
+```
+
+`apiKey`, `baseUrl` and `clientType` are optional (see routing below).
+
+## Before you start
+
+If the user's message only invokes this skill (e.g. "use agenthub-models skill") without a concrete task, ask the user what they want to build. Do not write code until the requirement is clear.
+
+## Model IDs
+
+Use exact model ids. If an id is not in the table below and the user has not given one, ask the user to confirm the exact id before writing code.
+
+| Family           | Official IDs                                                          | Gateway variants                                                                                                                                |
+| ---------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Gemini 3         | `gemini-3.1-pro-preview`, `gemini-3.5-flash`, `gemini-3.1-flash-lite` | —                                                                                                                                               |
+| Gemini 3 image   | `gemini-3.1-flash-image-preview`, `gemini-3-pro-image-preview`        | —                                                                                                                                               |
+| Gemini 3 TTS     | `gemini-3.1-flash-tts-preview`                                        | —                                                                                                                                               |
+| Gemini embedding | `gemini-embedding-2`                                                  | —                                                                                                                                               |
+| Claude           | `claude-sonnet-4-6`, `claude-opus-4-7`, `claude-opus-4-8`             | —                                                                                                                                               |
+| GPT              | `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5`                  | —                                                                                                                                               |
+| OpenAI embedding | `text-embedding-3-small`, `text-embedding-3-large`                    | —                                                                                                                                               |
+| Kimi K2.6        | `kimi-k2.6`                                                           | OpenRouter `moonshotai/kimi-k2.6`; SiliconFlow `Pro/moonshotai/Kimi-K2.6`                                                                       |
+| DeepSeek V4      | `deepseek-v4-pro`, `deepseek-v4-flash`                                | OpenRouter `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`; SiliconFlow `deepseek-ai/DeepSeek-V4-Pro`, `deepseek-ai/DeepSeek-V4-Flash` |
+| GLM 5.1          | `glm-5.1`                                                             | OpenRouter `z-ai/glm-5.1`; SiliconFlow `Pro/zai-org/GLM-5.1`                                                                                    |
+
+Gateway model lists can be queried online:
+
+```bash
+curl https://openrouter.ai/api/v1/models
+curl --request GET --url https://api.siliconflow.cn/v1/models --header 'Authorization: Bearer <token>'
+```
+
+## Routing and credentials
+
+- Without `clientType`, the client auto-routes by model id substring: `gemini-3*`, `gemini-embedding`, `claude` 4-6/4-7/4-8, `gpt-5.4`/`gpt-5.5`, `glm-5`, `kimi-k2.5`/`kimi-k2.6`, `deepseek-v4`, `openai`+`embedding` (embeddings), `openai`. Ids matching none of these throw. The gateway variants in the table above hit the same substrings, so they route to the right family — just set `baseUrl` to the gateway endpoint.
+- For any other OpenAI chat-completion compatible model (e.g. Qwen series via OpenRouter or SiliconFlow), pass `clientType: "openai"` plus `baseUrl` (embeddings endpoints use a different client type — see Embeddings below).
+- API key: constructor parameter first, then the provider environment variable — `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, `MOONSHOT_API_KEY`. Base URLs read the same names with `_BASE_URL`.
+
+## Streaming text
+
+```ts
+for await (const event of client.streamingResponseStateful({
+  message: { role: "user", content_items: [{ type: "text", text: "Hello" }] },
+  config: {},
+})) {
+  for (const item of event.content_items) {
+    if (item.type === "text") process.stdout.write(item.text);
+  }
+}
+```
+
+- Each `event` is a `UniEvent`: `event_type` is `start` | `delta` | `stop`, and `content_items` carry the increments.
+- `config` accepts `max_tokens`, `temperature`, `system_prompt`, `thinking_level` (the `ThinkingLevel` enum, `NONE` to `XHIGH`) and `tools`.
+- `streamingResponseStateful` keeps conversation history inside the client; manage it with `getHistory()` / `setHistory(history)` / `clearHistory()`. The stateless variant is `streamingResponse({ messages, config })`.
+
+## Image generation
+
+Use a Gemini image model (see Model IDs) and set `config.image_config` (optional `aspect_ratio`, and `image_size` of `"1K"` | `"2K"`):
+
+```ts
+import fs from "node:fs";
+
+const client = new AutoLLMClient({ model: "gemini-3.1-flash-image-preview" });
+for await (const event of client.streamingResponseStateful({
+  message: { role: "user", content_items: [{ type: "text", text: "A penguin on a glacier" }] },
+  config: { image_config: { aspect_ratio: "16:9", image_size: "2K" } },
+})) {
+  for (const item of event.content_items) {
+    if (item.type === "inline_data") fs.writeFileSync("image.png", item.data);
+  }
+}
+```
+
+Images arrive as `inline_data` content items (`data` is a Buffer, with `mime_type`).
+
+## Speech synthesis
+
+Use a Gemini TTS model (`gemini-3.1-flash-tts-preview`) and set `config.tts_config`:
+
+```ts
+config: { tts_config: [{ voice: "Kore" }] }
+```
+
+- One entry → single voice; two entries → multi-speaker, and each entry must also set `speaker`.
+- The `inline_data` output is raw PCM (24kHz 16-bit mono) — wrap it in a WAV header yourself before saving as `.wav`.
+
+## Embeddings
+
+Two routes:
+
+- Gemini: a model whose id contains `gemini-embedding` auto-routes (`gemini-embedding-2`).
+- Any OpenAI-compatible embeddings endpoint: pass `clientType: "openai-embedding"` (plus `baseUrl` and `apiKey` as needed) — ids like `text-embedding-3-small` / `text-embedding-3-large` match no auto-route substring and would throw without it.
+
+Optional `config.embedding_config`:
+
+```ts
+config: { embedding_config: { dimensions: 768 } }
+```
+
+The output arrives as `embedding` content items (`embedding` is a number array).

package/skills/agenthub-models/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="12" r="2.6" />
+  <circle cx="5" cy="5" r="1.9" />
+  <circle cx="19" cy="5" r="1.9" />
+  <circle cx="12" cy="20" r="1.9" />
+  <path d="M10.2 10.2 6.3 6.3" />
+  <path d="M13.8 10.2 17.7 6.3" />
+  <path d="M12 14.6v3.5" />
+</svg>

package/skills/benchmark-design/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: benchmark-design
+description: Design and calibrate a multi-Case capability Benchmark with repeated independent evaluations and a traceable baseline.
+short_description: Design and calibrate an Agent capability Benchmark.
+short_description_zh: 设计并校准 Agent 能力评测 Benchmark。
+version: 1
+updated: 2026-07-17T17:08:17Z
+---
+
+# Benchmark Design
+
+Create and calibrate a multi-Case Benchmark that discovers a specified Test Agent's capability boundary. Own the public Statements, private Rubrics, Case set, configuration, and final baseline. Do not modify the Test Agent State, launch the Test Agent directly, or score a Case yourself.
+
+## Before you start
+
+Require a Test Agent and the capability to measure. If either is missing, ask the user. A Benchmark run also requires a top-level Session with `run_subagent` and the current Agent must have `agent-evaluation` installed. If the Skill is missing or this Session is already a subagent, stop and ask the user to install the Skill or start a top-level Session. Do not begin a partial Benchmark.
+
+## Boundaries
+
+Access only the explicit Test Agent and Benchmark paths. Do not inspect another Agent, Project configuration files, Agent Evaluator State, Evaluator Workspace, or Evaluator Trace. Consume only each Evaluator's terminal protocol response and the returned Test Session id.
+
+Use the Environment's Project Dir and the explicit Test Agent id:
+
+```text
+PROJECT_DIR = <project_dir>
+PROJECT_ID = <basename_of_project_dir>
+PENGUIN_HOME = <parent_of_project_dir>
+TEST_AGENT_DIR = <project_dir>/agents/<test_agent_id>
+BENCHMARK_DIR = <project_dir>/agents/<test_agent_id>/benchmarks/<benchmark_id>
+SCOREBOARD = <benchmark_dir>/scoreboard.yaml
+```
+
+Derive a semantic Benchmark id when the user does not supply one. Require `agent_state/system_config.yaml`; its top-level `version` is the canonical State version and defaults to 1 when absent.
+
+## Benchmark contract
+
+Use this structure:
+
+```text
+<benchmark_id>/
+├── benchmark_config.toml
+├── scoreboard.yaml
+└── CASE-<nnn>-<semantic-name>/
+    ├── statement/
+    │   └── README.md
+    └── rubric/
+        └── README.md
+```
+
+Both README files are required; either directory may contain supporting files. `statement/` is the complete public task and evidence. `rubric/` is private scoring material. Never mention private criteria or paths in the Statement.
+
+Create `benchmark_config.toml` first. The Model is deliberately not stored here; each evaluation records the actual `(provider, model_id)` pair.
+
+```toml
+title = "<benchmark_title>"
+description = "<capability_and_scope>"
+runs = 3
+```
+
+Use `runs = 3` unless the user explicitly requests another positive integer. Initialize the Scoreboard with:
+
+```yaml
+evaluations: []
+```
+
+Every accepted evaluation follows scoreboard v2:
+
+```yaml
+evaluations:
+  - time: "2026-07-17T00:00:00Z"
+    version: 1
+    provider: deepseek
+    model_id: deepseek-v4-pro
+    summary_title: "Calibrated baseline"
+    summary: "Abbreviated baseline schema for one Case with three independent runs."
+    score: 18
+    cost: 0.04
+    duration_ms: 60000
+    cases:
+      - case: CASE-001-example
+        score: 18
+        cost: 0.04
+        duration_ms: 60000
+        runs:
+          - score: 17
+            cost: 0.03
+            duration_ms: 58000
+            session_id: session-1
+          - score: 18
+            cost: 0.04
+            duration_ms: 60000
+            session_id: session-2
+          - score: 19
+            cost: 0.05
+            duration_ms: 62000
+            session_id: session-3
+```
+
+Case `score`, `cost`, and `duration_ms` are the means of their valid `runs`. Evaluation totals are the sums of the Case means. Omit a Case or evaluation `cost` when any contributing run has unknown cost; never treat unknown as zero. Rubric maxima across the complete Case set should total 100 points so the evaluation score remains interpretable on a 0–100 scale.
+
+Builder writes one final baseline for the current Benchmark definition. A material change to a Statement, Rubric, Case set, or `runs` invalidates prior results: clear `evaluations`, recalibrate, and write a new baseline. Rejected candidates and provisional matrices remain only in Builder Trace. Evaluator never writes the Scoreboard.
+
+The public `summary_title` and `summary` may describe the tested State, Case-level score patterns, and instability. They must not reveal Rubric or Gold content, expected answers, private scoring reasoning, mappings, thresholds, formulas, or rules.
+
+## Design and calibrate
+
+Before writing Cases, define the observable difference between an Agent that has the requested capability and one that does not. Each Case must make that capability causally necessary, not merely share its topic.
+
+Run this counterfactual before accepting a Case: could a competent executor without the target capability complete it by mechanically following the Statement? If yes, reject or redesign it. A self-contained Statement specifies the task, available evidence, and required artifact without disclosing the reasoning, mapping, or rule the capability is supposed to recover. The evidence must still make the answer inferable.
+
+Build several independent, realistic end-to-end Cases with distinct capability-relevant failure modes. Do not manufacture low scores through missing essential evidence, trivia, formatting traps, excessive workload, or unstable infrastructure.
+
+Freeze every Rubric before evaluation. Use atomic observable conditions, exact points, reasonable equivalence rules, and meaningful partial credit. Test the Rubric mentally against full, partial, missing, malformed, wrong-type, and extra output. Never execute Test Agent-produced code while scoring.
+
+Use valid evidence to calibrate toward a user-supplied target; otherwise aim near 60/100. Treat a near-ceiling candidate as uncalibrated when a credible structural refinement remains. Audit high scores for shortcuts or leakage and low scores for ambiguity, missing evidence, unrelated difficulty, or a defective Rubric. More items, steps, or workload alone are not structural refinement.
+
+## Select the evaluation Model
+
+Use a user-specified `(provider, model_id)` pair when supplied. Otherwise resolve the Project default with the supported CLI, never by reading the hidden Project configuration:
+
+```bash
+penguin config model list --project-id "<project_id>" --root "<penguin_home>"
+```
+
+The row marked `*` is the default. Keep the same pair through all candidate matrices for this calibration. The pair selects the Test Agent's CLI Session, not the Builder or Evaluator runtime model.
+
+## Run the Case-run matrix
+
+Read and retain the exact State version, Scoreboard bytes, configured positive `runs`, selected Model pair, and complete valid Case set. Build every unique Case-run cell before dispatch.
+
+Start one child per cell with `run_subagent`, and omit `agent_id` so the child reuses the current Agent. Each prompt must begin with the caller identity and the sentence: Use the `agent-evaluation` Skill. Then provide exactly one request:
+
+```text
+Caller agent: <current_agent_id>
+Use the `agent-evaluation` Skill. Return only its terminal protocol YAML.
+protocol_version: 1
+case_id: <case_id>
+run: <1_based_run_index>
+expected_version: <tested_agent_state_version>
+test_agent_id: <test_agent_id>
+benchmark_dir: <absolute_benchmark_dir>
+provider: <provider>
+model_id: <upstream_model_id>
+```
+
+For N Cases and R runs, emit all N × R independent `run_subagent` calls in the same parallel tool-call group before waiting for results. Continue an active child through `input_subagent`; never duplicate it.
+
+Parse only the last terminal `protocol_version: 1` YAML mapping. Keep every identity-matched `status: ok` result. Retry only invalid cells once, with all retry cells dispatched together and the same State version, Model, Benchmark, and run identities. Never retry a valid scored cell. If any retry remains invalid, abandon the matrix.
+
+For a complete matrix, calculate Case means and evaluation sums using scoreboard v2. Retain every run's score, cost when known, duration, and Test Session id. Re-read State version and exact Scoreboard bytes; abandon the result if either changed.
+
+Use each returned Test Session id to inspect the exact Test Trace and artifact. Analyze all repeated runs; disagreement is capability instability, not permission to select a convenient result. Accept a candidate only when the capability caused the scored difference, evidence was sufficient, the Rubric was sound, and useful headroom remains.
+
+When calibration stops after a complete valid matrix, write the final baseline to a temporary sibling, parse it as YAML, then atomically rename it over `scoreboard.yaml`. Include the sorted Case set and sorted runs, a real UTC ISO-8601 time, the tested version and Model pair, and a privacy-safe summary. A near-ceiling final score is still recorded, but if the refinement budget ends without an acceptable candidate, report `calibration_failed` rather than calling the Benchmark ready. Leave `evaluations` empty only when no complete valid matrix exists.
+
+Report the Benchmark path, aggregate and Case scores, Test Session ids, refinements, stop reason, and limitations.

package/skills/benchmark-design/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="4" y="4" width="16" height="16" rx="2" />
+  <path d="M8 8h8" />
+  <path d="M8 12h5" />
+  <path d="M8 16h3" />
+  <path d="m15 15 1.4 1.4L19 13.8" />
+</svg>

package/skills/data-analysis/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: data-analysis
+description: Complete data-analysis tasks with bounded evidence inspection, explicit answer-changing decisions, native artifact handling, and final output verification.
+short_description: Complete data analysis with a bounded, verified method.
+short_description_zh: 以有界、可验证的方法完成数据分析任务。
+version: 1
+updated: 2026-07-18T00:00:00Z
+---
+
+# Data Analysis
+
+## Before you start
+
+Require a concrete data-analysis task, its available inputs, and the requested deliverable, location, and format. If the task or required materials are missing or ambiguous in an answer-changing way, ask before calculating or creating outputs. Otherwise proceed without forcing a fixed analysis template.
+
+## Success criteria
+
+- Derive the final result from one committed method: the selected evidence, answer-changing decisions, transformations, calculations, and judgments.
+- Produce every output the task asks for, in the requested location and format, and ensure it reflects the committed method.
+- Ground each answer-changing choice in the task materials rather than in a merely plausible nearby match.
+- Prefer a complete, simple, defensible deliverable over an elaborate or exhaustive analysis that risks not being delivered.
+
+## Constraints
+
+- Use bounded probes first for large, unfamiliar, or expensive-to-read inputs. Narrow the scope, cap output, or use a timeout before expanding.
+- Before calculating or producing final outputs, identify the few decisions that can change the answer, such as inclusion or exclusion, matching, boundary choices, transformations, formulas, and ranking criteria. Adapt this check to the task; do not force a fixed analysis template.
+- Compare materially plausible alternatives only when they would change the final output. Use the smallest comparison needed to resolve the choice from the task materials, then commit to a method.
+- Once the evidence supports a defensible answer, create the requested output files promptly. Do not continue open-ended thinking, searching, or polishing over alternatives that would not change the delivered answer.
+- Use intermediate files only when they help compute or verify the result. Preserve the requested output format and structure unless the task asks for a change.
+- Satisfy the requested deliverable with the simplest sufficient artifact and implementation. Avoid optional structure, styling, helper code, or reimplementation that is not required by the task.
+- Keep final delivery steps short and robust. Avoid putting a long report, large dataset, or large script into one fragile streamed command when the deliverable can be created by shorter steps. Create the required artifact first, then refine only if the required outputs already exist.
+- For spreadsheet or Office deliverables, prefer the tool path that preserves the native artifact contract. If a task depends on Excel formula recalculation, data tables, workbook formatting, or Office export, first check whether native Excel automation such as `xlwings` is available before falling back to LibreOffice or a hand-rolled model. Record formulas or inputs that will be temporarily overwritten, restore them before finalizing, and verify that the requested workbook, deck, document, or PDF can be opened and contains the expected tables, sheets, slides, or sections. Do not dump or reimplement an entire workbook when bounded input changes and output reads can answer the task.
+- When creating spreadsheet tables, keep each table as one contiguous rectangle: title or caption, row-axis labels, column-axis labels, and data cells should be adjacent and inspectable together. Do not place row labels or key headers outside the visible table bounds or to the left of the title anchor. If you add decorative axis labels, keep the actual machine-readable row and column values inside the same table rectangle.
+
+## Stop rules
+
+- Before finalizing, inspect the requested outputs and check their location, format, shape, and content against the committed method and the task.
+- If a later finding changes the method, assumptions, selections, transformations, calculations, decisions, or coverage, regenerate the affected outputs before finalizing.
+- Once the requested outputs exist and the relevant checks pass, stop instead of continuing open-ended exploration.

package/skills/data-analysis/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M4 4.5v15h16" />
+  <path d="m7 15 3-3 3 2 4-6" />
+  <path d="M7 18v1.5M10 18v1.5M13 18v1.5M17 18v1.5" />
+</svg>