build-iterated-agentic-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build Iterated Agentic Loop

构建迭代式Agent循环

Use this skill when the user wants to turn a repeatable agent task into a repo-local skill plus a GitHub Actions workflow that runs a coding agent on a schedule, manually, or both.

The target shape is an iterated agentic loop: a focused skill defines the agent's judgement, a workflow invokes a coding agent with a repo-specific prompt, an agent-memory file carries standing feedback between runs, and each workflow labels its PRs so only one open PR exists per loop. The

narrow-react-prop-types

skill is the concrete reference pattern.

当用户希望将可重复的Agent任务转换为仓库本地Skill，以及一个可按计划、手动或两种方式运行编码Agent的GitHub Actions工作流时，可使用此Skill。

目标形态是一个迭代式Agent循环：一个聚焦的Skill定义Agent的判断逻辑，一个工作流调用带有仓库专属提示词的编码Agent，一个Agent内存文件在多次运行间传递持续反馈，且每个工作流会为其PR添加标签，确保每个循环仅存在一个开放PR。

narrow-react-prop-types

Skill是具体的参考模式。

Outputs

输出内容

Create or update these files in the target repo:

```
.claude/skills/<skill-name>/SKILL.md
```
for the repo-local agent behavior.
```
.github/workflows/agent-<task-name>.yml
```
for the recurring coding-agent automation.
```
.github/agent-memory/<task-name>.md
```
for stable feedback and scope constraints.
Optional references under
```
.claude/skills/<skill-name>/references/
```
when the skill needs templates, examples, or long supporting material.

在目标仓库中创建或更新以下文件：

```
.claude/skills/<skill-name>/SKILL.md
```
：用于定义仓库本地Agent行为。
```
.github/workflows/agent-<task-name>.yml
```
：用于实现周期性编码Agent自动化。
```
.github/agent-memory/<task-name>.md
```
：用于存储稳定反馈和范围约束。
可选参考文件：当Skill需要模板、示例或长篇支持材料时，可放在
```
.claude/skills/<skill-name>/references/
```
目录下。

Workflow

工作流程

1. Explore the target repo

1. 探索目标仓库

Read before asking setup questions:

Existing
```
.github/workflows/*.yml
```
and
```
.github/actions/**
```
to understand runner, checkout, dependency install, cache, and PR patterns.

Package manager files such as

package.json

bun.lock

pnpm-lock.yaml

yarn.lock

package-lock.json

pyproject.toml

go.mod

, or

Cargo.toml

, or other package management-related files

Existing validation scripts, especially typecheck, lint, test, quality, format, and package-scoped commands.
Existing
```
.claude/skills
```
and
```
.agents/skills
```
to avoid duplicating conventions.

Completion criterion: you can name the repo's package manager, install command, likely validation commands, and existing workflow conventions.

在询问设置问题前，先阅读以下内容：

现有
```
.github/workflows/*.yml
```
和
```
.github/actions/**
```
文件，了解运行器、代码检出、依赖安装、缓存及PR模式。

包管理器文件，如

package.json

、

bun.lock

、

pnpm-lock.yaml

、

yarn.lock

、

package-lock.json

、

pyproject.toml

、

go.mod

或

Cargo.toml

，或其他包管理相关文件

现有验证脚本，尤其是类型检查、 lint、测试、质量、格式化及包范围命令。
现有
```
.claude/skills
```
和
```
.agents/skills
```
目录，避免重复已有约定。

完成标准：能够说出仓库的包管理器、安装命令、可能的验证命令及现有工作流约定。

2. Ask setup questions

2. 询问设置问题

Walk the user through these decisions. Recommend defaults from repo evidence instead of presenting a blank form.

Coding Agent: Claude Code, Codex, OpenCode, or CodeLayer. Explain the required secret and headless command for the recommended choice. Use
```
references/agent-runner-templates.md
```
. CodeLayer is Humanlayer's ultra-lightweight agent harness.
Cadence: daily, weekly, weekdays, monthly, manual-only, or custom cron. Recommend a cadence based on task risk and review burden - most likely weekdays, daily, or weekly.
Task: What task should the agent loop accomplish?

Are there existing skills for doing this? (you can do research before asking the user this)
Ask the user if you should look at recent PRs, git history, or other particular parts of the codebase for reference.

Scope: which directories/packages the loop may change and which it may only inspect
Validation: which commands must pass before the agent commits (You should propose this to the user based on your earlier research and ask them to confirm)
PR bounding: Ask if scheduled runs should no-op when open PRs from this agent already exist, and if so, how many open PRs to allow before blocking new runs.

Recommended: Yes, bound to 1 open PR per agent loop. This prevents the agent from creating unbounded work that piles up faster than humans can review. Without bounding, a daily agent could generate 5+ unreviewed PRs in a week, creating review fatigue and merge conflicts.
The workflow uses a label (e.g.,
```
agent-<task-slug>
```
) to identify PRs from each agent loop. Scheduled runs check
```
gh pr list --label <label> --state open
```
and skip if the count meets or exceeds the bound.
Manual
```
workflow_dispatch
```
runs bypass the bound check, allowing forced runs when needed.

PR metadata: label name, PR title prefix, and branch prefix.

Suggest

[MM/DD][Agent: <Agent Name>]: <Concise Description>

as a template, e.g.

[6/23][Agent: Effect Migrator]: Migrate XYZ module

Response format: How should the CI agent format its final response (which becomes the PR body)?

Show the user
```
references/response-template.md
```
for examples (fix/migration, generation, refactor).
Ask what information reviewers need: summary stats, risk levels, verification steps, file lists, etc.
Create a customized response template that the generated skill will reference in its
```
references/
```
directory

Iteration behavior: whether
```
/iterate
```
comments should update the existing PR.

If enabled, install
```
references/agent-iteration.ts
```
to the repo. Ask the user's preferred location:
```
.github/scripts/
```
,
```
ci-scripts/
```
, or
```
scripts/
```
.
The script has two modes:
```
footer
```
(adds the PR body marker) and
```
prompt
```
(builds the iteration prompt from PR context).
If disabled, remove the
```
issue_comment
```
trigger and iteration-only steps from the workflow.

Completion criterion: every placeholder in the workflow, prompt, and memory template has a chosen value or an explicit default.

引导用户完成以下决策。根据仓库现有情况推荐默认值，而非提供空白选项。

编码Agent：Claude Code、Codex、OpenCode或CodeLayer。说明推荐选项所需的密钥和无界面命令。参考
```
references/agent-runner-templates.md
```
。CodeLayer是Humanlayer的超轻量级Agent工具。
运行频率：每日、每周、工作日、每月、仅手动或自定义 cron 表达式。根据任务风险和审核负担推荐频率——最可能是工作日、每日或每周。
任务内容：Agent循环应完成什么任务？

是否已有用于完成此任务的Skill？（你可以先进行研究再询问用户）
询问用户是否需要查看近期PR、git历史或代码库的其他特定部分作为参考。

范围：循环可修改的目录/包，以及仅可查看的目录/包
验证要求：Agent提交前必须通过哪些命令（你应基于之前的研究向用户提出建议并请求确认）
PR限制：询问当此Agent的开放PR已存在时，计划运行是否应无操作，若应限制，允许存在多少个开放PR后阻止新运行。

推荐：是，每个Agent循环限制1个开放PR。 这可防止Agent创建大量无法及时审核的工作，避免审核疲劳和合并冲突。若无限制，每日运行的Agent一周内可能生成5个以上未审核PR。
工作流使用标签（如
```
agent-<task-slug>
```
）识别每个Agent循环的PR。计划运行会检查
```
gh pr list --label <label> --state open
```
，若数量达到或超过限制则跳过。
手动
```
workflow_dispatch
```
运行会绕过限制检查，允许在需要时强制运行。

PR元数据：标签名称、PR标题前缀和分支前缀。

建议使用

[MM/DD][Agent: <Agent Name>]: <简要描述>

作为模板，例如

[6/23][Agent: Effect Migrator]: 迁移XYZ模块

响应格式：CI Agent应如何格式化最终响应（即PR正文）？

向用户展示
```
references/response-template.md
```
中的示例（修复/迁移、生成、重构）。
询问审核人员需要哪些信息：统计摘要、风险等级、验证步骤、文件列表等。
创建定制化响应模板，生成的Skill会在其
```
references/
```
目录中引用该模板

迭代行为：
```
/iterate
```
评论是否应更新现有PR。

若启用，将
```
references/agent-iteration.ts
```
安装到仓库。询问用户偏好的位置：
```
.github/scripts/
```
、
```
ci-scripts/
```
或
```
scripts/
```
。
该脚本有两种模式：
```
footer
```
（添加PR正文标记）和
```
prompt
```
（从PR上下文构建迭代提示词）。
若禁用，从工作流中移除
```
issue_comment
```
触发器和仅迭代步骤。

完成标准：工作流、提示词和内存模板中的所有占位符都已选定值或明确默认值。

3. Define the agent job

3. 定义Agent任务

Extract the smallest repeatable job the agent should perform. Work through these three questions with the user:

What are we finding? How does the agent identify targets for this run?

A CLI tool that reports issues (e.g.,
```
bunx react-doctor
```
,
```
eslint --format json
```
)
A search pattern (e.g., files matching
```
*.test.ts
```
without coverage, components using deprecated APIs)
A diff or changelog (e.g., new dependencies since last release, changed files in a PR)
An old pattern that should be replaced with a new pattern or migrated to a new framework
A flaky test based on previous CI runs

What are we changing? What transformation does the agent apply to each target?

Fix: resolve a reported issue in place
Migrate: update code from one pattern to another
Generate: create new files based on existing sources
Refactor: restructure without changing behavior

How do we validate? What proves the change is correct?

Build/typecheck passes
Tests pass (or a specific subset)
The same tool that found the issue now reports it resolved
Linting or formatting checks pass

Completion criterion: you can state the job in one sentence, e.g., "Find 5 react-doctor violations, fix them, and verify typecheck and quality pass."

提炼Agent应执行的最小可重复任务。与用户一起解决以下三个问题：

我们要查找什么？ Agent如何识别本次运行的目标？

报告问题的CLI工具（如
```
bunx react-doctor
```
、
```
eslint --format json
```
）
搜索模式（如无覆盖率的
```
*.test.ts
```
文件、使用废弃API的组件）
差异或变更日志（如上次发布以来的新依赖、PR中变更的文件）
应替换为新模式或迁移到新框架的旧模式
基于之前CI运行的不稳定测试

我们要修改什么？ Agent对每个目标执行什么转换？

修复：就地解决报告的问题
迁移：将代码从一种模式更新为另一种
生成：基于现有资源创建新文件
重构：在不改变行为的情况下调整结构

如何验证？ 什么能证明变更正确？

构建/类型检查通过
测试通过（或特定子集）
发现问题的工具现在报告问题已解决
Linting或格式化检查通过

完成标准：可以用一句话描述任务，例如“找出5个react-doctor违规项，修复它们，并验证类型检查和质量检查通过。”

4. Write the skill

4. 编写Skill

Write a repo-local skill that captures the agent's judgement for this task. The skill can include repo-specific paths, package names, and conventions since it lives in this repository.

Use these skill-writing rules:

Put ordered behavior in
```
SKILL.md
```
in the skill directory (
```
.claude/skill-slug-here
```
or
```
.agents/skill-slug-here
```
depending on repo patterns and user preferences) steps with checkable completion criteria
Move long templates and examples into sibling reference files, then point to them from
```
SKILL.md
```
.
Keep one source of truth for each rule; do not repeat the same guidance in the skill, prompt, and memory file.
Include a response template as a reference file (e.g.,
```
references/response-template.md
```
under the skill directory) that defines how the CI agent should format its final output. The skill should instruct the agent to read and follow this template when formatting its final response which will be used as the PR body.
Use the skill template in
```
references/skill-template.md
```
. An EXAMPLE skill can be found in
```
references/example-skill.md
```
You may refer to https://agentskills.io/specification to understand skill specification.

IMPORTANT: the

name

field in the

SKILL.md

frontmatter must match the skill slug - e.g. a skill with name

fix-eslint-issues

must be in

.claude/skills/fix-eslint-issues/SKILL.md

.agents/skills/fix-eslint-issues/SKILL.md

Completion criterion: the skill explains how to do the job clearly enough that the agent can follow it without additional prompting, including how to format the final response.

编写一个仓库本地Skill，捕捉此任务的Agent判断逻辑。由于Skill存放在该仓库中，可包含仓库特定的路径、包名和约定。

遵循以下Skill编写规则：

将有序行为放在Skill目录（
```
.claude/skill-slug-here
```
或
```
.agents/skill-slug-here
```
，取决于仓库模式和用户偏好）的
```
SKILL.md
```
中，包含可检查完成标准的步骤
将长篇模板和示例移至同级参考文件，然后在
```
SKILL.md
```
中引用它们。
每个规则仅保留一个权威来源；不要在Skill、提示词和内存文件中重复相同指导。
包含一个作为参考文件的响应模板（如Skill目录下的
```
references/response-template.md
```
），定义CI Agent应如何格式化最终输出。Skill应指示Agent在格式化最终响应（将用作PR正文）时读取并遵循此模板。

使用

references/skill-template.md

中的Skill模板。示例Skill可在

references/example-skill.md

中找到

你可以参考https://agentskills.io/specification了解Skill规范。

重要提示：

SKILL.md

前置元数据中的

name

字段必须与Skill别名匹配——例如，名称为

fix-eslint-issues

的Skill必须位于

.claude/skills/fix-eslint-issues/SKILL.md

或

.agents/skills/fix-eslint-issues/SKILL.md

中

完成标准：Skill足够清晰地解释如何执行任务，Agent无需额外提示即可遵循，包括如何格式化最终响应。

5. Write the workflow prompt

5. 编写工作流提示词

Put repo-specific targeting in the GitHub Actions prompt, not in the generic skill. Include:

```
Begin by using the <skill-name> skill.
```
Scope: directories/packages the agent may change and may inspect.
Instructions: the reviewable unit of work, what to avoid, and how to validate.
Validation commands in fenced bash if applicable
Agent memory interpolation from
```
.github/agent-memory/<task-name>.md
```
.
Finishing requirements: validate, commit, push, and return a PR-ready summary.

Use

references/workflow-template.yml

as the base template. Use

references/prompt-template.md

when drafting the embedded prompt.

Completion criterion: the prompt contains all repo-specific constraints needed for an unattended run.

将仓库特定的目标选择逻辑放在GitHub Actions提示词中，而非通用Skill中。内容应包括：

```
Begin by using the <skill-name> skill.
```
范围：Agent可修改和可查看的目录/包。
说明：可审核的工作单元、需避免的事项及验证方式。
若适用，用bash代码块包含验证命令
从
```
.github/agent-memory/<task-name>.md
```
插入Agent内存内容。
完成要求：验证、提交、推送并返回可用于PR的摘要。

以

references/workflow-template.yml

为基础模板。编写嵌入提示词时使用

references/prompt-template.md

。

完成标准：提示词包含无人值守运行所需的所有仓库特定约束。

6. Install the memory file

6. 安装内存文件

Create

.github/agent-memory/<task-name>.md

using

references/memory-template.md

as a starting point. The memory file carries standing feedback that should affect future runs. Keep it short.

Good memory entries:

Permanent scope exclusions.
Known false-positive areas.
Review feedback that should change future agent selection.

Bad memory entries:

One-off task instructions.
Validation output from a single run.
Rules already stated in the skill.

Completion criterion: deleting the memory file would lose useful future-run context, not just history.

以

references/memory-template.md

为起点创建

.github/agent-memory/<task-name>.md

。内存文件承载影响未来运行的持续反馈。保持内容简洁。

合适的内存条目：

永久范围排除项。
已知误报区域。
应改变未来Agent选择的审核反馈。

不合适的内存条目：

一次性任务指令。
单次运行的验证输出。
已在Skill中说明的规则。

完成标准：删除内存文件会丢失对未来运行有用的上下文，而非仅丢失历史记录。

7. Create the workflow

7. 创建工作流

Create

.github/workflows/agent-<task-name>.yml

from

references/workflow-template.yml

and replace every placeholder.

Required customizations:

Workflow name, cron, branch prefix, workflow id, agent label, PR title.
Runner label and setup steps for the repo.
Dependency install command.
Coding-agent install, secret, and headless run command (from
```
references/agent-runner-templates.md
```
).
Response extraction step: each agent outputs differently (JSON, stream-json, plain text). Use the agent-specific extraction from
```
references/agent-runner-templates.md
```
to get the final response into
```
/tmp/pr-body.md
```
for the PR body.
Skill name, scope, validation commands, and memory path.
PR bounding gate: the workflow checks for open PRs with the agent label before running. Configure the bound based on the user's choice from step 2 (default: 1). The gate uses
```
gh pr list --label "$AGENT_LABEL" --state open
```
and compares the count. If bounding is disabled, remove the gate step entirely.
If
```
/iterate
```
is enabled: install
```
references/agent-iteration.ts
```
to the user's preferred location and update the workflow paths to match. The script handles both PR footer generation and iteration prompt building. This file can be run with the user's preferred typescript toolchain (node with type-stripping, Bun (recommended), Deno, tsx, etc) or can at the user's request be rewritten into another language.

/iterate

is disabled, remove the

issue_comment

trigger, the iteration-only steps, and skip installing

agent-iteration.ts

Completion criterion: the workflow can run from

workflow_dispatch

without relying on files that do not exist.

从

references/workflow-template.yml

创建

.github/workflows/agent-<task-name>.yml

并替换所有占位符。

必需的自定义项：

工作流名称、cron表达式、分支前缀、工作流ID、Agent标签、PR标题。
仓库的运行器标签和设置步骤。
依赖安装命令。
编码Agent的安装、密钥和无界面运行命令（来自
```
references/agent-runner-templates.md
```
）。
响应提取步骤：每个Agent的输出格式不同（JSON、流式JSON、纯文本）。使用
```
references/agent-runner-templates.md
```
中的Agent特定提取方法，将最终响应写入
```
/tmp/pr-body.md
```
作为PR正文。
Skill名称、范围、验证命令和内存文件路径。
PR限制 gate：工作流在运行前检查带有Agent标签的开放PR数量。根据用户在步骤2中的选择配置限制（默认：1）。该gate使用
```
gh pr list --label "$AGENT_LABEL" --state open
```
并比较数量。若禁用限制，完全移除gate步骤。
若启用
```
/iterate
```
：将
```
references/agent-iteration.ts
```
安装到用户偏好的位置，并更新工作流路径以匹配。该脚本处理PR页脚生成和迭代提示词构建。此文件可使用用户偏好的TypeScript工具链（带类型剥离的Node.js、Bun（推荐）、Deno、tsx等）运行，或根据用户请求重写为其他语言。

若禁用

/iterate

，移除

issue_comment

触发器、仅迭代步骤，并跳过安装

agent-iteration.ts

。

完成标准：工作流可通过

workflow_dispatch

运行，无需依赖不存在的文件。

8. Validate and verify

8. 验证与确认

Validate workflow YAML: Before committing, parse the workflow file to catch syntax errors early. Use one of:

bash

undefined

验证工作流YAML：提交前，解析工作流文件以尽早发现语法错误。可使用以下方式之一：

bash

undefined

Node.js / bun (js-yaml)

bunx js-yaml .github/workflows/agent-<task-name>.yml > /dev/null && echo "Valid YAML"

Python

python -c "import yaml; yaml.safe_load(open('.github/workflows/agent-<task-name>.yml'))"

yq (if installed)

yq (若已安装)

yq eval '.name' .github/workflows/agent-<task-name>.yml


If the parser fails, fix the YAML syntax before proceeding.

**Verify references and paths:** Check that every path named by the skill, workflow, and memory file exists or is intentionally created by this task.

Completion criterion: the workflow YAML parses without errors and all referenced files exist.

yq eval '.name' .github/workflows/agent-<task-name>.yml


若解析失败，先修复YAML语法再继续。

**验证引用和路径**：检查Skill、工作流和内存文件中提及的每个路径是否存在，或是否由本次任务有意创建。

完成标准：工作流YAML解析无错误，所有引用文件均存在。

9. Dry-run the workflow

9. 试运行工作流

GitHub Actions workflows cannot be manually dispatched via

workflow_dispatch

until they have run at least once. To bootstrap the workflow:

Temporarily add a

push

trigger for the current branch (if not main):

yaml

on:
  push:
    branches:
      - <current-branch-name>  # Remove after first run
  schedule:
    - cron: "0 13 * * *"
  workflow_dispatch:
    # ...

Commit and push all the new files (workflow, skill, memory file, scripts).
The workflow will trigger on push. Watch the Actions tab to verify it runs successfully.
After the first successful run, remove the temporary
```
push
```
trigger and push again. The workflow can now be dispatched manually via the Actions UI or
```
gh workflow run
```
.
If the dry-run creates a PR, review it to verify the agent behavior, then close or merge as appropriate.

Completion criterion: the workflow appears in the Actions tab and can be triggered via

workflow_dispatch

GitHub Actions工作流至少运行一次后，才能通过

workflow_dispatch

手动触发。要引导工作流启动：

临时为当前分支添加

push

触发器（若不是主分支）：

yaml

on:
  push:
    branches:
      - <current-branch-name>  # 首次运行后移除
  schedule:
    - cron: "0 13 * * *"
  workflow_dispatch:
    # ...

提交并推送所有新文件（工作流、Skill、内存文件、脚本）。
工作流将在推送时触发。查看Actions标签页以验证运行成功。
首次成功运行后，移除临时
```
push
```
触发器并再次推送。现在可通过Actions UI或
```
gh workflow run
```
手动触发工作流。
若试运行创建了PR，审核以验证Agent行为，然后酌情关闭或合并。

完成标准：工作流出现在Actions标签页中，可通过

workflow_dispatch

触发。

Reference Files

参考文件

```
references/workflow-template.yml
```
- coding-agent GitHub Actions workflow skeleton.
```
references/agent-runner-templates.md
```
- headless commands and secrets for Claude Code, Codex, OpenCode, and CodeLayer.
```
references/agent-iteration.ts
```
- helper script for
```
/iterate
```
support (PR footer and iteration prompt building). Install to
```
.github/scripts/
```
,
```
ci-scripts/
```
, or
```
scripts/
```
based on user preference.
```
references/prompt-template.md
```
- embedded prompt structure for the workflow.
```
references/memory-template.md
```
- agent-memory file skeleton.
```
references/skill-template.md
```
- skill skeleton for the generated task skill.
```
references/response-template.md
```
- examples for how the CI agent should format its final response (PR body).
```
references/example-skill.md
```
- example skill

```
references/workflow-template.yml
```
- 编码Agent GitHub Actions工作流骨架。
```
references/agent-runner-templates.md
```
- Claude Code、Codex、OpenCode和CodeLayer的无界面命令及密钥。
```
references/agent-iteration.ts
```
- 支持
```
/iterate
```
的辅助脚本（PR页脚和迭代提示词构建）。根据用户偏好安装到
```
.github/scripts/
```
、
```
ci-scripts/
```
或
```
scripts/
```
。
```
references/prompt-template.md
```
- 工作流的嵌入提示词结构。
```
references/memory-template.md
```
- Agent内存文件骨架。
```
references/skill-template.md
```
- 生成任务Skill的骨架。
```
references/response-template.md
```
- CI Agent应如何格式化最终响应（PR正文）的示例。
```
references/example-skill.md
```
- 示例Skill