# Agent Readiness

> Use when assessing whether a repo is ready for autonomous AI agents (pylot workers) — produces a scored, actionable Agent Readiness Report as a GitHub issue in the assessed repo.

- Skill: `fellowship-dev/agent-readiness` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fellowship-dev/agent-readiness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fellowship-dev/agent-readiness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: fellowship-dev (https://skillmd.com/u/fellowship-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fellowship-dev/agent-readiness

---


# 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
```

## 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)

## Inputs

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

## Procedure

### 0. Access + clone

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.

### 1. Score the 8 dimensions

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) |

### 2. Compute the verdict

- **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".

### 3. File the report 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
# 🤖 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. Report

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

## 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.