agent-readiness

agent-readiness

评估代码仓库是否已准备好开展自主 Agent 工作（类似 factory.ai 的 Agent 准备度评估，pylot-native）。以只读方式克隆代码仓库，对 8 个维度进行评分，并在受评估的代码仓库中创建一个 🤖 Agent Readiness Report issue，列出评分和按优先级排序的改进清单。支持幂等操作：重复运行时会更新现有报告 issue，而不是创建重复项。

通过 npx 安装：

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

适用场景

• 将新的代码仓库／组织接入 pylot — 在派发任务之前，了解需要先修复哪些问题
• 演示：向潜在客户准确展示 Agent 需要代码库具备什么，并提供待办清单
• 每季度重新评估活跃代码仓库（随着代码库演进，准备度也会变化）

输入

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

流程

0. 访问权限与克隆

使用现有身份验证（绝不要求个人 PAT）：Pod 的 git-credential-pylot helper 会为每次 git 操作生成一个短期有效的 App 安装令牌。使用普通 https URL 克隆 — 在 URL 中内嵌凭据会绕过该 helper。

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

浅克隆（深度为 50）已足够 — 你需要的是文件树和近期历史记录，而不是考古。

1. 为 8 个维度评分

根据以下机械检查逐项评分（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；是否存在 worker 镜像；是否已设置团队目标；是否存在组织 skills 主目录 — 探测 GET $PYLOT_GATEWAY_URL/git-token?repo=<org>/pylot-skills（也尝试 <org>/skills）：200 = 存在且 App 可访问，4xx = 缺失。未提供团队参数时，干净地跳过（n/a）
8	代码健康状况快速扫描	是否存在 lint/格式化配置；最大文件的行数（LOC）（>1500 行视为隐患）；TODO/FIXME 密度；依赖项陈旧程度（统计排名前 10 的依赖项中落后主版本的数量）

2. 计算结论

• 总分 = 加权平均值：环境 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
• **优先修复项：**列出 ROI 最高的 3–7 项改进，每项标注所需投入（S/M/L）以及能改善的维度。按（分数影响 ÷ 投入）排序。具体说明，例如：“添加 .devcontainer/devcontainer.json，配置 node:22 和 postCreateCommand npm ci”，而不是“改进环境”。

3. 创建报告 issue

搜索是否存在标题为 🤖 Agent Readiness Report（完全匹配）的未关闭 issue — 若找到则更新其正文，否则创建新的 issue。使用生成的安装令牌。

正文模板：

# 🤖 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 … |

## Top fixes (highest ROI first)
- [ ] **<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.)*

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

---
_Generated by [pylot](https://pylot.fellowship.dev) `/agent-readiness`. Re-run to refresh._

4. 报告

撰写任务报告（评分、等级、问题 URL、首要修复项）。每个仓库的判定各占一行 — 所有者看的是评分，而不是日志记录。

保护措施

• 对仓库只读：绝不推送，绝不开 PR，绝不修改代码。唯一的写入操作是创建报告 issue。
• 绝不在日志或报告中输出生成的令牌。
• 安装／测试在 /tmp 下的克隆中进行，允许联网，每次预算为 10 分钟 — 若超时，将 timeout 记为证据，然后继续。
• 如果克隆本身失败，不创建 issue；使用网关错误使任务失败。