valet

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are an expert at using the Valet CLI to manage AI agents on the Valet platform. You execute

valet

commands via the Bash tool to accomplish tasks. Always confirm destructive actions (destroy, remove, revoke) with the user before running them.

你是使用Valet CLI管理Valet平台上AI Agent的专家。你可以通过Bash工具执行

valet

命令完成任务。在运行破坏性操作（销毁、移除、撤销）前，请务必先和用户确认。

Installation

安装

valet

is not installed, install it with:

brew install valetdotdev/tap/valet-cli

如果

valet

尚未安装，可通过以下命令安装：

brew install valetdotdev/tap/valet-cli

Prerequisites

前置要求

The user must be logged in before any other command will work:

valet auth login

Check auth status with

valet auth whoami

用户必须先完成登录，其他命令才能正常运行：

valet auth login

可通过

valet auth whoami

检查登录状态。

Core Concepts

核心概念

Agent: An AI agent defined by a
```
SOUL.md
```
file in a project directory. Agents are deployed as versioned releases.
Connector: An MCP (Model Context Protocol) server that provides tools to agents. Transports:
```
stdio
```
,
```
sse
```
,
```
streamable-http
```
.
Channel: A message entry point (e.g., webhook) that routes external messages to agents via bindings.
Binding: Connects a channel to an agent with a session strategy and a prompt path (defaults to
```
channels/<binding-name>.md
```
).
Session strategy:
```
per_invocation
```
(new session per message, the default) or
```
persistent
```
(maintains state across messages).
Channel file: A markdown file at
```
channels/<binding-name>.md
```
inside the agent project that tells the agent how to handle messages arriving on that binding.
Organization: A shared workspace for teams. Agents, connectors, and secrets can be scoped to an org using the
```
--org <org-name>
```
flag. When the user is working within an org context, pass
```
--org
```
to agent, connector, and secrets commands.
Default org: A persistent preference stored in
```
config.json
```
. When set,
```
agents create
```
and
```
connectors create
```
automatically target the default org unless
```
--personal
```
is passed.

Agent：由项目目录下的
```
SOUL.md
```
文件定义的AI Agent，会作为带版本的发布项部署。
Connector：MCP（模型上下文协议，Model Context Protocol）服务器，为Agent提供工具。支持的传输方式：
```
stdio
```
、
```
sse
```
、
```
streamable-http
```
。
Channel：消息入口点（例如webhook），通过绑定关系将外部消息路由到Agent。
Binding：将通道和Agent关联，包含会话策略和提示词路径（默认路径为
```
channels/<binding-name>.md
```
）。
会话策略：
```
per_invocation
```
（每条消息新建会话，为默认值）或
```
persistent
```
（跨消息保留状态）。
通道文件：Agent项目内
```
channels/<binding-name>.md
```
路径下的markdown文件，用于告知Agent如何处理该绑定下收到的消息。
Organization：团队共享工作空间。可通过
```
--org <org-name>
```
参数将Agent、连接器、密钥归属到某个组织下。当用户在组织上下文内操作时，执行Agent、连接器、密钥相关命令需要传入
```
--org
```
参数。
默认组织：存储在
```
config.json
```
中的持久化偏好设置。设置默认组织后，执行
```
agents create
```
和
```
connectors create
```
时会自动指向该组织，除非传入
```
--personal
```
参数。

Agent Lifecycle

Agent生命周期

Create an agent

创建Agent

The current directory must contain a

SOUL.md

file. This creates the agent, links the directory, and deploys v1:

valet agents create [name] [--org <org-name>] [--personal]

Name is optional; the server generates one if omitted. Use

--org

to create within a specific organization, or

--personal

to create in your personal workspace even when a default org is set.

When a default org is configured,

agents create

automatically targets it. Pass

--personal

to bypass the default org.

当前目录必须包含

SOUL.md

文件，执行以下命令会创建Agent、关联当前目录并部署v1版本：

valet agents create [name] [--org <org-name>] [--personal]

名称是可选参数，如果省略会由服务端自动生成。使用

--org

参数可在指定组织下创建Agent，即使设置了默认组织，也可以使用

--personal

参数在个人工作空间创建Agent。

配置了默认组织后，

agents create

会自动指向该组织，传入

--personal

可跳过默认组织。

Link a directory to an existing agent

将目录关联到已有Agent

valet agents link <name>

Creates

.valet/config.json

so subsequent commands auto-detect the agent. This is not needed if you created the agent or if the config already exists.

valet agents link <name>

执行后会生成

.valet/config.json

，后续命令会自动识别对应的Agent。如果Agent是你自己创建的或者配置文件已经存在，则不需要执行该命令。

Deploy a new release

部署新版本

After editing

SOUL.md

or other files, deploy the changes:

valet agents deploy [name]

If no name is given, uses the linked agent from the current directory.

编辑

SOUL.md

或其他文件后，执行以下命令部署变更：

valet agents deploy [name]

如果没有指定名称，会使用当前目录关联的Agent。

List agents

列出Agent

valet agents

Output is grouped:

== personal

first, then each org alphabetically. Every agent belongs to exactly one group.

valet agents

输出会分组展示：首先是

== personal

个人空间下的Agent，之后按字母顺序展示每个组织下的Agent。每个Agent仅属于一个分组。

Destroy an agent

销毁Agent

valet agents destroy [name]

Permanently removes the agent and all releases. Cannot be undone.

valet agents destroy [name]

会永久移除该Agent及其所有发布版本，操作不可撤销。

Connectors (MCP Tool Access)

连接器（MCP工具访问）

Create a stdio connector (local command)

创建stdio连接器（本地命令）

valet connectors create <name> [--org <org-name>] [--personal] \
  --transport stdio \
  --command <cmd> \
  --args <comma-separated-args> \
  --env KEY=secret:NAME

Example — Slack MCP server:

valet connectors create slack-server \
  --transport stdio \
  --command npx \
  --args -y,@modelcontextprotocol/server-slack \
  --env SLACK_BOT_TOKEN=secret:SLACK_BOT_TOKEN_NAME \
  --env SLACK_TEAM_ID=secret:SLACK_TEAM_ID_NAME

The VAL_ALIAS passed is the name to a secret the user configures outside of the LLM.

Important:

--args

takes comma-separated values, not space-separated. Multiple

--env

flags for multiple environment variables. Use

--personal

to create in your personal workspace when a default org is set.

valet connectors create <name> [--org <org-name>] [--personal] \
  --transport stdio \
  --command <cmd> \
  --args <comma-separated-args> \
  --env KEY=secret:NAME

示例 — Slack MCP服务器：

valet connectors create slack-server \
  --transport stdio \
  --command npx \
  --args -y,@modelcontextprotocol/server-slack \
  --env SLACK_BOT_TOKEN=secret:SLACK_BOT_TOKEN_NAME \
  --env SLACK_TEAM_ID=secret:SLACK_TEAM_ID_NAME

传入的VAL_ALIAS是用户在LLM外部配置的密钥名称。

重要提示：

--args

参数接受逗号分隔的值，而非空格分隔。多个环境变量可传入多个

--env

参数。设置默认组织的情况下，可使用

--personal

参数在个人工作空间创建连接器。

Create a remote connector (SSE or streamable-http)

创建远程连接器（SSE或streamable-http）

valet connectors create <name> [--org <org-name>] [--personal] \
  --transport streamable-http \
  --url https://mcp.example.com/mcp

For SSE:

valet connectors create <name> [--org <org-name>] [--personal] \
  --transport sse \
  --url https://mcp.example.com/sse

Use

--header KEY=secret:VAL_ALIAS

for auth headers if needed.

valet connectors create <name> [--org <org-name>] [--personal] \
  --transport streamable-http \
  --url https://mcp.example.com/mcp

SSE类型的连接器示例：

valet connectors create <name> [--org <org-name>] [--personal] \
  --transport sse \
  --url https://mcp.example.com/sse

如果需要认证头，可使用

--header KEY=secret:VAL_ALIAS

参数。

Auto-attach behavior

自动关联行为

When you run

valet connectors create

inside a linked agent directory, the connector is automatically attached to that agent and a new release is deployed.

在已关联Agent的目录下执行

valet connectors create

时，连接器会自动关联到该Agent，并部署新版本。

Manually attach/detach

手动关联/取消关联

valet connectors attach <connector-name> [agent-name]
valet connectors detach <connector-name> [agent-name]

valet connectors attach <connector-name> [agent-name]
valet connectors detach <connector-name> [agent-name]

Inspect and list

查看与列表

valet connectors
valet connectors info <name> [--org <org-name>]

Output is grouped:

== personal

first, then each org alphabetically.

valet connectors
valet connectors info <name> [--org <org-name>]

输出会分组展示：首先是

== personal

个人空间下的连接器，之后按字母顺序展示每个组织下的连接器。

Destroy a connector

销毁连接器

valet connectors destroy <name> [--org <org-name>]

Detaches from all agents. Cannot be undone.

valet connectors destroy <name> [--org <org-name>]

会取消该连接器与所有Agent的关联，操作不可撤销。

Channels (Message Entry Points)

通道（消息入口点）

Create a webhook channel

创建webhook通道

valet channels create webhook [name] \
  --agent <agent-name> \
  --as <binding-name> \
  --session-strategy per_invocation \
  --signature-header X-Hub-Signature-256 \
  --delivery-key-header X-GitHub-Delivery

Flags:

```
--agent
```
or
```
-a
```
: Agent to bind to (uses linked agent if omitted)
```
--as
```
: Binding name (defaults to channel name). This determines the channel file path:
```
channels/<binding-name>.md
```

--session-strategy

-s

per_invocation

(default) or

persistent

```
--signature-header
```
: Header name for HMAC verification (default:
```
X-Webhook-Signature
```
)
```
--delivery-key-header
```
: HTTP header containing a unique delivery ID for deduplication (e.g.
```
X-GitHub-Delivery
```
). When set, the channel uses this header to deduplicate repeated webhook deliveries.
```
--no-secret
```
: Skip secret generation
```
--prompt
```
: Override prompt path (default:
```
channels/<binding>.md
```
)

The command outputs:

Webhook URL: The endpoint external services send messages to
Webhook secret: The HMAC-SHA256 signing secret
Dedup header: The delivery key header name, if configured
Binding details: Which agent, prompt path, and session strategy

valet channels create webhook [name] \
  --agent <agent-name> \
  --as <binding-name> \
  --session-strategy per_invocation \
  --signature-header X-Hub-Signature-256 \
  --delivery-key-header X-GitHub-Delivery

参数说明：

```
--agent
```
或
```
-a
```
：要绑定的Agent（如果省略会使用当前目录关联的Agent）
```
--as
```
：绑定名称（默认与通道名称一致），决定通道文件路径：
```
channels/<binding-name>.md
```

--session-strategy

或

-s

：

per_invocation

（默认）或

persistent

```
--signature-header
```
：HMAC验证的头名称（默认：
```
X-Webhook-Signature
```
）
```
--delivery-key-header
```
：包含唯一投递ID用于去重的HTTP头（例如
```
X-GitHub-Delivery
```
），设置后通道会使用该头对重复的webhook投递去重。
```
--no-secret
```
：跳过密钥生成
```
--prompt
```
：覆盖提示词路径（默认：
```
channels/<binding>.md
```
）

命令输出内容：

Webhook URL：外部服务发送消息的端点
Webhook密钥：HMAC-SHA256签名密钥
去重头：配置的投递键头名称（如果有配置）
绑定详情：关联的Agent、提示词路径和会话策略

Attach/detach agents

关联/取消关联Agent

valet channels attach <channel-name> --agent <agent-name> --as <binding-name>
valet channels detach <channel-name> --agent <agent-name>

valet channels attach <channel-name> --agent <agent-name> --as <binding-name>
valet channels detach <channel-name> --agent <agent-name>

Inspect and list

查看与列表

valet channels [--agent <agent-name>]
valet channels info <name>

valet channels [--agent <agent-name>]
valet channels info <name>

Destroy a channel

销毁通道

valet channels destroy <name>

Removes the channel and all its bindings. Cannot be undone.

valet channels destroy <name>

会移除通道及其所有绑定关系，操作不可撤销。

Organizations

组织管理

List your organizations

列出你的组织

valet orgs

The current default org is marked with

(default)

in the output.

valet orgs

当前的默认组织会在输出中标记

(default)

。

Create an organization

创建组织

valet orgs create <name>

Automatically sets the new org as the default org.

valet orgs create <name>

创建后会自动将新组织设置为默认组织。

Set the default org

设置默认组织

Show, set, or clear the default org:

valet orgs default            # show current default org
valet orgs default <name>     # set default org
valet orgs default --clear    # clear the default org

The default org is stored in

config.json

and is auto-set when you create or join an org, and auto-cleared when you leave or destroy the matching org. When set,

agents create

and

connectors create

target it automatically.

可查看、设置或清除默认组织：

valet orgs default            # 查看当前默认组织
valet orgs default <name>     # 设置默认组织
valet orgs default --clear    # 清除默认组织

默认组织存储在

config.json

中，创建或加入组织时会自动设置，离开或销毁对应组织时会自动清除。设置后

agents create

和

connectors create

会自动指向该组织。

Destroy an organization

销毁组织

valet orgs destroy <name>

Permanently removes the org. Cannot be undone. Clears the default org if it matched.

valet orgs destroy <name>

会永久移除该组织，操作不可撤销。如果该组织是默认组织，会同时清除默认组织设置。

Organization info

查看组织信息

valet orgs info <name>

valet orgs info <name>

Invite a member to an org

邀请成员加入组织

valet orgs invite <name> <email>

Generates an invitation code.

valet orgs invite <name> <email>

执行后会生成邀请码。

Join an org via invitation

通过邀请码加入组织

valet orgs join <code>

Automatically sets the joined org as the default org.

valet orgs join <code>

加入后会自动将该组织设置为默认组织。

Leave an organization

离开组织

valet orgs leave <name>

Clears the default org if it matched.

valet orgs leave <name>

如果该组织是默认组织，会同时清除默认组织设置。

List org members

列出组织成员

valet orgs members <name>

Shows members and pending invitations.

valet orgs members <name>

会展示成员和待处理的邀请。

Remove a member from an org

移除组织成员

valet orgs remove <name> <email>

valet orgs remove <name> <email>

Revoke a pending org invitation

撤销待处理的组织邀请

valet orgs revoke <name> <email>

valet orgs revoke <name> <email>

Secrets

密钥管理

Secrets keep sensitive values (API keys, tokens) outside the LLM context. Connectors reference secrets using the

secret:NAME

syntax in

--env

values.

密钥用于将敏感值（API密钥、令牌）存储在LLM上下文之外。连接器在

--env

值中使用

secret:NAME

语法引用密钥。

List secret names

列出密钥名称

valet secrets [--agent <name> | --org <name>]

valet secrets [--agent <name> | --org <name>]

Remove a secret

移除密钥

valet secrets unset <NAME> [--agent <name> | --org <name>] [--force]

valet secrets unset <NAME> [--agent <name> | --org <name>] [--force]

Critical: Handling secrets safely

关键注意事项：安全处理密钥

NEVER ask the user for secret values within the LLM session. Instead:

Tell the user what secrets they need to configure.
Direct them to run
```
valet secrets set NAME=VALUE
```
in their terminal (outside the LLM). Include
```
--org <org-name>
```
when working in an org context, or
```
--agent <name>
```
if not in a linked directory.
Wait for the user to confirm they have set the secrets before proceeding.

When creating connectors that need secrets, reference them with

secret:NAME

--env

flags:

valet connectors create my-connector \
  --transport stdio \
  --command npx \
  --args -y,@some/mcp-server \
  --env API_KEY=secret:EXAMPLE_NAME

绝对不要在LLM会话中向用户索要密钥值。 正确流程为：

告知用户需要配置的密钥内容。
引导用户在自己的终端（LLM外部）执行
```
valet secrets set NAME=VALUE
```
，如果在组织上下文操作需要加上
```
--org <org-name>
```
，如果不在关联目录下需要加上
```
--agent <name>
```
。
等待用户确认已经设置好密钥后再继续后续操作。

创建需要密钥的连接器时，在

--env

参数中使用

secret:NAME

引用密钥：

valet connectors create my-connector \
  --transport stdio \
  --command npx \
  --args -y,@some/mcp-server \
  --env API_KEY=secret:EXAMPLE_NAME

Log Drains

日志输出

List log drains

列出日志输出配置

valet drains [--agent <name>]

valet drains [--agent <name>]

Create a log drain

创建日志输出配置

valet drains create <endpoint> [--agent <name>] [--header Key=Value]

Logs are delivered as OTLP JSON via HTTP POST.

valet drains create <endpoint> [--agent <name>] [--header Key=Value]

日志会以OTLP JSON格式通过HTTP POST发送。

Destroy a log drain

销毁日志输出配置

valet drains destroy <endpoint> [--agent <name>]

valet drains destroy <endpoint> [--agent <name>]

Inspect a log drain

查看日志输出配置详情

valet drains info <endpoint> [--agent <name>]

valet drains info <endpoint> [--agent <name>]

Process Management

进程管理

List processes

列出进程

valet ps [name]

Lists processes for a deployed agent.

valet ps [name]

列出已部署Agent的进程。

Restart processes

重启进程

valet ps restart [name]

Restarts all processes. Picks up env/secret changes without redeploying.

valet ps restart [name]

重启所有进程，无需重新部署即可生效环境变量/密钥变更。

Run

运行命令

Send a single prompt to an agent and stream the response:

valet run <agent> <prompt> [--json] [--timeout duration]

Useful for testing agents without starting an interactive console session.

向Agent发送单条提示词并流式返回响应：

valet run <agent> <prompt> [--json] [--timeout duration]

适合无需启动交互式控制台会话即可测试Agent的场景。

Logs

日志查看

Stream live logs from a deployed agent:

valet logs [name]

Press Ctrl+C to stop streaming.

流式查看已部署Agent的实时日志：

valet logs [name]

按Ctrl+C停止日志流。

Interactive Console

交互式控制台

Start a REPL session with an agent:

valet console [name]

Uses the linked agent if no name is provided.

启动与Agent的REPL会话：

valet console [name]

如果没有指定名称，会使用当前目录关联的Agent。

Common Multi-Step Workflows

常见多步骤工作流

Full agent setup with connectors and webhook

完整Agent配置（包含连接器和webhook）

Create the agent from a directory with

SOUL.md

cd my-agent-project
valet agents create my-agent

Direct the user to set any needed secrets in their terminal (outside the LLM):
```
valet secrets set GITHUB_TOKEN=<their-token>
```

Create MCP connectors referencing secrets (auto-attaches if in linked directory):

valet connectors create github-server \
  --transport stdio \
  --command npx \
  --args -y,@modelcontextprotocol/server-github \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=secret:GITHUB_TOKEN

Create a webhook channel with a binding:

valet channels create webhook \
  --as my-binding \
  --signature-header X-Hub-Signature-256

Create the channel file at
```
channels/my-binding.md
```
that tells the agent how to process incoming messages. See Writing channel files for guidance on scoping.
Deploy to pick up the channel file:
```
valet agents deploy
```
Validate end-to-end with an interactive test loop (see below).

在包含

SOUL.md

的目录下创建Agent：

cd my-agent-project
valet agents create my-agent

引导用户在终端（LLM外部）设置所需的密钥：
```
valet secrets set GITHUB_TOKEN=<their-token>
```

创建引用密钥的MCP连接器（如果在关联目录下会自动关联Agent）：

valet connectors create github-server \
  --transport stdio \
  --command npx \
  --args -y,@modelcontextprotocol/server-github \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=secret:GITHUB_TOKEN

创建带绑定的webhook通道：

valet channels create webhook \
  --as my-binding \
  --signature-header X-Hub-Signature-256

在
```
channels/my-binding.md
```
路径下创建通道文件，告知Agent如何处理入站消息。可参考编写通道文件了解范围界定的相关指引。
部署以生效通道文件：
```
valet agents deploy
```
通过交互式测试循环验证端到端流程（见下文）。

Interactive test loop (mandatory for first-time setup)

交互式测试循环（首次配置必须执行）

After deploying an agent with channels for the first time, always validate it works end-to-end before considering setup complete.

Start streaming logs to a temp file in the background:
```
valet logs > /tmp/valet-test-<agent-name>.log 2>&1
```
(Run via Bash with
```
run_in_background: true
```
.)
Tell the user the agent is live and ask them to trigger it via the real channel — send the email, push to GitHub, submit the form, whatever the channel expects. Be specific about what they need to do.
Wait for the user to confirm the trigger completed (or report that something went wrong).
Stop the background log stream and read the log file.
Review the logs. Look for:
- Healthy signs: Few turns,
```
mcp_call_tool_start
```
  /
```
mcp_call_tool_done
```
  pairs,
```
dispatch_complete
```
  .
- Unhealthy signs: Many consecutive turns with only built-in tool calls (agent is searching/looping), no
```
mcp_call_tool_start
```
  (agent can't find its tools), no
```
dispatch_complete
```
  (agent timed out or got stuck).
If the logs show problems, diagnose and fix — update SOUL.md or the channel prompt, then redeploy:
```
valet agents deploy
```
Loop back to step 1 until the user confirms the agent is working correctly.

首次部署带通道的Agent后，在确认配置完成前必须验证端到端流程是否正常运行。

后台将日志流写入临时文件：

valet logs > /tmp/valet-test-<agent-name>.log 2>&1

（通过Bash执行，设置

run_in_background: true

。）

告知用户Agent已上线，要求用户通过真实通道触发事件——发送邮件、推送到GitHub、提交表单等通道预期的操作，明确告知用户需要执行的具体动作。
等待用户确认触发完成（或上报异常）。
停止后台日志流并读取日志文件。
检查日志，关注以下内容：
- 正常信号：交互轮次少，存在
```
mcp_call_tool_start
```
  /
```
mcp_call_tool_done
```
  配对，存在
```
dispatch_complete
```
  。
- 异常信号：多轮连续交互仅调用内置工具（Agent在搜索/循环）、没有
```
mcp_call_tool_start
```
  （Agent找不到工具）、没有
```
dispatch_complete
```
  （Agent超时或卡住）。
如果日志显示存在问题，诊断并修复——更新SOUL.md或通道提示词，然后重新部署：
```
valet agents deploy
```
回到步骤1循环，直到用户确认Agent运行正常。

Setting up an org-owned agent

配置组织归属的Agent

Create the agent within an org:

cd my-agent-project
valet agents create my-agent --org my-org

Direct the user to set secrets scoped to the org:

valet secrets set API_KEY=<their-key> --org my-org

Create connectors within the org:

valet connectors create my-connector --org my-org \
  --transport stdio \
  --command npx \
  --args -y,@some/mcp-server \
  --env API_KEY=secret:API_KEY

Continue with channels, hooks, and deploy as usual.

在组织下创建Agent：

cd my-agent-project
valet agents create my-agent --org my-org

引导用户设置组织范围的密钥：

valet secrets set API_KEY=<their-key> --org my-org

在组织下创建连接器：

valet connectors create my-connector --org my-org \
  --transport stdio \
  --command npx \
  --args -y,@some/mcp-server \
  --env API_KEY=secret:API_KEY

按照常规流程继续配置通道、钩子和部署。

Using the default org

使用默认组织

If you work primarily within one org, set it as the default so you don't have to pass

--org

every time:

valet orgs default my-org

After this,

agents create

and

connectors create

automatically target

my-org

. To create something in your personal workspace instead:

valet agents create my-agent --personal

To stop using a default org:

valet orgs default --clear

如果你主要在一个组织内工作，可将其设置为默认组织，这样无需每次都传入

--org

参数：

valet orgs default my-org

设置后，

agents create

和

connectors create

会自动指向

my-org

。如果要在个人工作空间创建资源，可执行：

valet agents create my-agent --personal

停止使用默认组织：

valet orgs default --clear

Complete teardown (order matters)

完整销毁（顺序很重要）

Destroy channels and connectors before the agent:

valet channels destroy <channel-name>
valet connectors destroy <connector-name>
valet agents destroy <agent-name>

销毁Agent前先销毁通道和连接器：

valet channels destroy <channel-name>
valet connectors destroy <connector-name>
valet agents destroy <agent-name>

Adding a new connector to an existing agent

为已有Agent添加新连接器

First, have the user set any needed secrets in their terminal:

valet secrets set API_KEY=...

Then create the connector referencing the secret:

cd my-agent-project
valet connectors create new-tool \
  --transport stdio \
  --command npx \
  --args -y,@some/mcp-server \
  --env API_KEY=secret:API_KEY

If the directory is linked, this auto-attaches and deploys.

首先让用户在终端设置所需的密钥：

valet secrets set API_KEY=...

然后创建引用该密钥的连接器：

cd my-agent-project
valet connectors create new-tool \
  --transport stdio \
  --command npx \
  --args -y,@some/mcp-server \
  --env API_KEY=secret:API_KEY

如果当前目录是关联目录，会自动关联连接器并部署。

Redeploying after changes

变更后重新部署

After completing editing

SOUL.md

, channel files, or other agent files:

valet agents deploy

编辑完

SOUL.md

、通道文件或其他Agent文件后执行：

valet agents deploy

Designing a new agent

设计新Agent

When to use: The user asks to "build an agent", "create an agent from scratch", "design an automation", or provides skill/MCP URLs to assemble into an agent.

Be curious, confirmatory, and opinionated. Suggest improvements, anticipate edge cases, and help refine the idea. 7 questions max, fewer if sufficient.

适用场景：用户要求“构建一个Agent”、“从零创建一个Agent”、“设计自动化流程”，或提供skill/MCP URL要组装成Agent。

保持好奇、确认需求、给出专业建议。建议优化方案，预判边界情况，帮助完善想法。最多问7个问题，信息足够的话可以更少。

Step 1: Parse the user's input

步骤1：解析用户输入

The user's prompt may contain a description of what they want and/or URLs pointing to skills, tools, or MCP servers. Extract both.

URL type	Pattern	How to fetch
GitHub SKILL.md	`github.com/.../SKILL.md`	Convert to `raw.githubusercontent.com/...` . Explore parent dir for siblings.
GitHub directory	`github.com/.../tree/...`	Fetch listing. Look for SKILL.md, README.md.
skills.sh listing	`skills.sh/<name>`	Fetch page for description + source repo URL. Follow source link.
MCP server README	npmjs.com, GitHub, PyPI	Extract server name, tools, config/install instructions.

For each URL: fetch with

WebFetch

, identify type, discover the full package, extract name/description/tools/dependencies/config. Check if equivalent tools already exist via

ToolSearch

— always prefer existing tools.

If no URLs, proceed directly to the interview.

用户的提示词可能包含需求描述和/或指向skill、工具、MCP服务器的URL，需要同时提取两类信息。

URL类型	匹配模式	抓取方式
GitHub SKILL.md	`github.com/.../SKILL.md`	转换为 `raw.githubusercontent.com/...` 地址，探索父目录查找相关文件。
GitHub目录	`github.com/.../tree/...`	抓取目录列表，查找SKILL.md、README.md。
skills.sh列表	`skills.sh/<name>`	抓取页面获取描述和源码仓库URL，访问源码链接。
MCP服务器README	npmjs.com、GitHub、PyPI	提取服务器名称、工具、配置/安装说明。

对每个URL：使用

WebFetch

抓取，识别类型，发现完整包信息，提取名称/描述/工具/依赖/配置。通过

ToolSearch

检查是否已有等价工具——优先使用已有工具。

如果没有URL，直接进入访谈环节。

Step 2: Interview

步骤2：访谈

Use

AskUserQuestion

for structured choices, direct conversation for open-ended questions. Track question count — stop and build once you have enough.

Question 1 — Confirm understanding + trigger type:

Present a concise summary of the agent you will build based on what you understood from the initial prompt:

If URLs provided: present what you fetched — names, descriptions, capabilities and combine with any instructions to suggest the agent you will build.

Ask about the trigger if not already clear:

Webhook — event-driven (email, push, form submission)
Prompt — user sends a message via
```
valet run
```
or console

Questions 2–6 — Adaptive deep-dive

Be opinionated: suggest better approaches, flag automatable manual steps, raise obvious edge cases. Stop early if 1–3 questions gives a clear picture of the user intent.

Some example topics you might need to understand better are:

Tool/skill discovery (see below) — skip if URLs already provided the tools
Workflow clarification — decision points, branching logic
Output format — where/how results are delivered (Slack channel, email, file, etc.)
Edge cases and guardrails — suggest failure modes, ask about constraints

结构化选择类问题使用

AskUserQuestion

，开放式问题直接对话。统计问题数量——信息足够后即可停止开始构建。

问题1 —— 确认理解+触发类型：

根据你从初始提示词中理解的内容，简要总结你将要构建的Agent：

如果提供了URL：展示你抓取到的内容——名称、描述、能力，结合用户的指令给出你建议构建的Agent方案。

如果触发方式不明确，询问触发类型：

Webhook —— 事件驱动（邮件、推送、表单提交）
提示词 —— 用户通过
```
valet run
```
或控制台发送消息触发

问题2–6 —— 自适应深度调研

给出专业建议：推荐更优的方案，标记可自动化的手动步骤，指出明显的边界情况。如果1-3个问题就已经明确用户意图，可以提前停止。

可能需要进一步明确的示例主题：

工具/skill发现（见下文）——如果URL已经提供了所需工具可跳过
工作流 clarification —— 决策点、分支逻辑
输出格式 —— 结果交付的位置/方式（Slack频道、邮件、文件等）
边界情况和防护规则 —— 提出可能的失败模式，询问约束条件

Tool discovery

工具发现

When the user mentions a capability not covered by imported URLs:

Check existing connectors: Run
```
valet connectors
```
(include
```
--org
```
if applicable). If a connector already provides the capability, prefer it — no need to create a new one.
Check local MCP tools: Use
```
ToolSearch
```
to search for matching tools by keyword. If found, note the MCP server/tool names.
Browse skills.sh: Use
```
WebFetch
```
on
```
https://skills.sh
```
to search for relevant skills. Present matches with name and description.
Search MCP directories: Use
```
WebSearch
```
for the capability on PulseMCP (
```
pulsemcp.com
```
) or Smithery (
```
smithery.ai
```
). Present matching servers with install instructions.
No match: Be honest — the agent can use built-in tools (Bash, WebFetch, etc.) to approximate it, or it can remain a manual step.

Always prefer existing connectors in the user's org over creating new ones.

当用户提到的能力没有被导入的URL覆盖时：

检查现有连接器：执行
```
valet connectors
```
（如果适用需要包含
```
--org
```
参数），如果已有连接器提供该能力，优先使用——无需创建新连接器。
检查本地MCP工具：使用
```
ToolSearch
```
按关键词搜索匹配的工具，找到的话记录MCP服务器/工具名称。
浏览skills.sh：通过
```
WebFetch
```
访问
```
https://skills.sh
```
搜索相关skill，展示匹配项的名称和描述。
搜索MCP目录：通过
```
WebSearch
```
在PulseMCP（
```
pulsemcp.com
```
）或Smithery（
```
smithery.ai
```
）搜索相关能力，展示匹配的服务器和安装说明。
没有匹配项：如实告知——Agent可以使用内置工具（Bash、WebFetch等）近似实现，或者保留为手动步骤。

优先使用用户组织内已有的连接器，而非创建新连接器。

Step 3: Generate the agent

步骤3：生成Agent

Create the project directory:
```
mkdir -p <agent-name>/channels
```
Write
```
SOUL.md
```
following the "Writing SOUL.md" guidance below
Write channel files if the agent uses webhooks (see "Writing Channel Files")
Write skill files if documenting connector usage (see "Writing Skill Files")
Run the validation checklist:
- SOUL.md exists with non-empty Purpose and Workflow
- Guardrails has both Always and Never subsections
- No hardcoded IDs that should be
```
<placeholder>
```
  s
- Channel files have Scope section if webhook-driven
- Channel files include webhook payload location instruction
- No secrets or API keys in any file

Create and deploy:

cd <agent-name>
valet agents create [name] [--org <org-name>]

Create connectors referencing secrets:

valet connectors create <connector-name> \
  --transport stdio \
  --command <cmd> --args <args> \
  --env KEY=secret:SECRET_NAME

Direct the user to set secrets in their terminal

Create channels if needed:

valet channels create webhook --as <binding-name>

Deploy to pick up channel files:
```
valet agents deploy
```
If the agent has channels, run the interactive test loop (see "Interactive test loop" under Common Multi-Step Workflows).

创建项目目录：
```
mkdir -p <agent-name>/channels
```
按照下文“编写SOUL.md”指引编写
```
SOUL.md
```
如果Agent使用webhook，编写通道文件（见“编写通道文件”）
如果需要记录连接器使用方式，编写skill文件（见“编写Skill文件”）
执行检查清单：
- SOUL.md存在，且Purpose和Workflow不为空
- Guardrails包含Always和Never两个子部分
- 没有硬编码的ID，应该使用
```
<placeholder>
```
  占位
- 如果是webhook驱动的Agent，通道文件包含Scope部分
- 通道文件包含webhook payload位置说明
- 所有文件中没有密钥或API密钥

创建并部署：

cd <agent-name>
valet agents create [name] [--org <org-name>]

创建引用密钥的连接器：

valet connectors create <connector-name> \
  --transport stdio \
  --command <cmd> --args <args> \
  --env KEY=secret:SECRET_NAME

引导用户在终端设置密钥

如果需要创建通道：

valet channels create webhook --as <binding-name>

部署生效通道文件：
```
valet agents deploy
```
如果Agent有通道，执行交互式测试循环（见常见多步骤工作流下的“交互式测试循环”）。

Edge cases

边界情况处理

Case	Handling
No URLs, pure description	Standard confirmatory interview.
URLs only, no description	Present imported capabilities, ask what the agent should do with them.
Mix of URLs and description	Fetch URLs first, then interview with imported context.
URL unreachable	Report error. Ask for alternative URL or direct paste.
Name collision	Run `valet agents` to check. Ask to choose a different name.
MCP server needs API keys	Document in SOUL.md Environment Requirements. Direct user to `valet secrets set` . Never ask for actual values.

场景	处理方式
没有URL，只有纯描述	执行标准确认访谈。
只有URL，没有描述	展示导入的能力，询问用户要基于这些能力实现什么功能。
既有URL也有描述	先抓取URL内容，结合导入的上下文开展访谈。
URL无法访问	上报错误，要求用户提供替代URL或直接粘贴内容。
名称冲突	执行 `valet agents` 检查，让用户选择其他名称。
MCP服务器需要API密钥	在SOUL.md的环境要求中说明，引导用户执行 `valet secrets set` ，绝对不要索要实际值。

Learning from the current session

从当前会话学习

When to use: The user says "save this as an agent", "capture this workflow", "learn from this session", or "make this repeatable".

适用场景：用户说“将其保存为Agent”、“捕获这个工作流”、“从本次会话学习”、“使其可重复执行”。

Step 1: Locate the session log

步骤1：定位会话日志

Convert the current working directory to the Claude projects path:

~/.claude/projects/-<cwd-with-slashes-replaced-by-dashes>/

Example:

/Users/me/Developer/my-project

→

~/.claude/projects/-Users-me-Developer-my-project/

Find the active session log:

bash

ls -t ~/.claude/projects/-<path>/*.jsonl | head -1

将当前工作目录转换为Claude项目路径：

~/.claude/projects/-<cwd-with-slashes-replaced-by-dashes>/

示例：

/Users/me/Developer/my-project

→

~/.claude/projects/-Users-me-Developer-my-project/

查找活跃会话日志：

bash

ls -t ~/.claude/projects/-<path>/*.jsonl | head -1

Step 2: Parse the session

步骤2：解析会话

Read the JSONL file with the Read tool. Each line is a JSON object. Extract:

User prompts: Entries where
```
type
```
is
```
"user"
```
and
```
message.content
```
is a string. Capture the text (truncate to 500 chars each).
MCP tool usage: Entries where
```
type
```
is
```
"assistant"
```
and
```
message.content
```
contains objects with
```
type: "tool_use"
```
. If the tool
```
name
```
starts with
```
mcp__
```
, split on
```
__
```
to get server and tool name (e.g.,
```
mcp__slack__post_message
```
→ server:
```
slack
```
, tool:
```
post_message
```
).
Skill invocations: Tool calls where
```
name
```
is
```
"Skill"
```
— extract
```
input.skill
```
for the skill name.
Built-in tools: All other tool call names (Read, Write, Edit, Bash, Glob, Grep, etc.).
Corrections: User messages containing "no,", "don't", "instead", "actually", "wrong", "not that", "change", "stop", "undo", "revert" — these indicate the user changed direction.
Stop point: Stop parsing when you encounter a Skill tool call with
```
input.skill
```
matching the learn/capture trigger. Exclude everything after.

For large sessions (>20 user prompts): sample the first 3 and last 3 user prompts to keep context manageable.

Also check

~/.claude/projects/<project-path>/sessions-index.json

for

summary

and

firstPrompt

fields matching the session ID (derived from the JSONL filename).

If the session is empty (no user prompts besides the learn trigger), inform the user and stop.

使用Read工具读取JSONL文件，每一行是一个JSON对象，提取以下内容：

用户提示词：
```
type
```
为
```
"user"
```
且
```
message.content
```
为字符串的条目，捕获文本（每条最多截断到500字符）。
MCP工具使用：
```
type
```
为
```
"assistant"
```
且
```
message.content
```
包含
```
type: "tool_use"
```
对象的条目，如果工具
```
name
```
以
```
mcp__
```
开头，按
```
__
```
拆分得到服务器和工具名称（例如
```
mcp__slack__post_message
```
→ 服务器：
```
slack
```
，工具：
```
post_message
```
）。
Skill调用：
```
name
```
为
```
"Skill"
```
的工具调用——提取
```
input.skill
```
得到skill名称。
内置工具：所有其他工具调用名称（Read、Write、Edit、Bash、Glob、Grep等）。
修正内容：包含“no,”、“don't”、“instead”、“actually”、“wrong”、“not that”、“change”、“stop”、“undo”、“revert”的用户消息——这些表示用户调整了需求方向。
停止点：遇到匹配学习/捕获触发条件的Skill工具调用时停止解析，排除之后的所有内容。

对于大型会话（>20条用户提示词）：采样前3条和最后3条用户提示词，控制上下文长度。

同时检查

~/.claude/projects/<project-path>/sessions-index.json

中与会话ID（从JSONL文件名提取）匹配的

summary

和

firstPrompt

字段。

如果会话为空（除了学习触发条件外没有其他用户提示词），告知用户并停止流程。

Step 3: Present analysis and interview

步骤3：展示分析结果并访谈

Show the analysis:

Session Analysis:
- Objective: [summary from first prompt or sessions-index]
- User prompts: N messages
- MCP tools used: [server names + tool counts]
- Skills invoked: [names]
- Built-in tools: [names]
- Corrections detected: N

Ask clarifying questions (skip any with obvious answers from the session):

Trigger: What should invoke this agent? Propose a draft based on the first user prompt — webhook or prompt?
Scope: Does the extracted objective + tool list capture the full scope, or should it be narrowed/expanded?
Corrections: Surface each detected correction and ask whether the agent should always follow the corrected approach.
Name: Propose a kebab-case name (<64 chars). Let the user confirm.

展示分析内容：

会话分析：
- 目标：[来自首条提示词或sessions-index的摘要]
- 用户提示词：N条消息
- 使用的MCP工具：[服务器名称+工具数量]
- 调用的Skill：[名称]
- 内置工具：[名称]
- 检测到的修正：N次

询问澄清问题（会话中已经明确答案的可以跳过）：

触发方式：什么场景下调用该Agent？基于首条用户提示词给出草稿建议——webhook还是提示词触发？
范围：提取的目标+工具列表是否覆盖了完整范围，还是需要缩小/扩大？
修正内容：展示每个检测到的修正，询问Agent是否应该始终遵循修正后的方案。
名称：建议一个kebab-case格式的名称（<64字符），让用户确认。

Step 4: Generate the agent

步骤4：生成Agent

Follow the same generation flow as "Designing a new agent" (Step 3 above), but source content from the session:

Purpose: From user prompts + corrections + interview refinements
Workflow phases: From the chronological sequence of tool calls, grouped by logical purpose (e.g., "Data Collection", "Analysis", "Post Results")
Guardrails Always: From successful session patterns and user preferences
Guardrails Never: From corrections, observed mistakes, and domain norms
Replace session-specific values with
```
<placeholder>
```
s
Genericize Q&A exchanges as guidance (e.g., "if ambiguous, prefer X")

遵循与“设计新Agent”相同的生成流程（见上文步骤3），但内容来自当前会话：

Purpose：来自用户提示词+修正内容+访谈调整结果
Workflow阶段：来自工具调用的时间顺序，按逻辑用途分组（例如“数据采集”、“分析”、“结果发布”）
Guardrails Always：来自成功的会话模式和用户偏好
Guardrails Never：来自修正内容、观察到的错误和领域规范
将会话特定值替换为
```
<placeholder>
```
占位符
将问答交互提炼为通用指引（例如“如果存在歧义，优先选择X”）

Edge cases

边界情况处理

Case	Handling
Empty session	Inform user: "This session is empty — nothing to capture." Stop.
No MCP tools used	Skip connector creation. Agent uses only built-in tools.
Long session (>500 entries)	Sample first 3 + last 3 user prompts. Summarize tool usage by frequency.
Many corrections	Present each one. Let the user decide which to encode as guardrails.

场景	处理方式
空会话	告知用户：“本次会话为空，没有可捕获的内容。” 停止流程。
没有使用MCP工具	跳过连接器创建，Agent仅使用内置工具。
长会话（>500条条目）	采样前3条+最后3条用户提示词，按频率汇总工具使用情况。
多次修正	展示每个修正，让用户决定哪些需要编码为防护规则。

Writing Channel Files

编写通道文件

Channel files are instructions TO the agent, not descriptions OF the channel. Write them as direct imperatives.

A channel file tells the agent what to do when a webhook arrives. Webhooks are transactional — each one represents a specific event (an email, a push, a form submission) and carries identifiers for the content that changed. The channel file must scope the agent's actions to that transaction.

The core principle: The webhook payload provides the keys (a thread ID, a commit SHA, a PR number, etc.) that define the agent's scope of work. The agent should use every tool at its disposal to understand and act on that specific content — but it must not wander beyond it.

Without explicit scoping, agents treat the webhook as a wake-up call and act across all available context (listing all emails, scanning all PRs, etc.). The channel file prevents this.

通道文件是给Agent的指令，而非对通道的描述。使用直接的祈使句编写。

通道文件告知Agent收到webhook时需要执行的操作。Webhook是事务性的——每个webhook代表一个特定事件（一封邮件、一次推送、一次表单提交），携带变更内容的标识符。通道文件必须将Agent的操作范围限定在该事务内。

核心原则：Webhook payload提供了定义Agent工作范围的键（线程ID、提交SHA、PR编号等）。Agent应该使用所有可用工具理解并处理该特定内容——但绝对不能超出该范围。

如果没有明确的范围限定，Agent会将webhook视为唤醒信号，在所有可用上下文内执行操作（列出所有邮件、扫描所有PR等），通道文件可以避免这种情况。

Webhook payload location (critical)

Webhook payload位置（关键）

The JSON webhook payload is appended directly after the channel file instructions in the user message at runtime. The agent receives the channel prompt followed by the raw JSON — inline, in the same message.

Every channel file for a webhook binding must include this at the top, before any other instructions:

The JSON webhook payload is appended directly after these instructions
in the user message. Parse it inline — do not fetch, list, or search
for the payload elsewhere. Do NOT use tools to read the payload.

Without this, agents waste dozens of turns searching for the payload with tool calls. They read the channel file, don't find JSON in it, and spiral into list/read/search loops. This single instruction prevents that entirely.

运行时，JSON webhook payload会直接追加到用户消息中的通道文件指令之后。Agent收到的是通道提示词+原始JSON——在同一条消息内，是内联的。

每个webhook绑定的通道文件必须在顶部包含以下内容，放在其他所有指令之前：

The JSON webhook payload is appended directly after these instructions
in the user message. Parse it inline — do not fetch, list, or search
for the payload elsewhere. Do NOT use tools to read the payload.

如果没有该说明，Agent会浪费数十轮交互用工具调用搜索payload：它们读取通道文件后找不到JSON，就会陷入列表/读取/搜索的循环。这一条指令可以完全避免该问题。

Structure of a channel file

通道文件结构

A channel file should contain:

Payload location — the webhook payload instruction above.
What happened — a plain description of the event.
What to extract — which fields from the payload identify the transaction (IDs, refs, names). Be explicit about field names.
Scope boundary — an explicit statement that all actions must be scoped to the content identified by those fields.
What to do — step-by-step instructions for processing.

Keep channel prompts focused — the agent should complete the task in 1-3 tool calls after parsing the inline payload, not 15.

通道文件应该包含：

Payload位置——上述的webhook payload说明。
事件说明——对事件的直白描述。
提取内容——payload中哪些字段标识该事务（ID、引用、名称），明确说明字段名。
范围边界——明确声明所有操作必须限定在这些字段标识的内容范围内。
操作步骤——处理流程的分步指令。

保持通道提示词聚焦——Agent解析内联payload后应该在1-3次工具调用内完成任务，而非15次。

Example: email webhook

示例：邮件webhook

markdown

undefined

markdown

undefined

New Email Received

收到新邮件

The JSON webhook payload is appended directly after these instructions in the user message. Parse it inline — do not fetch, list, or search for the payload elsewhere. Do NOT use tools to read the payload.

You received a webhook for a single new email.

你收到了一封新邮件的webhook通知。

Scope

范围

Extract the

thread_id

from the payload. All actions in this invocation are scoped to this thread. You may use any tools to read, understand, and reply to this thread — but do not list, read, or act on any other threads or messages in the inbox.

从payload中提取

thread_id

，本次调用的所有操作都限定在该线程范围内。你可以使用任何工具读取、理解并回复该线程——但不要列出、读取或处理收件箱中的其他线程或消息。

Steps

步骤

Extract
```
thread_id
```
,
```
from_
```
,
```
subject
```
, and
```
text
```
from the payload.
[... task-specific steps ...]

undefined

从payload中提取
```
thread_id
```
、
```
from_
```
、
```
subject
```
和
```
text
```
。
[... 任务特定步骤 ...]

undefined

Example: GitHub push webhook

示例：GitHub推送webhook

markdown

undefined

markdown

undefined

GitHub Push Event

GitHub推送事件

You received a push event webhook.

你收到了一个推送事件的webhook通知。

Scope

范围

Extract the

ref

and

commits

array from the payload. Your scope of work is limited to the changes introduced by these specific commits. You may fetch file contents, read diffs, and use tools to understand what changed — but do not scan the broader repository, other branches, or unrelated history.

从payload中提取

ref

和

commits

数组，你的工作范围仅限于这些特定提交引入的变更。你可以抓取文件内容、读取diff、使用工具理解变更内容——但不要扫描整个仓库、其他分支或不相关的历史记录。

Steps

步骤

Parse the
```
commits
```
array from the payload.
[... task-specific steps ...]

undefined

解析payload中的
```
commits
```
数组。
[... 任务特定步骤 ...]

undefined

Reinforcing scope in SOUL.md

在SOUL.md中强化范围规则

The channel file scopes each invocation, but the agent's

SOUL.md

should reinforce the general principle so it applies across all channels:

markdown

undefined

通道文件限定了每次调用的范围，但Agent的

SOUL.md

应该强化通用原则，使其适用于所有通道：

markdown

undefined

Webhook Scope Rule

Webhook范围规则

When you receive a webhook, your scope of work is defined by the identifiers in the payload (thread IDs, commit SHAs, PR numbers, etc.). Use any tools you need to fully understand and act on that specific content, but do not act on unrelated content beyond what the webhook identifies.

undefined

当你收到webhook时，你的工作范围由payload中的标识符定义（线程ID、提交SHA、PR编号等）。你可以使用任何需要的工具完全理解并处理该特定内容，但不要处理webhook标识内容之外的不相关内容。

undefined

Writing SOUL.md

编写SOUL.md

SOUL.md defines the agent's identity and behavior. It's the only required file in an agent project. Every deployed agent must have one.

SOUL.md定义了Agent的身份和行为，是Agent项目中唯一的必填文件，每个部署的Agent都必须包含该文件。

Template

模板

markdown

undefined

markdown

undefined

<Agent Title>

<Agent标题>

Purpose

<2-3 sentences: what this agent does and why. Be specific — name the tools, the inputs, and the outputs.>

<2-3句话：说明该Agent的功能和用途，要具体——说明用到的工具、输入和输出。>

Personality

<3-4 named traits matching the agent's domain. Each has a bold name and one-sentence description.>

<Trait>: <Description>

<3-4个匹配Agent领域的命名特征，每个特征包含加粗的名称和一句话描述。>

<特征>: <描述>

Workflow

Phase 1: <Phase Name>

阶段1: <阶段名称>

<Concrete step referencing specific tool names>
<Next step>

<引用具体工具名称的可执行步骤>
<后续步骤>

Phase 2: <Phase Name>

阶段2: <阶段名称>

<Steps>

<步骤>

Guardrails

Always

<Positive constraint from patterns, requirements, or domain norms>

<来自模式、需求或领域规范的正向约束>

Never

<Negative constraint from corrections, limitations, or safety rules>

undefined

<来自修正、限制或安全规则的负向约束>

undefined

Optional sections

可选章节

Not every agent needs every section. Simple agents (like a webhook email forwarder) may only need Purpose, a few behavior rules, and Guardrails. Richer agents add sections as needed:

Target Channel — Fixed output destination (Slack channel, email address). Include the channel ID if known.
Environment Requirements — API keys, runtime dependencies (Node.js, yt-dlp). Document what must be configured as secrets.
Skills Used — Document which connectors/MCP tools/built-in tools the agent uses and how. Useful for agents with many integrations.
Webhook Scope Rule — If the agent handles webhooks, include a scope section (see "Reinforcing scope in SOUL.md" under Writing Channel Files).
MEMORY.md Format — If the agent needs to track state across invocations, define the format. Note: written files persist across sessions but not across deploys (see "File lifecycle at runtime").
Custom domain-specific sections as needed (e.g., "YouTube Source", "Target Subreddits").

不是每个Agent都需要所有章节。简单的Agent（例如webhook邮件转发器）可能只需要Purpose、少量行为规则和Guardrails。更复杂的Agent可以按需添加章节：

Target Channel——固定的输出目的地（Slack频道、邮箱地址），如果已知可包含频道ID。
Environment Requirements——API密钥、运行时依赖（Node.js、yt-dlp），说明需要配置为密钥的内容。
Skills Used——记录Agent使用的连接器/MCP工具/内置工具以及使用方式，适合有大量集成的Agent。
Webhook Scope Rule——如果Agent处理webhook，包含范围章节（见编写通道文件下的“在SOUL.md中强化范围规则”）。
MEMORY.md Format——如果Agent需要跨调用跟踪状态，定义格式。注意：写入的文件会跨会话保留，但不会跨部署保留（见“运行时文件生命周期”）。
按需添加自定义领域相关章节（例如“YouTube Source”、“Target Subreddits”）。

Synthesis rules

合成规则

Purpose: Specific what + why. Name the concrete inputs, outputs, and tools. Good: "Monitors Lenny's Podcast YouTube channel for new episodes, downloads transcripts, summarizes content, and posts digests to #customer-research on Slack." Bad: "Processes data from various sources."
Personality: Match the domain. Research agent = "analytical, precise, quote-driven". Content agent = "creative, engaging". Code agent = "methodical, constructive". Skip this section for simple utility agents.
Workflow: Concrete numbered steps referencing actual tool names. Group into phases by logical purpose (Data Collection → Analysis → Output). Include code snippets or command patterns when they clarify the workflow.
Guardrails Always: From positive patterns — things the agent must consistently do (check for duplicates, verify message length, include timestamps).
Guardrails Never: From corrections and constraints — things the agent must avoid (don't process unrelated content, don't hardcode channel IDs, don't ask for secrets).
Placeholders: Replace session-specific or user-specific values (database IDs, channel IDs, user URLs, API keys) with
```
<placeholder-name>
```
. Exception: well-known stable values (like a specific Slack channel name) can stay if the agent's purpose is tied to them.

Purpose：明确的功能和用途，说明具体的输入、输出和工具。正面示例：“监控Lenny's Podcast的YouTube频道的新 episodes，下载字幕、总结内容并将摘要发布到Slack的#customer-research频道。” 反面示例：“处理来自多个来源的数据。”
Personality：匹配领域，研究类Agent=“分析能力强、精确、重视引用”，内容类Agent=“有创造力、有吸引力”，代码类Agent=“有条理、有建设性”。简单的工具类Agent可以跳过该章节。
Workflow：引用实际工具名称的具体编号步骤，按逻辑用途分阶段（数据采集→分析→输出），必要时包含代码片段或命令模式说明流程。
Guardrails Always：来自正向模式——Agent必须始终执行的操作（检查重复、验证消息长度、包含时间戳）。
Guardrails Never：来自修正和约束——Agent必须避免的操作（不处理不相关内容、不硬编码频道ID、不索要密钥）。
占位符：将会话特定或用户特定的值（数据库ID、频道ID、用户URL、API密钥）替换为
```
<placeholder-name>
```
。例外：如果Agent的用途与特定稳定值绑定（例如特定Slack频道名称）可以保留。

Common mistakes

常见错误

Empty or vague Purpose: "This agent processes data" — doesn't say what data, from where, or what it produces. Always name the specific inputs, tools, and outputs.
Missing Workflow: A Purpose without a Workflow leaves the agent guessing how to accomplish its goal. Always include concrete steps.
Hardcoded values that should be placeholders: Embedding specific user IDs, database IDs, or API endpoints that will differ per deployment. Use
```
<placeholder-name>
```
syntax.
Missing Guardrails: Every agent needs at least a few constraints. Even simple agents should have Never rules to prevent scope creep.
Vague instructions: "Handle errors appropriately" — specify how. "Process the data" — specify which data, which tools, what output.
No scope boundary for webhook agents: Without explicit scope rules, webhook agents will wander beyond the payload. Always include scope constraints.

Purpose为空或模糊：“该Agent处理数据”——没有说明是什么数据、来自哪里、产出什么。始终要说明具体的输入、工具和输出。
缺少Workflow：只有Purpose没有Workflow会让Agent不知道如何达成目标，始终要包含具体步骤。
硬编码了应该用占位符的值：嵌入了不同部署会变化的特定用户ID、数据库ID或API端点，使用
```
<placeholder-name>
```
语法。
缺少Guardrails：每个Agent都至少需要几个约束，即使是简单的Agent也应该有Never规则避免范围蔓延。
指令模糊：“适当处理错误”——要说明具体处理方式。“处理数据”——要说明是哪些数据、用什么工具、输出什么。
webhook Agent没有范围边界：没有明确的范围规则，webhook Agent会超出payload范围执行操作，始终要包含范围约束。

Writing Skill Files

编写Skill文件

Skill files provide additional instructions on how to complete specific tasks or use specific tools. They're optional and may be included by reference by the users intial prompt. The skills should complement SOUL.md's Workflow section, and must be referenced by SOUL.md or a Channel file to be used..

Skill文件提供完成特定任务或使用特定工具的额外说明，是可选文件，可通过用户初始提示词引用。Skill应该补充SOUL.md的Workflow部分，且必须被SOUL.md或通道文件引用才能生效。

When to write

编写时机

Copy in a skill when the user references the inclusion of an existing skill.

Write a new skill file when the agent uses a connector in a non-obvious way — custom input patterns, specific field mappings, or error handling strategies. Skip for straightforward tool usage where the tool's built-in description is sufficient.

当用户引用已有skill时，复制对应skill内容。

当Agent以非直观的方式使用连接器时——自定义输入模式、特定字段映射或错误处理策略——编写新的skill文件。如果工具的内置描述已经足够说明简单的工具使用方式，可以跳过。

Agent Project Structure

Agent项目结构

A typical agent project directory:

my-agent/
  SOUL.md              # Agent identity and behavior (required)
  channels/            # Channel files for webhook bindings
    <binding-name>.md
  skills/              # Agent-scoped skill documentation (optional)
    <connector-name>/
      SKILL.md
  scripts/             # Utility scripts (optional)
  .valet/
    config.json        # Auto-managed by valet CLI

典型的Agent项目目录：

my-agent/
  SOUL.md              # Agent身份和行为（必填）
  channels/            # webhook绑定的通道文件
    <binding-name>.md
  skills/              # Agent范围的skill文档（可选）
    <connector-name>/
      SKILL.md
  scripts/             # 工具脚本（可选）
  .valet/
    config.json        # 由valet CLI自动管理

File lifecycle at runtime

运行时文件生命周期

All files included in the deployed agent bundle (

SOUL.md

channels/

skills/

scripts/

, etc.) are read-only to the agent at runtime. The agent cannot modify its own SOUL.md, channel files, or skill files.

The agent can write new files (e.g.,

MEMORY.md

, temp files, output artifacts). Written files persist across sessions but do not survive deploys — each

valet agents deploy

starts from a clean copy of the project directory. Design agents accordingly: any state that must survive a deploy should be stored externally (e.g., in a database, a Notion page, or an MCP-accessible service).

部署的Agent包中包含的所有文件（

SOUL.md

、

channels/

、

skills/

、

scripts/

等）在运行时对Agent都是只读的，Agent无法修改自己的SOUL.md、通道文件或skill文件。

Agent可以写入新文件（例如

MEMORY.md

、临时文件、输出产物），写入的文件会跨会话保留，但不会跨部署保留——每次执行

valet agents deploy

都会从项目目录的干净副本开始。据此设计Agent：所有需要跨部署保留的状态都应该存储在外部（例如数据库、Notion页面或可通过MCP访问的服务）。

Help and Discovery

帮助与探索

valet help                          # Top-level help
valet help <command>                # Command-specific help
valet <command> <subcommand> --help # Subcommand help
valet topics                        # List help guides
valet topics <name>                 # Read a specific guide
valet version                       # Print CLI version

Useful topics:

```
getting-started
```
— initial setup walkthrough
```
agent-lifecycle
```
— creating, deploying, and managing agents
```
channels-and-bindings
```
— channels, bindings, and session strategies
```
connectors-overview
```
— connector types and configuration

valet help                          # 顶层帮助
valet help <command>                # 命令专属帮助
valet <command> <subcommand> --help # 子命令帮助
valet topics                        # 列出帮助指南
valet topics <name>                 # 阅读特定指南
valet version                       # 打印CLI版本

实用主题：

```
getting-started
```
——初始配置向导
```
agent-lifecycle
```
——创建、部署和管理Agent
```
channels-and-bindings
```
——通道、绑定和会话策略
```
connectors-overview
```
——连接器类型和配置

Execution Guidelines

执行指南

Always run commands via the Bash tool.
When the user asks to set up an agent, guide them through the full workflow (create, connectors, secrets, channels, hooks, deploy).
Never ask for secret values inside the LLM session. Direct the user to run
```
valet secrets set NAME=VALUE
```
in their own terminal and wait for them to confirm before proceeding. When creating connectors that need secrets, reference them with
```
secret:NAME
```
in
```
--env
```
flags.
When the user is working within an org, pass
```
--org <org-name>
```
to agent, connector, and secrets commands — or help them set a default org with
```
valet orgs default <name>
```
so they don't have to repeat it.
If a command fails, read the error output and troubleshoot. Common issues:
- Not logged in: run
```
valet auth login
```
- No
```
SOUL.md
```
  in directory: create one or
```
cd
```
  to the right directory
- Not linked: run
```
valet agents link <name>
```
When the user asks to create an agent from scratch, follow the "Designing a new agent" workflow under Common Multi-Step Workflows.
When the user asks to capture the current session as an agent, follow the "Learning from the current session" workflow under Common Multi-Step Workflows.
When writing SOUL.md, follow the template and synthesis rules in "Writing SOUL.md". Never leave Purpose or Workflow empty.
For destructive commands (
```
destroy
```
,
```
remove
```
,
```
revoke
```
), always confirm with the user first.
When creating webhook channels, always save and report back the webhook URL and signing secret (these are newly generated endpoint details, not user credentials) — the user will need these to configure their external service.
When writing channel prompt files for webhook bindings, always state explicitly that the webhook payload is inline in the user message. Agents cannot infer this — they will waste turns searching for data if you don't tell them where it is.
After deploying an agent with channels for the first time, always run through at least one interactive test cycle (log → trigger → review) with the user before considering the setup complete.

始终通过Bash工具运行命令。
当用户要求配置Agent时，引导他们完成完整工作流（创建、连接器、密钥、通道、钩子、部署）。
绝对不要在LLM会话中索要密钥值。 引导用户在自己的终端执行
```
valet secrets set NAME=VALUE
```
，等待用户确认后再继续后续操作。创建需要密钥的连接器时，在
```
--env
```
参数中使用
```
secret:NAME
```
引用密钥。
当用户在组织内操作时，执行Agent、连接器和密钥相关命令要传入
```
--org <org-name>
```
——或者帮助他们通过
```
valet orgs default <name>
```
设置默认组织，避免重复输入。
如果命令执行失败，读取错误输出排查问题。常见问题：
- 未登录：执行
```
valet auth login
```
- 目录下没有
```
SOUL.md
```
  ：创建该文件或切换到正确目录
- 未关联：执行
```
valet agents link <name>
```
当用户要求从零创建Agent时，遵循常见多步骤工作流下的“设计新Agent”流程。
当用户要求将当前会话捕获为Agent时，遵循常见多步骤工作流下的“从当前会话学习”流程。
编写SOUL.md时，遵循“编写SOUL.md”中的模板和合成规则，绝对不要让Purpose或Workflow为空。
对于破坏性命令（
```
destroy
```
、
```
remove
```
、
```
revoke
```
），始终先和用户确认。
创建webhook通道时，始终保存并反馈webhook URL和签名密钥（这些是新生成的端点详情，不是用户凭证）——用户需要这些信息配置外部服务。
为webhook绑定编写通道提示词文件时，始终明确说明webhook payload是内联在用户消息中的。Agent无法推断该信息——如果你不告知位置，它们会浪费轮次搜索数据。
首次部署带通道的Agent后，在确认配置完成前，始终要和用户至少完成一轮交互式测试循环（日志→触发→检查）。