Skip to main content
Agent skill

Penguin Config

Manage model API keys, default models and per-agent vault secrets with the penguin CLI.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Penguin Config when an AI agent needs a reusable SKILL.md workflow for this job: Manage model API keys, default models and per-agent vault secrets with the penguin CLI.

When not to use it

Skip Penguin Config when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/penguin-config
# Save SKILL.md to ~/.claude/skills/penguin-config/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/penguin-config/SKILL.md. For a shared project, commit the folder at .claude/skills/penguin-config/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Penguin Config skill for this task: Use Penguin Config when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

68/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
68/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptinferred

    The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Penguin Config (CLI)

The `penguin` CLI manages model credentials, default models and per-agent vault secrets. Its primary job is model configuration: `penguin config model add` registers a model, or — without `--model-id` — gives a whole group its key, base URL or protocol, and `penguin config model list` shows the groups' connections and the models currently available. 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 `(provider, model_id)` pair; re-run with more options to amend an entry):

```bash penguin config model add --provider <group> --model-id <upstream_id> [--api-key <key> | --clear-api-key] \ [--base-url <url> | --clear-base-url] [--client-type <type> | --clear-client-type] \ [--context-window <n>] [--max-tokens <n>] [--vision | --no-vision] [--fast-mode | --no-fast-mode] \ [--price-cache-read <n>] [--price-cache-write <n>] [--price-output <n>] \ [--project-id <id>] [--root <dir>] [--set-default] ```

- A model is identified by the `(provider, model_id)` pair, so `--provider` and `--model-id` are **both required** to name one — the group is never inferred from the model id, because gateways resell vendor models under their upstream ids and a wrong guess would send the key to another vendor's endpoint. `--model-id` takes the provider's upstream model id (what the API expects) and is persisted as the entry's request id, so it reaches the API unchanged; `--provider` names the group (`deepseek`, `openai`, `anthropic`, `google`, `openrouter`, `siliconflow`, … — `custom` for any other endpoint). - Only `custom`, `vllm`, `openrouter`, `tokendance`, `siliconflow`, `atlascloud` and groups of your own take models added by hand. Every other built-in group carries its catalog models only: `model add` there accepts one of that group's catalog model ids (to set its key, limits or prices, or to bring it back) and refuses any other id with "cannot be added". Add such a model under `custom` with `--base-url`, or under a group of your own. - `--api-key`, `--base-url` and `--client-type` set the model's **own** values, and `--clear-api-key`, `--clear-base-url` and `--clear-client-type` remove them. Omitted, the model follows its group (see [Group connection](#group-connection)), and with no group value it gets the client's default; the built-in catalog is never consulted. A model added to `openrouter`, `tokendance` or `siliconflow` needs only `--provider` and `--model-id` once the group has a key: a new Project already stores those gateways' endpoint and protocol on the group. For an OpenAI chat-completion compatible endpoint under `custom` or a group of your own, use `--client-type openai --base-url <endpoint>`, or set both once on the group; in a vendor group, 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). - `--max-tokens <n>` pins a per-model output cap (positive integer), overriding the Agent's `model.max_tokens`; omit to inherit. Lower it for small-context models — the per-Agent default (32000) cannot fit into e.g. a 32k context window together with any prompt. - All `penguin config model ...` and `penguin config vault ...` commands accept `--root <dir>` to target another data root (default `PENGUIN_HOME`, then `~/.penguin/data`). Two configuration targets — treat the difference as a hard rule: - **Penguin's own model** (self-configuration: the model Penguin itself runs on): pass `--root <data root>` as well — the parent directory of the App Data Dir named in your Environment section. An agent running inside PenguinHarness never sees `PENGUIN_HOME`: the harness strips every `PENGUIN_*` variable from a command's environment, so a command without `--root` falls back to `~/.penguin/data` and configures a root the running server does not read. - **An AI app you are building**: `--root` **must** point at the app's own data directory inside the project (e.g. `--root ./penguin_data`, the same path the app gives `createAgent({ root })`) unless the user explicitly chose another location — never write an app's models or keys into the global `~/.penguin/data`, which belongs to the person running Penguin, not to the app. - While developing an app, review regularly: `penguin config model list --root <app root>` should show the app's entries, and the global list (no `--root`) should stay clean.

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>] # the groups' connections, then the models with the connection each uses; api_key masked, (provider) = from the group, (env) = from an environment variable penguin config model remove --model-id <upstream_id> --provider <group> [--root <dir>] # remove one model ```

## Group connection

A group holds one connection — API key, base URL, protocol — in its `[providers.<group>]` table, and every model in it without a value of its own follows it. Each field resolves on its own from the config file alone: the model's value, else the group's, else nothing (the client's default endpoint, MMSP routing by model id, the environment key where allowed). The built-in catalog is only a reference: a new Project's file already stores each gateway's endpoint and protocol on its group. Set a key once on the group rather than on every model. `model add` and `model remove` without `--model-id` act on the group:

```bash penguin config model add --provider <group> [--api-key <key> | --clear-api-key] [--base-url <url> | --clear-base-url] \ [--client-type <type> | --clear-client-type] [--project-id <id>] [--root <dir>] penguin config model remove --provider <group> [--project-id <id>] [--root <dir>] # removes the group's connection only; its models stay ```

- A field you do not name is left as it is. An empty value is refused: remove a field with its `--clear-*` flag. - The flags that describe one model (`--context-window`, `--max-tokens`, `--vision`, `--fast-mode`, `--price-*`, `--set-default`) are refused without `--model-id`; nothing is written. - Any group but `penguin-go` takes a protocol, `opencode-go` included: a model's own protocol always wins over its group's. `penguin-go` is fixed to `mmsp`, for its models too: another `--client-type`, or `--clear-client-type` on the group, is refused. - The group key never replaces a key set on one model with `model add --api-key`; the command says how many models keep their own. It reaches only the models that go to the group's endpoint: a model whose own `--base-url` is on another host (scheme, host and port) needs its own `--api-key`. - For a group of your own on one endpoint, set its connection first, then add each model with only `--provider` and `--model-id`: the models store nothing and follow the group. Removing the group's last model removes its connection too.

## 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>" [--provider <group> --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. The model reference stays a pair here too: pass `--provider` and `--model-id` together, or neither to run on the project's default model — one without the other is rejected.

## Storage

Paths use `<app_data_dir>`, the App Data Dir value from your Environment section.

- `<app_data_dir>/.project_config.toml` — the project's single hidden config file: model list, settings, each group's connection (`[providers.<group>]`) and the values a model overrides (`api_key` etc. on its entry). Configuration is CLI-only — never read, print or hand-edit this file. - `<app_data_dir>/agents/<agent_id>/agent_state/.vault.toml` — that agent's vault entries, hidden file; same rule, manage it with `penguin config vault`.

Intended uses

  • Use Penguin Config when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.