loops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Loops — find, install, run & build recurring agents

Loops — 查找、安装、运行并构建周期性Agent

The full lifecycle for agentic loops — the

LOOP.md

format behind agenticloops.dev.

An agentic loop is an installable, recurring AI agent defined in one file: a trigger, a set of skills, and a prompt. One file defines it; any harness (Claude Code, Cursor, Codex, GitHub Actions, a 5dive runtime) can install and run it on a schedule.

This one skill covers the whole lifecycle — the loop-level analogue of

find-skills

and

skill-creator

in one:

Find an existing loop in the directory
Install / run it on your harness
Author a new
```
LOOP.md
```
when nothing fits

Always try 1–2 before 3. Search the directory and install an existing loop when one fits; only build a new one when nothing does. The authoritative format is spec v0.1 at github.com/5dive-ai/loops; when a field is ambiguous, defer to the spec.

The CLI for the whole flow is

npx agenticloops

(

find

install

run

list

update

). On a 5dive runtime, the native path is

5dive loop find|show|install

Agentic循环的完整生命周期——agenticloops.dev背后的

LOOP.md

格式。

Agentic循环是一个可安装、定时运行的AI Agent，由一个文件定义：触发器、一组技能和一个提示词。一个文件即可完成定义；任何harness（Claude Code、Cursor、Codex、GitHub Actions、5dive运行时）都可安装并定时运行它。

这一项技能涵盖了整个生命周期——相当于循环级别的

find-skills

和

skill-creator

二合一：

查找目录中的现有循环
安装/运行到你的harness中
编写新的
```
LOOP.md
```
（当没有合适的现有循环时）

始终优先执行步骤1-2，再考虑步骤3。搜索目录并安装合适的现有循环；只有在没有合适循环时才构建新循环。权威格式为github.com/5dive-ai/loops上的v0.1规范；当字段存在歧义时，以规范为准。

整个流程的CLI命令为

npx agenticloops

（包含

find

install

run

list

update

）。在5dive运行时上，原生命令为

5dive loop find|show|install

。

Part A — Find & install an existing loop

第一部分 — 查找并安装现有循环

Do this first whenever the user wants a recurring agent for a job.

当用户需要周期性Agent执行任务时，首先执行此步骤。

A1. Understand the job

A1. 明确任务

Identify the job (competitive intel, PR triage, security scan, news digest), the cadence (hourly, daily, on an event), and whether it's a single-agent job or a pipeline (gather → draft → publish = a multi-agent loop).

确定任务内容（竞品情报、PR分类、安全扫描、新闻摘要）、执行频率（每小时、每日、事件触发），以及它是单Agent任务还是流水线任务（收集→起草→发布 = 多Agent循环）。

A2. Search the directory

A2. 搜索目录

bash

npx agenticloops find <query>        # searches agenticloops.dev

Examples: "watch our competitors" →

find competitive intel

; "triage new PRs" →

find pr triage

; "daily security scan" →

find security

. Or browse agenticloops.dev directly (ci-analyst, intel-brief, autonomous-pr-loop, agentic-security-scanner, daily-news-radar, issue-triage-bot, …).

bash

npx agenticloops find <query>        # 搜索agenticloops.dev

示例：“监控我们的竞品” →

find competitive intel

；“分类新PR” →

find pr triage

；“每日安全扫描” →

find security

。或者直接浏览agenticloops.dev（包含ci-analyst、intel-brief、autonomous-pr-loop、agentic-security-scanner、daily-news-radar、issue-triage-bot等）。

A3. Vet before recommending

A3. 验证后再推荐

A loop runs unattended on a schedule, so vet it harder than a skill:

Proof, not popularity. The directory ranks on verifiable, signed run receipts, not stars — prefer a loop that emits receipts (proof it actually did the job).
Read the
requires
block — the trust surface: exactly which
```
cli
```
binaries,
```
secrets
```
(names),
```
mcp
```
servers, and
```
network
```
egress the loop touches, before it runs. Confirm the user is comfortable with all of it.
Source reputation — official
```
5dive-ai/loops
```
entries over an unknown author.
Can the harness honor the trigger? A loop needs scheduling — a run-only harness (an IDE) can run it once but can't fire it on time. Target a scheduler (5dive, GitHub Actions, cron); the installer warns otherwise.

循环会定时无人值守运行，因此要比验证技能更严格：

优先看验证记录，而非流行度。目录按可验证的签名运行记录排名，而非星标数——优先选择能生成运行记录（证明实际完成任务）的循环。
阅读
requires
块——信任范围：明确列出循环运行时会接触的
```
cli
```
二进制文件、
```
secrets
```
（名称）、
```
mcp
```
服务器和
```
network
```
出站请求，在运行前确认用户对所有内容都满意。
来源可信度——优先选择官方
```
5dive-ai/loops
```
条目，而非未知作者的内容。
**harness是否支持触发器？**循环需要调度功能——仅支持单次运行的harness（如IDE）可以运行一次，但无法定时触发。请选择支持调度的工具（5dive、GitHub Actions、cron）；安装程序会对此发出警告。

A4. Install (and test-run first)

A4. 安装（先进行测试运行）

bash

npx agenticloops install <owner/loop> --dry-run    # validate + pre-flight, change nothing
npx agenticloops run <owner/loop> --harness=<id>    # optional: one live run to see it work
npx agenticloops install <owner/loop> --yes         # register the recurring job

bash

npx agenticloops install <owner/loop> --dry-run    # 验证+预检查，不做任何更改
npx agenticloops run <owner/loop> --harness=<id>    # 可选：单次实时运行以查看效果
npx agenticloops install <owner/loop> --yes         # 注册周期性任务

native on a 5dive box:

在5dive主机上的原生命令：

5dive loop install <slug> --onto=<agent> [--cron="…"]


`--harness` auto-detects. Supply any `requires.secrets` host-side at install (the installer prompts) — secrets are names in the file, never values. Manage installed loops with `npx agenticloops list` and `npx agenticloops update [<slug>]`.

If nothing in the directory fits → go to Part B and author one.

---

5dive loop install <slug> --onto=<agent> [--cron="…"]


`--harness`会自动检测。安装时在主机端提供所有`requires.secrets`（安装程序会提示）——secrets仅为文件中的名称，绝不包含值。使用`npx agenticloops list`和`npx agenticloops update [<slug>]`管理已安装的循环。

如果目录中没有合适的循环 → 进入第二部分编写新循环。

---

Part B — Author a new loop

第二部分 — 编写新循环

B1. Capture intent

B1. 捕捉需求

A loop is a recurring job, so pin down four things (mine the conversation first):

The job — what one unit of work does this agent do each run? (one sentence; it becomes the prompt)

The trigger — a

schedule

(

every 4h

daily @ 07:00

weekdays @ 09:00

, or raw cron) or an

event

(

task-done

pr-opened

push

). One is required.

The skills — capabilities it leans on (e.g.
```
deep-research
```
,
```
compile-knowledge
```
). Optional but common.
The environment — any CLI binary, secret, MCP server, or network egress? These go in
```
requires
```
for install-time pre-flight.

If the job is a pipeline (gather → draft → publish), it's a multi-agent loop — see the

agents:

template below.

循环是周期性任务，因此需要明确四点（先从对话中提取）：

任务内容——Agent每次运行时完成的单个工作单元是什么？（一句话；将作为提示词）
触发器——
```
schedule
```
（
```
every 4h
```
、
```
daily @ 07:00
```
、
```
weekdays @ 09:00
```
或原始cron表达式）或
```
event
```
（
```
task-done
```
、
```
pr-opened
```
、
```
push
```
）。必须二选一。
技能——依赖的能力（如
```
deep-research
```
、
```
compile-knowledge
```
）。可选但常用。
环境要求——是否需要任何CLI二进制文件、密钥、MCP服务器或网络出站请求？这些将放在
```
requires
```
中供安装时预检查。

如果任务是流水线（收集→起草→发布），则属于多Agent循环——请参阅下面的

agents:

模板。

B2. Write the LOOP.md

B2. 编写LOOP.md

A loop is a directory whose name is the loop id, containing one

LOOP.md

. Frontmatter = manifest; body = starter prompt.

markdown

---
name: ci-analyst                 # kebab-case, ≤64 chars, matches the folder name
description: >                    # what it does + when to use it (drives discovery)
  Competitive-intel analyst — watches every competitor and the field, catches
  what changed, and writes a digest before it matters.
schedule: every 4h               # or: event: pr-opened  (one trigger is REQUIRED)
skills:                          # owner/repo/skill is explicit & recommended
  - 5dive-ai/skills/deep-research
  - 5dive-ai/skills/compile-knowledge
requires:                        # what must ALREADY be true in the env (declare-and-check)
  cli: [gh]                      #   binaries on PATH
  secrets: [X_API_TOKEN]         #   env-var NAMES only — never values
  mcp: [github]                  #   optional MCP servers
  network: [api.x.com]           #   optional egress allowlist
tier: frontier                   # capability hint: frontier | standard | fast (NEVER a vendor model)
effort: high                     # reasoning budget: high | medium | low
concurrency: skip                # overlap policy: skip | queue | replace | allow
timeout: 30m                     # per-run wall-clock cap (optional)
budget: 200k                     # per-run spend cap: tokens (200k) or cost ($2.00) (optional)
tags: [research, market-intel]
license: MIT
---

Scan our competitor set and the field for the last interval — launches, pricing,
funding, notable chatter. Update the watchlist and, once a day, write a concise
sourced briefing of what changed and what it means for us, then post it to the team.

Only

name

description

, and a trigger (

schedule

event

) are required. Start minimal; add fields as the job needs them.

Multi-agent (pipeline) template — an ordered

agents:

chain replaces the single body. Roles run strictly in array order; each role's structured output is injected at

{{previous_output}}

in the next:

markdown

---
name: intel-brief
description: Competitive-intel pipeline — a researcher gathers what changed, a writer turns it into a sourced briefing.
schedule: every 4h
tier: frontier
effort: high
agents:
  - role: researcher             # kebab id, unique in the loop
    skills: [deep-research, compile-knowledge]   # per-role, additive to top-level skills
    prompt: |
      Scan our competitor set and the field for the last interval. Return a
      structured list of what changed, with sources. No prose, just findings.
  - role: writer
    skills: [copywriting]
    prompt: |
      From the findings below, write a concise sourced briefing of what changed
      and what it means for us, then post it to the team.
      Findings:
      {{previous_output}}
tags: [research, multi-agent]
license: MIT
---

Triggers,

requires

tier

effort

concurrency

timeout

budget

, and

tags

stay top-level — they govern the whole run, not one role.

循环是一个目录，名称为循环ID，包含一个

LOOP.md

文件。前置元数据（Frontmatter）= 清单；正文=初始提示词。

markdown

---
name: ci-analyst                 # kebab-case格式，≤64字符，与文件夹名称匹配
description: >                    # 功能及适用场景（用于搜索发现）
  竞品情报分析师——监控所有竞品及行业动态，捕捉变化，并在产生影响前编写摘要。
schedule: every 4h               # 或：event: pr-opened （必须指定一个触发器）
skills:                          # 推荐明确指定owner/repo/skill
  - 5dive-ai/skills/deep-research
  - 5dive-ai/skills/compile-knowledge
requires:                        # 环境中必须已具备的条件（声明并检查）
  cli: [gh]                      #   PATH中的二进制文件
  secrets: [X_API_TOKEN]         #   仅为环境变量名称——绝不包含值
  mcp: [github]                  #   可选的MCP服务器
  network: [api.x.com]           #   可选的出站请求白名单
tier: frontier                   # 能力提示：frontier | standard | fast（绝不能指定厂商模型）
effort: high                     # 推理预算：high | medium | low
concurrency: skip                # 重叠策略：skip | queue | replace | allow
timeout: 30m                     # 每次运行的最长时间限制（可选）
budget: 200k                     # 每次运行的花费上限：token数（200k）或金额（$2.00）（可选）
tags: [research, market-intel]
license: MIT
---

扫描我们的竞品及行业在上一周期的动态——产品发布、定价、融资、重要讨论。更新监控列表，并且每天编写一份简洁的、带来源的简报，说明发生了什么变化以及对我们的影响，然后发布给团队。

仅

name

、

description

和触发器（

schedule

或

event

）是必填项。从最简版本开始；根据任务需求添加字段。

多Agent（流水线）模板——有序的

agents:

链替代单个正文。角色严格按数组顺序运行；每个角色的结构化输出会注入到下一个角色的

{{previous_output}}

中：

markdown

---
name: intel-brief
description: 竞品情报流水线——研究员收集变化信息，撰稿人将其转化为带来源的简报。
schedule: every 4h
tier: frontier
effort: high
agents:
  - role: researcher             # kebab格式ID，在循环中唯一
    skills: [deep-research, compile-knowledge]   # 每个角色的技能，会添加到顶层技能中
    prompt: |
      扫描我们的竞品及行业在上一周期的动态。返回结构化的变化列表，并附上来源。无需散文，仅需结果。
  - role: writer
    skills: [copywriting]
    prompt: |
      根据以下结果，编写一份简洁的、带来源的简报，说明发生了什么变化以及对我们的影响，然后发布给团队。
      结果：
      {{previous_output}}
tags: [research, multi-agent]
license: MIT
---

触发器、

requires

、

tier

、

effort

、

concurrency

、

timeout

、

budget

和

tags

保持在顶层——它们控制整个运行过程，而非单个角色。

B3. Validate

B3. 验证

There's no standalone

validate

command — validation is folded into

install

and

run

. Use a dry-run install to check the manifest against spec v0.1 and pre-flight

requires

without registering anything:

bash

npx agenticloops install ./ci-analyst --dry-run --no-telemetry

✓ <name>

line means the manifest parsed. Fix any schema errors; unknown fields are warnings, not errors. A missing secret/CLI shows up as a pre-flight

✗

— that's the check working, not a bad manifest.

没有独立的

validate

命令——验证已整合到

install

和

run

中。使用预安装试运行检查清单是否符合v0.1规范，并预检查

requires

，无需注册任何内容：

bash

npx agenticloops install ./ci-analyst --dry-run --no-telemetry

出现

✓ <name>

行表示清单解析成功。修复任何架构错误；未知字段会显示警告而非错误。缺少密钥/CLI会显示预检查

✗

——这是检查功能正常，而非清单错误。

B4. Test-run once, now

B4. 立即进行单次测试运行

bash

npx agenticloops run ./ci-analyst --harness=claude-code
npx agenticloops run ./ci-analyst --harness=claude-code --budget='$0.50'   # hard cap via `claude --max-budget-usd`

--harness

auto-detects. Iterate on the prompt/skills until the single run does the job.

bash

npx agenticloops run ./ci-analyst --harness=claude-code
npx agenticloops run ./ci-analyst --harness=claude-code --budget='$0.50'   # 通过`claude --max-budget-usd`设置硬性上限

--harness

会自动检测。迭代调整提示词/技能，直到单次运行能完成任务。

B5. Publish

B5. 发布

Publishing = pushing a conforming public repo, no curation step:

Put the
```
LOOP.md
```
in a public GitHub repo (the folder name is the loop id).
Add the GitHub topic
agenticloops
.
The crawler finds it, validates it, and indexes it. Others install with
```
npx agenticloops install <owner/repo>
```
.

Ranking is proof, not popularity — loops that emit verifiable signed run receipts outrank ones that just have stars.

发布即推送符合规范的公开仓库，无需审核步骤：

将
```
LOOP.md
```
放入公开GitHub仓库（文件夹名称为循环ID）。
添加GitHub主题
agenticloops
。
爬虫会发现它，进行验证并编入索引。其他人可使用
```
npx agenticloops install <owner/repo>
```
进行安装。

排名依据验证记录，而非流行度——能生成可验证签名运行记录的循环排名高于仅有点赞的循环。

Golden rules (the ones that trip people up)

黄金规则（容易出错的要点）

Model-agnostic:
tier
, never a vendor model. Write
```
tier: frontier | standard | fast
```
; the harness maps it to its own lineup. Naming
```
opus
```
/
```
gpt-5
```
in a
```
LOOP.md
```
breaks portability. A specific model is a host-side install override (
```
--model=opus
```
), never in the file.
Secrets are NAMES, never values.
```
secrets: [X_API_TOKEN]
```
declares that the loop needs a token; the value is supplied host-side at install and never enters the file or repo.
requires
is declare-and-check, not an installer. It lists what must already be true; the installer pre-flights and prompts for what's missing. Only
```
skills
```
are ever fetched.
A trigger is required.
```
schedule
```
or
```
event
```
. And it needs a scheduler — an IDE-only harness can run the agent but can't honor a recurring trigger.
Multi-agent handoff is structured, not chat. Each role passes a defined artifact to
```
{{previous_output}}
```
, never transcript scraping — that's what makes an unattended run deterministic anywhere.
Prefer explicit skill paths.
```
owner/repo/skill
```
is unambiguous; a bare name resolves against a default registry and can collide.

模型无关：使用
tier
，而非厂商模型。请写
```
tier: frontier | standard | fast
```
；harness会将其映射到自身的模型阵容。在
```
LOOP.md
```
中指定
```
opus
```
/
```
gpt-5
```
会破坏可移植性。特定模型是主机端的安装覆盖项（
```
--model=opus
```
），绝不能写入文件。
Secrets仅为名称，绝不包含值。
```
secrets: [X_API_TOKEN]
```
声明循环需要一个令牌；值在安装时由主机端提供，绝不会进入文件或仓库。
requires
是声明并检查，而非安装程序。它列出必须已具备的条件；安装程序会预检查并提示缺少的内容。只有
```
skills
```
会被获取。
必须指定触发器。
```
schedule
```
或
```
event
```
。并且需要调度器——仅支持IDE的harness可以运行Agent，但无法执行周期性触发器。
多Agent交接是结构化的，而非聊天式。每个角色将定义好的工件传递给
```
{{previous_output}}
```
，绝不会抓取对话记录——这是确保无人值守运行在任何环境下都能确定执行的关键。
优先使用明确的技能路径。
```
owner/repo/skill
```
没有歧义；仅使用名称会解析到默认注册表，可能会产生冲突。

Communicating with the user

与用户沟通

Loop users range from engineers to first-time terminal users. Match their level: explain "cron", "MCP", or "egress" briefly if there's any doubt, and lead with the plain-language job ("a bot that emails you a competitor digest every morning") before the YAML. Default to find-first — most people want a job done, not a file authored; reach for Part B only when the directory has nothing that fits.

循环用户涵盖工程师到首次使用终端的用户。匹配用户的技术水平：如果有疑问，简要解释“cron”、“MCP”或“egress”，先以通俗易懂的语言描述任务（“每天早上给你发竞品摘要的机器人”），再介绍配置内容。默认优先查找——大多数用户只想完成任务，而非编写文件；只有当目录中没有合适的循环时才使用第二部分。