/agent-initialization

name: agent-initialization
description: Initialize or extend an Agent from a user requirement - write AGENTS.md, set identity metadata, and create, install or import Skills and hook packages (scripts the harness runs on every prompt, before tool calls, or after a task). For an Agent with an in-app workbench, pair with penguin-plugin; for a standalone external program, use penguin-sdk.
version: 2026.11.07.1

Agent Initialization

This skill initializes an agent's settings from a user requirement — plain files in the target agent's directory. It is also the reference for giving an agent, yourself included, a new Skill or a new hook: both are directories you write, and the harness picks them up from disk.

Before you start

If the user's message only invokes this skill (e.g. "use agent-initialization skill") without a concrete requirement, ask the user what agent they want and what it should do. But when the requirement is already concrete — even a single sentence like "an expert that answers questions about X" — do **not** ask follow-up questions: derive the role and rules from that sentence, apply the defaults below, and list your assumptions in the final reply.

An Agent Workbench inside PenguinHarness already has its runtime: create the new Agent and follow `penguin-plugin` for its tab. No SDK/API question is needed. Only an external program without a chosen architecture needs the question below.

An agent for a program

An external program — an app, a service, a bot, a script outside PenguinHarness — reaches a Penguin agent either embedded with the SDK or through the Penguin server's Agent API, and the two put the agent in different places. That choice is the penguin-sdk skill's, in this same plugin: whenever the requested agent is for a program, follow its *Ask which way first* before you create anything. An agent that people talk to, in the Web App, the CLI or a Remote-control bot, is not for a program and needs no question. Then:

• **SDK:** no Agent is created in this Project. Build the program with the penguin-sdk skill, and apply this skill to the program's embedded agent (see *The embedded agent of an SDK app*).
• **API:** create or configure the Agent here with the rest of this skill. Its API access and keys are the owner's to turn on, never yours; the penguin-sdk skill's *The API path* and its `reference/agent-api.md` have the rules and the steps to hand the user.

Resolve the inherited runtime

Treat the current Agent as the **Builder**. Resolve the runtime before creating a new Agent:

• `provider` and `model_id` are one complete pair. If the user explicitly supplies both, use that pair. If the user supplies neither, inherit the current Builder Session's `Provider` and `Model ID` from the Environment. Reject a half pair.
• `thinking_level` is independent. If the user explicitly supplies it, use that value. Otherwise read `model.thinking_level` from the Builder's own `agent_state/system_config.yaml`; when the field is absent, use the normal Agent-config default `medium`.

Write the resolved `thinking_level` into a brand-new target Agent's `model.thinking_level`, preserving all other copied `model` fields. Penguin does not persist `provider` or `model_id` in Agent State, so never add either field to `system_config.yaml`. When the same request continues into Benchmark design, carry the resolved model pair forward explicitly so evaluation uses the Builder runtime instead of a Project default. When configuring an existing Agent, change `model.thinking_level` only when the user explicitly requests that runtime change.

Locate the target agent

All agents of this project live side by side under `agents/` in the App Data Dir:

APP_DATA_DIR="<app_data_dir>"     # the App Data Dir value from your Environment section
ls "$APP_DATA_DIR/agents"         # existing agents (each is a folder here)
TARGET="$APP_DATA_DIR/agents/<agent_id>"   # the agent to configure

An agent directory contains `agent_state/` (`system_config.yaml`, `AGENTS.md`, `skills/`, `hooks/`, `memory/`, `tools/`) plus `scratchpad/` — and `traces/`, which appears once the agent has run at least once. `hooks/` exists once a hook package is installed; create it when you need it.

To extend the agent you are running as, the target is your own directory: `<app_data_dir>/agents/<agent_id>` with the Agent ID from your Environment section.

Write AGENTS.md

`agent_state/AGENTS.md` is injected into the agent's system prompt — it is where the user requirement becomes behavior. Keep `system_config.yaml`'s `system_prompt` untouched (that is the stable system layer); put everything requirement-specific in AGENTS.md:

• Role — what the agent is for, in one or two sentences.
• Domain guidance — the concrete rules, steps and constraints derived from the user requirement.

Be concise: AGENTS.md is prompt context, not documentation. For a domain expert that answers from a knowledge base, a good AGENTS.md is a few lines: the role sentence, "answer strictly from the provided context blocks", citation rules ("cite blocks inline as [1][2]"), a refusal rule for questions the context cannot answer, and "answer in the language of the question".

Skills

A Skill is a directory `agent_state/skills/<skill_name>/` containing a `SKILL.md`. The directory name is the Skill's name (letters, digits, `_`, `-`); nothing else registers it.

---
name: <skill_name>
description: <one line: what it does and when to use it>
version: <YYYY.MM.DD.N, e.g. 2026.09.29.1 - today's date, N counts that day's changes>
---

<skill_instructions>

The `description` line is what the target agent sees in its system prompt, so it has to say when the Skill applies; the body is read only once the agent decides to use it. Optional `short_description` and `short_description_zh` lines give the UI a short blurb. Files the body refers to go beside it (`reference/<topic>.md`, scripts), linked by relative path.

There are three ways to