agent-readiness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agent-readiness

Agent就绪评估（agent-readiness）

Assess a repository's readiness for autonomous agent work (à la factory.ai's agent readiness assessment, pylot-native). Clones the repo read-only, scores 8 dimensions, and files a single

🤖 Agent Readiness Report

issue in the assessed repo with scores and a prioritized remediation checklist. Idempotent: re-runs update the existing report issue instead of opening duplicates.

Install via npx:

bash

npx skills add fellowship-dev/dogfooded-skills/skills/ops/agent-readiness

评估仓库是否已准备好开展自主Agent工作（参考factory.ai的Agent就绪评估机制，pylot原生支持）。以只读方式克隆仓库，对8个维度进行评分，并在被评估仓库中创建一个名为

🤖 Agent Readiness Report

的Issue，包含评分结果和按优先级排序的整改清单。具备幂等性：重新运行时会更新现有报告Issue，而非创建重复内容。

通过npx安装：

bash

npx skills add fellowship-dev/dogfooded-skills/skills/ops/agent-readiness

When to Use

使用场景

Onboarding a fresh repo/org into pylot — know what to fix before dispatching missions
Demo: show a prospect exactly what agents need from their codebase, with a punch list
Quarterly re-assessment of active repos (readiness drifts as codebases evolve)

将新仓库/组织接入pylot时——在派发任务前了解需要修复的问题
演示：向潜在客户清晰展示Agent对其代码库的要求，并提供任务清单
对活跃仓库进行季度重新评估（代码库演进会导致就绪状态变化）

Inputs

输入参数

```
$1
```
—
```
org/repo
```
to assess (required)
```
$2
```
— pylot team name (optional; enables the Pylot Wiring dimension checks via the gateway)

```
$1
```
— 待评估的
```
org/repo
```
（必填）
```
$2
```
— pylot团队名称（可选；启用通过网关进行的Pylot Wiring维度检查）

Procedure

执行流程

0. Access + clone

0. 访问与克隆

Auth is ambient (never require a personal PAT): the pod's

git-credential-pylot

helper mints a short-lived App installation token per git operation. Clone with a plain https URL — inline credentials bypass the helper.

bash

git clone --depth 50 "https://github.com/${REPO}.git" /tmp/assess-repo

Shallow (depth 50) is enough — you need the tree + recent history, not archaeology.

身份验证为环境式（无需个人PAT）：Pod的

git-credential-pylot

助手会为每个Git操作生成一个短期的应用安装令牌。使用普通HTTPS URL进行克隆——内联凭据会绕过该助手。

bash

git clone --depth 50 "https://github.com/${REPO}.git" /tmp/assess-repo

浅克隆（深度50）已足够——只需获取目录树和近期历史，无需完整历史。

1. Score the 8 dimensions

1. 对8个维度进行评分

Score each 0–10 using the mechanical checks below, then adjust ±2 with judgment (explain any adjustment in the report). Do not fabricate: every score must cite the files/commands that produced it. If a check can't run, say so and score conservatively.

#	Dimension	Mechanical checks (each ✓/✗ with evidence)
1	Environment reproducibility	`.devcontainer/` or `Dockerfile` present; lockfile present (package-lock/poetry.lock/Gemfile.lock/go.sum); pinned runtime (.nvmrc, .tool-versions, engines); install command succeeds headlessly ( `npm ci` / `pip install -r` / etc. — actually run it, 10 min budget)
2	Test trust	test dir/files exist; test command discoverable (package.json scripts, Makefile, CI yml); tests RUN headlessly without live creds (actually run, 10 min budget); pass/fail/flaky count
3	Agent context	CLAUDE.md or AGENTS.md present; README explains what+how-to-run; architecture/docs dir; comment density not misleading
4	CI/CD	workflow files present; default-branch status of latest runs (via API); branch protection on default branch
5	Task readiness	open issues count; % with body >200 chars; labels exist; issue templates present
6	Secrets hygiene	`.env.example` or documented config; `.env` /keys NOT committed (grep for obvious creds: `-----BEGIN` , `AKIA` , `sk-` , hardcoded passwords); secrets usage documented
7	Pylot wiring (only if `$2` team given)	repo in team's `repos` (GET /crew); devbox_config registered; worker image exists; team goals set; org skills home exists — probe `GET $PYLOT_GATEWAY_URL/git-token?repo=<org>/pylot-skills` (also try `<org>/skills` ): 200 = exists & App-accessible, 4xx = missing. Skip cleanly ( `n/a` ) if no team arg
8	Code health quick-scan	lint/format config present; largest file LOC (>1500 = smell); TODO/FIXME density; dependency staleness (count majors behind on top 10 deps)

使用以下机械检查为每个维度评分（0-10分），然后可根据判断调整±2分（需在报告中说明调整原因）。禁止编造：每个评分必须引用生成该评分的文件/命令。如果某项检查无法运行，需注明并保守评分。

#	维度	机械检查项（每项需标注✓/✗并提供证据）
1	环境可复现性	存在 `.devcontainer/` 或 `Dockerfile` ；存在锁定文件（package-lock/poetry.lock/Gemfile.lock/go.sum）；固定了运行时版本（.nvmrc、.tool-versions、engines字段）；无交互安装命令执行成功（ `npm ci` / `pip install -r` 等——实际运行，预算10分钟）
2	测试可信度	存在测试目录/文件；可找到测试命令（package.json脚本、Makefile、CI配置yml）；无需实时凭据即可无交互运行测试（实际运行，预算10分钟）；记录通过/失败/不稳定测试数量
3	Agent上下文	存在CLAUDE.md或AGENTS.md；README说明功能及运行方式；存在架构/文档目录；注释密度合理（无误导性）
4	CI/CD	存在工作流文件；默认分支最新运行状态（通过API获取）；默认分支开启分支保护
5	任务就绪度	未解决Issue数量；正文超过200字符的Issue占比；存在标签；存在Issue模板
6	密钥规范	存在 `.env.example` 或已记录配置；未提交 `.env` /密钥（搜索明显凭据： `-----BEGIN` 、 `AKIA` 、 `sk-` 、硬编码密码）；密钥使用方式已记录
7	Pylot集成配置（仅当提供 `$2` 团队名称时检查）	仓库已加入团队的 `repos` （调用GET /crew接口）；已注册devbox_config；存在工作者镜像；已设置团队目标；组织技能主仓库存在——调用 `GET $PYLOT_GATEWAY_URL/git-token?repo=<org>/pylot-skills` （也可尝试 `<org>/skills` ）：返回200表示存在且应用可访问，返回4xx表示缺失。若未提供团队参数则标记为 `n/a` 跳过
8	代码健康度快速扫描	存在 lint/格式化配置；最大文件行数（超过1500行视为问题）；TODO/FIXME密度；依赖陈旧度（前10个依赖中主版本落后的数量）

2. Compute the verdict

2. 生成评估结论

Overall score = weighted mean: env 20%, tests 25%, context 15%, CI 10%, tasks 10%, secrets 10%, wiring 5%, health 5%. (Without a team arg, redistribute wiring's 5% to tests.)
Tier: 8.0+
```
READY
```
· 6.0–7.9
```
NEARLY READY
```
· 4.0–5.9
```
NEEDS WORK
```
· <4.0
```
NOT READY
```
Top fixes: the 3–7 highest-ROI remediations, each with effort (S/M/L) and which dimension it unblocks. Order by (score impact ÷ effort). Be concrete: "add
```
.devcontainer/devcontainer.json
```
with node:22 + postCreateCommand
```
npm ci
```
", not "improve environment".

总分 = 加权平均值：环境20%、测试25%、上下文15%、CI 10%、任务10%、密钥10%、集成配置5%、健康度5%。（若未提供团队参数，将集成配置的5%权重分配给测试）

等级： 8.0+分

就绪（READY）

· 6.0–7.9分

接近就绪（NEARLY READY）

· 4.0–5.9分

需要改进（NEEDS WORK）

· 低于4.0分

未就绪（NOT READY）

优先整改项： 3-7个投资回报率最高的整改措施，每项需标注工作量（小/中/大，S/M/L）及解锁的维度。按（评分提升幅度 ÷ 工作量）排序。需具体：例如“添加包含node:22及postCreateCommand
```
npm ci
```
的
```
.devcontainer/devcontainer.json
```
”，而非“改进环境”。

3. File the report issue

3. 创建报告Issue

Search for an existing open issue titled

🤖 Agent Readiness Report

(exact match) — update its body if found, create otherwise. Use the minted installation token.

Body template:

markdown

undefined

搜索标题为

🤖 Agent Readiness Report

的现有未关闭Issue（精确匹配）——若找到则更新其内容，否则创建新Issue。使用生成的安装令牌。

内容模板：

markdown

undefined

🤖 Agent Readiness Report — <org/repo>

Overall: <score>/10 — <TIER> · assessed <date> · commit <sha7>

Dimension	Score	Evidence
Environment reproducibility	x/10	<one-line: what was found/run>
… all 8 rows …

Overall: <score>/10 — <TIER> · assessed <date> · commit <sha7>

Dimension	Score	Evidence
Environment reproducibility	x/10	<one-line: what was found/run>
… all 8 rows …

Top fixes (highest ROI first)

<fix> (effort S/M/L, unblocks <dimension>) — <one concrete instruction> …

<fix> (effort S/M/L, unblocks <dimension>) — <one concrete instruction> …

What agents can already do here

<2-4 bullets of work types that are safe to dispatch TODAY given current scores>

Org setup (include ONLY if the org skills home probe failed)

Create your org's private skills home — repo
```
<org>/pylot-skills
```
(private, empty is fine), then install the pylot GitHub App on it. This is where org-specific agent skills live; without it your teams can only use the shared cross-org skills. (An org admin must do this — pylot's App token cannot create repos by design.)

Create your org's private skills home — repo
```
<org>/pylot-skills
```
(private, empty is fine), then install the pylot GitHub App on it. This is where org-specific agent skills live; without it your teams can only use the shared cross-org skills. (An org admin must do this — pylot's App token cannot create repos by design.)

Details

<per-dimension: checks run, outputs, and why the score>

Generated by pylot
/agent-readiness
. Re-run to refresh.

undefined

<per-dimension: checks run, outputs, and why the score>

Generated by pylot
/agent-readiness
. Re-run to refresh.

undefined

4. Report

4. 任务报告

Write the mission report (score, tier, issue URL, top fixes). One line per repo verdict — the owner reads scores, not transcripts.

撰写任务报告（评分、等级、Issue链接、优先整改项）。每个仓库的结论占一行——仓库所有者更关注评分而非详细记录。

Guardrails

防护规则

Read-only on the repo: never push, never open PRs, never modify code. The ONLY write is the report issue.
Never print minted tokens to logs or the report.
Install/test runs happen in the clone under
```
/tmp
```
, network allowed, 10 min budget each — if exceeded, record
```
timeout
```
as the evidence and move on.
If the clone itself fails, file no issue; fail the mission with the gateway error.

仓库只读： 禁止推送、创建PR或修改代码。仅允许写入报告Issue。
禁止将生成的令牌打印到日志或报告中。
安装/测试运行在
```
/tmp
```
下的克隆仓库中，允许联网，每项预算10分钟——若超时，记录
```
timeout
```
作为证据并继续后续步骤。
如果克隆失败，不创建Issue；返回网关错误标记任务失败。