@prismshadow/penguin-skills 0.0.1

package/skills/penguin-cli/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: penguin-cli
+description: Manage model API keys, default models and per-agent vault secrets with the penguin CLI.
+short_description: Manage models and secrets with the penguin CLI.
+short_description_zh: 用 penguin CLI 管理模型与密钥。
+version: 1
+updated: 2026-07-17T00:00:00Z
+---
+
+# Penguin CLI
+
+The `penguin` CLI manages model credentials, default models and per-agent vault secrets. Configuration goes through the CLI only — never read or hand-edit the underlying hidden files.
+
+## Before you start
+
+If the user's message only invokes this skill (e.g. "use penguin-cli skill") without a concrete request, ask the user what they want to configure. Do not run any command until the goal is clear.
+
+## Models
+
+Add or update a model (upsert by the stored model id; re-run with more options to amend an entry):
+
+```bash
+penguin config model add --model-id <upstream_id> [--provider <group>] [--api-key <key>] [--base-url <url>] \
+  [--client-type <type>] [--context-window <n>] [--vision | --no-vision] \
+  [--price-cache-read <n>] [--price-cache-write <n>] [--price-output <n>] \
+  [--project-id <id>] [--root <dir>] [--set-default]
+```
+
+- `--model-id` takes the provider's upstream model id (what the API expects). The stored id is always `<provider>/<upstream_id>`: `--provider` picks the provider group, and when omitted it is inferred from the built-in catalog (unrecognized ids fall back to `custom`). The upstream id is persisted automatically as the entry's request id, so nothing extra is needed for it to reach the API unchanged.
+- For any OpenAI chat-completion compatible endpoint use `--client-type openai --base-url <endpoint>`; omit `--client-type` to auto-route by model id.
+- Prices are USD per million tokens (cache read / cache write / output).
+- `--vision` / `--no-vision` mark whether the model accepts images; omitting both keeps the current value (default is vision-capable).
+- All `penguin config model ...` and `penguin config vault ...` commands accept `--root <dir>` to target another data root (default `PENGUIN_HOME`, then `~/.penguin/data`).
+
+Other model commands:
+
+```bash
+penguin config model default --model-id <upstream_id> --provider <group> [--root <dir>]   # set the project default model
+penguin config model vision --model-id <upstream_id> --provider <group> [--root <dir>]    # set the project vision model (reads images for text-only sessions)
+penguin config model list [--root <dir>]                      # list models; api_key is shown masked
+```
+
+## Vault (per-agent secrets)
+
+The vault holds an agent's environment-variable secrets (third-party API keys etc.); values are injected into that agent's shell subprocesses:
+
+```bash
+penguin config vault set --key <NAME> --value <value> [--project-id <id>] [--agent-id <id>] [--root <dir>]
+penguin config vault list [--project-id <id>] [--agent-id <id>] [--root <dir>]      # values are shown masked
+penguin config vault remove --key <NAME> [--project-id <id>] [--agent-id <id>] [--root <dir>]
+```
+
+- `--project-id` defaults to `default_project`, `--agent-id` to `default_agent`.
+- Key names follow shell variable rules (letter or underscore first, then letters, digits and underscores); values are limited to 8192 characters.
+
+## Language
+
+```bash
+penguin config lang <en|zh>   # persist the CLI language via PENGUIN_LANG in your shell rc
+```
+
+## Running agents
+
+`penguin run -m "<task>" [--model-id <id>] [--agent-id <id>] [--workspace <path>] [--approve <mode>]` runs one task; `penguin chat [--resume [session_id]]` starts or resumes an interactive chat with the same options.
+
+## Storage
+
+- `<project_dir>/.project_config.toml` — the project's single hidden config file: model list, settings and per-model credentials (`api_key` etc. inlined in each model entry). Configuration is CLI-only — never read, print or hand-edit this file.
+- `<project_dir>/agents/<agent_id>/agent_state/.vault.toml` — that agent's vault entries, hidden file; same rule, manage it with `penguin config vault`.

package/skills/penguin-cli/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">
+  <rect x="3" y="4.5" width="18" height="15" rx="2" />
+  <path d="M7 9.5l3.2 2.7L7 14.9" />
+  <path d="M12.7 15.5h4.3" />
+</svg>

package/skills/penguin-sdk/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: penguin-sdk
+description: Build AI apps on the Penguin Harness SDK — self-contained projects inside the Workspace, model configuration, and the createSession/run streaming loop.
+short_description: Build AI apps on the Penguin Harness SDK.
+short_description_zh: 基于 Penguin Harness SDK 构建 AI 应用。
+version: 1
+updated: 2026-07-17T00:00:00Z
+---
+
+# Penguin Harness SDK
+
+`@prismshadow/penguin-core` is the TypeScript SDK this agent itself runs on. Use it to build your own AI apps:
+
+- An **Agent** loads its state (prompts, tools, skills) from `<root>/<project_id>/agents/<agent_id>/`. Creating an Agent whose directory is empty initializes it with defaults.
+- A **Session** is one conversation of an Agent inside a **Workspace** directory.
+- `session.run()` executes one task and streams every step (thinking, text, tool calls) as OmniMessages.
+
+To have an agent perform a task, use the `run_subagent` tool — the SDK is for building applications, not for invoking agents.
+
+## Before you start
+
+If the user's message only invokes this skill (e.g. "use penguin-sdk skill") without a concrete app to build, ask the user what they want to build. Do not start until the requirement is clear.
+
+## Project location
+
+Create the app in the current workspace directory by default (the `CWD` value from your Environment section), as a self-contained project — do not place it under `<project_dir>` or depend on any path outside the project folder. Point the agent data root at a directory inside the project with `createAgent({ root })`, resolved from the source file so it stays relative:
+
+```ts
+const agent = await createAgent({ root: path.resolve(import.meta.dirname, "penguin_data") });
+```
+
+With every reference relative to the project, the user can move or copy the folder anywhere and it still runs.
+
+## Setup
+
+```bash
+npm install @prismshadow/penguin-core
+```
+
+If the package is not yet available on your npm registry (it is developed in the PenguinHarness monorepo and may not be published), develop inside a checkout of the PenguinHarness repo instead: add your app as a workspace package under `packages/` and depend on `"@prismshadow/penguin-core": "workspace:*"`, then run `pnpm install && pnpm build` at the repo root. Tell the user which route you took.
+
+A model must be configured for the app's data root. Two ways:
+
+1. The penguin CLI, pointed at the project-local data directory:
+
+```bash
+penguin config model add --root <data_dir> --model-id <id> --api-key <key> [--base-url <url>] [--client-type openai] --set-default
+```
+
+Generally prefer the OpenAI protocol client (chat completion): `--client-type openai --base-url <endpoint>` works with any OpenAI-compatible endpoint. Use exact model ids — see the agenthub-models skill for the id table.
+
+2. Environment variables as a fallback: without a configured credential the SDK reads the provider's env vars (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`).
+
+Model config lives in a single hidden file under the data root's project directory: `.project_config.toml` (model list, settings and per-model credentials such as `api_key` inlined in each model entry). It is CLI-only — never read, print or edit it; the CLI above manages it.
+
+## Minimal conversational app
+
+```ts
+import path from "node:path";
+import readline from "node:readline/promises";
+import { createAgent, userText } from "@prismshadow/penguin-core";
+
+const agent = await createAgent({ root: path.resolve(import.meta.dirname, "penguin_data") });
+const session = await agent.createSession({ workspaceDir: process.cwd() });
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+for (;;) {
+  const line = await rl.question("> ");
+  if (!line.trim()) break;
+  // One run per user turn; the same Session keeps the conversation context.
+  for await (const msg of session.run([userText(line)], {
+    approve: async () => "allow", // demo only — a real app should ask its user ("deny" blocks the call)
+  })) {
+    const p = msg.payload;
+    if (p.type === "partial_text" && p.event_type === "delta") process.stdout.write(p.text);
+  }
+  process.stdout.write("\n");
+}
+rl.close();
+```
+
+Key points:
+
+- An Agent's behavior is edited in its `agent_state/` files (system_config.yaml, AGENTS.md, skills/), not in code.
+- `createSession({ workspaceDir, modelId })` — omit `workspaceDir` for a temporary workspace, omit `modelId` for the project default model.
+- `session.run(messages, { approve, signal })` is an async generator of OmniMessages; filter the payload types you care about (`partial_text` deltas carry the streamed answer).
+- The `approve` callback gates every tool call — auto-allow is for demos; a production app should prompt its user before returning `"allow"`.
+- Call `session.run()` again on the same Session for the next user turn — the context carries over.

package/skills/penguin-sdk/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="m12 3 8 4.5v9L12 21l-8-4.5v-9z" />
+  <path d="m4 7.5 8 4.5 8-4.5" />
+  <path d="M12 12v9" />
+  <path d="m8 5.25 8 4.5" />
+</svg>

package/skills/software-engineering/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: software-engineering
+description: Complete software-engineering tasks — investigate and review code, implement bug fixes, features and refactors with minimal scope, validate changes, and report verified outcomes.
+short_description: Complete software-engineering tasks.
+short_description_zh: 完成软件工程任务。
+version: 1
+updated: 2026-07-18T00:00:00Z
+---
+
+# Software Engineering
+
+This skill guides PenguinHarness through general software-engineering work, including code investigation, reviews, bug fixes, features, refactors, and verified handoff.
+
+## Before you start
+
+If the user's message only invokes this skill without a concrete software-engineering task, ask what they want investigated, reviewed, fixed, or implemented. Do not start until the task is clear.
+
+## Workflow
+
+- Match the work to the user's intent. For explanation, review, or planning requests, inspect and report without editing unless a change is also requested. For implementation tasks, carry the requested change through verification and handoff.
+- Use the current working directory as the target project and work in place unless the user directs otherwise.
+- Preserve worktree changes you did not make. Never revert unrelated user or collaborator work, and do not use destructive Git commands unless explicitly requested.
+- Act autonomously and use tools to understand the real code. Resolve minor ambiguity from existing behavior, tests, and repository conventions; ask only when different choices would materially change the requested behavior or scope.
+- Before making changes, read the applicable repository instructions (such as `AGENTS.md` or `CLAUDE.md`) and identify the repository-provided build, test, lint, and formatting commands.
+- Inspect the relevant implementation, callers, tests, and interfaces before making changes.
+- For bug reports, try to reproduce the issue or identify a failing test before editing when feasible. Use the reproduced behavior or failing test to verify the fix afterward.
+- Make the smallest coherent change that fully satisfies the request. Follow existing patterns and dependencies, preserve unrelated behavior, and update coupled tests, schemas, configuration, or generated artifacts only when the repository requires it. Never weaken a test to justify the implementation.
+- For implementation tasks, do not stop after analysis. Inspect failures, revise the approach, and continue until the change is verified or a concrete blocker remains. Do not repeat a failed action without changing the approach.
+- Validate code changes proportionally with repository-provided commands: run the most focused relevant check first and broaden only when useful. Preserve exit status, inspect relevant failure output, and never claim that an unobserved check passed.
+- Before finishing a code change, review `git diff` and repository status, remove temporary artifacts, and keep the change limited to the task. Do not commit unless the user or applicable repository instructions require it.
+
+## Handoff
+
+- Keep the final response concise: summarize the outcome or change, list checks actually run and their outcomes, and state any remaining limitation.

package/skills/software-engineering/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="M8.5 8 5 12l3.5 4" />
+  <path d="M15.5 8 19 12l-3.5 4" />
+  <path d="M13.3 6.2 10.7 17.8" />
+</svg>

package/skills/web-design/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: web-design
+description: Default visual language for generated web pages — minimal black-white-gray, square corners, hierarchy from weight and spacing; colors, radii and gradients only on explicit request.
+short_description: Minimal monochrome defaults for generated web pages.
+short_description_zh: 生成网页的极简黑白默认视觉规范。
+version: 1
+updated: 2026-07-17T00:00:00Z
+---
+
+# Web Design
+
+Default visual rules for every web page or frontend interface you generate. Apply them to any HTML/CSS you produce unless the user explicitly asks otherwise.
+
+## Before you start
+
+If the user's message only invokes this skill (e.g. "use web-design skill") without a concrete page or interface to build, ask the user what they want to build. Do not start until the requirement is clear.
+
+## Core rules
+
+- Monochrome only: black, white and grays. No accent colors, no gradients, no decorative shadows.
+- Square corners everywhere: `border-radius: 0` on buttons, cards, inputs, images and modals.
+- Hierarchy comes from font weight, font size, spacing and thin light-gray borders — never from colored blocks or backgrounds.
+- Generous whitespace: prefer more spacing over more dividers; let sections breathe.
+- Introduce colors, rounded corners or gradients **only when the user explicitly asks for them**, and only where asked — the rest of the page stays monochrome and square.
+
+## Tokens
+
+Base every stylesheet on a small monochrome token set:
+
+```css
+:root {
+  --fg: #111111; /* primary text */
+  --fg-muted: #666666; /* secondary text */
+  --bg: #ffffff; /* page background */
+  --bg-subtle: #f5f5f5; /* raised surfaces */
+  --border: #e2e2e2; /* hairline borders (1px) */
+}
+```
+
+Tailwind equivalent: stick to `text-neutral-900` / `text-neutral-500` / `bg-white` / `bg-neutral-100` / `border-neutral-200` / `rounded-none`; do not use color utilities (`blue-*`, `emerald-*`, ...), `rounded-*` variants other than `rounded-none`, or `bg-gradient-*`.

package/skills/web-design/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">
+  <rect x="3" y="4.5" width="18" height="15" />
+  <path d="M3 9h18" />
+  <path d="M6 6.75h.01" />
+  <path d="M8.7 6.75h.01" />
+  <path d="M9 9v10.5" />
+  <path d="M12 12.5h6" />
+  <path d="M12 15.5h3.5" />
+</svg>