agent-readiness
Skill49 starsChanged 14 days agoApache-2.0View on GitHub
One repeatable pass that keeps fak the path of least resistance for an AI agent — Claude Code, OpenAI Codex, Cursor, an MCP client — to discover, adopt, and build on. Runs the agent-readiness scorecard (`fak score agent-readiness`, backed by internal/agentreadinessscore) over the git-tracked tree, turns each HARD defect into a required affordance to ADD (a missing agents.md entry point, a missing harness config, a dead orientation link, no copy-pasteable first command, no install one-liner, an untagged claim, a missing. Use when this named workflow matches the task.
- Installs packages
8 other projects use a version of this.
Adopted by
Most recently taken up by
- Canonry/agent-readinesstheir own version, first seen Nov 15, 2026
- superduck-ai/open-managed-agentstheir own version, first seen Nov 15, 2026
- Canonry/aeo-audittheir own version, first seen Nov 8, 2026
- redhat-developer/rhdh-skillstheir own version, first seen Oct 23, 2026
- smillunchick/sam-skillstheir own version, first seen Jul 19, 2026
- JKHeadley/instartheir own version, first seen Jul 13, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- JKHeadley/instar★ 86same name
- superduck-ai/open-managed-agents★ 32same name
- redhat-developer/rhdh-skills★ 20same name
- Canonry/aeo-audit★ 7same name
- Canonry/agent-readiness★ 7same name
- BlackBoxVision/skills★ 1same name
- misty-step/laboratory★ 1same name
- smillunchick/sam-skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository151 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- llms-full.txtllms.txt
- llms.txtllms.txt
- appeal-scoreSkill
- bottleneck-mapSkill
- ci-repairSkill
- claim-repro-scoreSkill
- clear-out-wipSkill
- commit-cleanSkill
- conflation-scoreSkill
- cross-validateSkill
- curate-clusterSkill
- debt-cleanSkill
- debt-orchestratorSkill
- disambiguation-scoreSkill
- dojo-rsi-scoreSkill
- dos-dispatch-loopSkill
- dos-dispatchSkill
- dos-next-upSkill
- dos-replanSkill
- dos-witness-claimSkill
- field-borrowSkill
- fleet-waveSkill
- git-subagent-syncSkill
- goalSkill
- guard-rsi-scoreSkill
- harness-creatorSkill
- harness-gardenSkill
- industry-scoreSkill
- issue-orchestratorSkill
- issue-queueSkill
- issue-triageSkill
- lightgap-scoreSkill
- memory-compactSkill
- milestone-scoreSkill
- modularizeSkill
- negframe-scoreSkill
- opencode-waveSkill
- operator-heaviness-scoreSkill
- persona-scoreSkill
- phased-planSkill
- plan-auditSkill
- quality-scoreSkill
- question-loopSkill
- refresh-cachedoc-numbersSkill
- refresh-readmeSkill
- releaseSkill
- resume-watchdog-auditSkill
- run-it-all-nightSkill
- score-2xSkill
- scorecardSkill
- scout-loopSkill
- signal-firstSkill
- skill-lifecycleSkill
- skill-overlapSkill
- skill-scoreSkill
- slop-scoreSkill
- sota-checkSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 64
If "fixing" a defect would mean gaming the detector instead of adding the affordance, stop — that's not a real gap.
- Distinctive: line 145
Read the SOFT list once; fix the cheap, real ones.
- Very specific: line 159
If you added or removed a scorecard surface, also re-fold the portfolio: python tools/scorecard_control_pane.py (agent-readiness reports …
- Very specific: line 191
After a change to any agent surface: AGENTS.md, llms.txt/llms-full.txt, CLAIMS.md, the docs/integrations/ recipes, the surfaced guardrails, …
- Very specific: line 193
When onboarding a new agent harness (add its agent_config + a recipe).
“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
agent-readiness — keep fak the path of least resistance for an agent, and prove it
What this does. An agent-first project lives or dies on a question no human-facing scorecard asks: can an autonomous coding agent that lands in the repo cold discover what fak is, want to adopt it, and build on it without tripping over a missing affordance or an undocumented guard? This pass turns that from a vibe ("we have an AGENTS.md, we're fine") into a repeatable, provable number — the way
industry-scorekeeps the competitive story honest andrepo-hygienekeeps the tree lean.
The shape: run the scorecard → add every missing affordance (HARD defect) → weigh every SOFT signal → re-measure to prove friction-debt dropped and the experience-frontier climbed → regenerate the snapshot → commit only the scorecard lane.
There are two headline numbers, because agent-readiness is two questions:
- friction-debt (the BASELINE gate, lower = better, floor 0): the count of concrete, re-derivable defects that make the expected affordances missing or broken. Zero means the current metric version detects none in the current corpus; keep discovering new failure classes rather than treating the ledger as complete. The shipped tree currently reads 0 / grade A for that named detector.
- experience-frontier (the HEADLINE, higher = better, unbounded): the
weighted count of real, working agent affordances the tree actually provides — an
integration recipe an agent follows, a zero-setup harness config, a kernel refusal
an agent can recover from, a tool an agent drives via
--json. It is deliberately NOT a 0-100 grade: agent experience is a never-done program (the same category as kernel- and cache-optimization), so it has no ceiling and is tracked as a frontier + a trend, never a completion %. It is the deliberate mirror ofinternal/heavinessscore's unboundedheaviness_pressure(the load an operator carries); this is the surface an agent gains. You move it by adding a real affordance (onboard a harness, map a refusal, expose a--jsonsurface) — never by gaming a substring, the same rule the friction-debt gate enforces.
Drive friction-debt to zero and climb the frontier, and "attractive to agents" becomes a pair of numbers you moved, not a claim you made. (The stick any forked or adopting repo measures its own gap against.)
The one rule that overrides everything: add the affordance, never fake the check
The scorecard reads the real tracked tree. Every KPI is a genuine agent affordance — a file that must exist, a link that must resolve, a command that must be paste-able, a claim that must be tagged. So:
- Retire a defect by adding the real thing an agent reaches for, not by adding
a keyword to satisfy a substring match. A
first_commanddefect is fixed by a fenced, runnable no-key command an agent can actually paste — not by typing the wordsfak preflightinto prose. - Never weaken a claim or a guard to score. The honesty ledger, the trunk law,
the leaf/ABI discipline are load-bearing;
guardrails_surfacedwants them documented, never relaxed. - It is read-only. The tool edits nothing; you make the edit, then re-run.
If "fixing" a defect would mean gaming the detector instead of adding the affordance, stop — that's not a real gap.
The three steps an agent walks (the groups, and the HARD defects each retires)
Twenty KPIs, each 0–100, grouped by the step they gate. Retire worst-step-first
(the scorecard names the weakest step in group_scores). The presence KPIs ask
does the affordance exist; the paste-and-run / executable-truth KPIs ask the
question presence can't reach — does an agent who pastes the docs actually succeed
(a bounded presence-only score can read 100 while a cold agent still trips on a stale
cd fleet/fak, a /path/to/… placeholder, or a fak <verb> the binary never dispatches).
| Step | KPI | The affordance to add when it's red |
| discover | agents_entrypoint | An AGENTS.md (the agents.md convention) that states what fak is and carries build + test + run commands. |
| discover | agent_config | The zero-setup configs a harness auto-loads: .mcp.json, .cursorrules, .github/copilot-instructions.md. |
| discover | agent_config_valid | SUCCESS — the auto-loaded config is well-formed, not just present: .mcp.json parses and every server names a launch command (else the harness silently fails to start it). |
| discover | llms_map | llms.txt (the answer-engine / agent doc-map). |
| discover | identity_statement | A one-sentence "fak is a/an …" near the top of AGENTS.md / llms.txt / README an agent can quote. |
| discover | entry_links_resolve | Fix any dead local link in AGENTS.md or the integration index — a 404 on the orientation path. |
| discover | recipe_links_resolve | SUCCESS — every local link INSIDE each per-agent recipe resolves (one hop past the index — the recipe an agent is actively following). |
| adopt | first_command | A copy-pasteable, fenced, no-key/no-model/no-GPU first command (the 30-second proof). |
| adopt | command_verbs_resolve | SUCCESS — every fak <verb> an agent pastes resolves to a real dispatched verb (parsed live from cmd/fak/main.go); a doc that says fak hooks when the verb is fak hook is an ambush. |
| adopt | first_command_runs | SUCCESS — the first command actually RUNS from a clean clone: the --policy it names exists on disk, and it's the no-key form (not a serve --api-key-env sold as step one). |
| adopt | fenced_paths_resolve | SUCCESS — every path an agent pastes from a fenced block resolves in a clean clone: no stale cd fleet/fak private-monorepo prefix, no non-existent repo-relative path, no /path/to/… literal in a runnable line. |
| adopt | install_oneliner | The go install …@latest one-liner (the module is at the repo root, so it resolves). |
| adopt | honesty_ledger | CLAIMS.md present, every - [ claim carrying exactly one status tag (the make claims-lint rule). |
| adopt | integration_recipes | A per-agent recipe under docs/integrations/ for each family (Claude, Codex/OpenAI, Cursor, MCP). |
| adopt | codex_recipe_current | The Codex recipe matches current Codex surfaces: MCP for the CLI/IDE path, codex exec --json, AGENTS.md discovery, and an honest Responses-vs-Chat-Completions fence. |
| build | extension_scaffold | The additive path: fak new-leaf + EXTENDING.md (add a leaf, don't edit core). |
| build | guardrails_surfaced | Document each enforced rule in AGENTS.md: trunk-only, commit-by-path, DCO sign-off, tagged claims, leaf/ABI, the out-of-tree write guard. |
| build | contributor_contract | CONTRIBUTING.md linked from the entry point + a one-command green gate (make ci). |
| build | platform_guidance_consistent | SUCCESS — if AGENTS.md sells make ci as the gate, it names the native-Windows bridge (scripts/ci.ps1 / ./test.ps1 under WSL) so a Windows agent isn't told to run a gate it can't. |
| build | machine_consumable | SOFT — how much of the measurement family speaks --json. Scores; never hard debt. |
SOFT signals (a missing llms-full.txt, a tool without --json) lower the
score but are never friction-debt; weigh them, don't grind on them.
Step 1 — Run the scorecard (it builds your work-list)
From the repo root:
fak score agent-readiness --json > agent-readiness.jsonThis machine-readable artifact is mandatory. Before choosing work, quote every non-zero
corpus.breakdown row from it. When present, prioritize command_verbs_resolve and
refusal_recovery_mapped before softer copy polish. Product defects exposed by those rows
belong in dedicated issues rather than being silently fixed inside a skill-only pass.
It scores the three steps (discover · adopt · build) into a composite (0–100, A–F) and a friction-debt integer, and prints the work-list: every HARD defect with the affordance to add, then the SOFT signals. Read-only; it never edits the tree.
Step 2 — Retire friction-debt worst-step-first
Take the weakest measured step first (the captured JSON names it in group_scores and
corpus.breakdown). Quote the exact non-zero rows in the work record. For each HARD defect,
add the real affordance from the table above, using a dedicated product issue when the fix is
outside this skill. After a batch, re-run
the scorecard and watch the number fall; that loop (add, re-measure, add again)
is the whole method. Capture a before/after baseline so you can prove the drop:
fak score agent-readiness --json > /tmp/before.json # baseline before the pass
# … add the issue-authorized affordances …
fak score agent-readiness --compare /tmp/before.json # experience-frontier delta (+35% goal) + friction-debt delta--compare leads with the experience-frontier delta and a percentage: the goal
is a frontier climb (the default target is +35%), because the friction-debt
gate has already bottomed out at 0 — improvement now lives entirely on the unbounded
frontier. It also still prints the friction-debt 2x gate (held at 0).
Step 3 — Weigh the SOFT signals, then stop
Read the SOFT list once; fix the cheap, real ones. Don't chase them to zero — a token added only to move a metric is the gaming this pass refuses.
Step 4 — Re-measure, confirm, regenerate the snapshot
Re-run fak score agent-readiness --json; compare and quote the before/after
corpus.breakdown rows, then state the before/after on BOTH headlines (e.g. "friction-debt
6 → 0, adopt 67 → 100; experience-frontier 284 → 384, +35%"). Then regenerate the
committed snapshot so the doc matches the tree:
go run ./cmd/fak score agent-readiness --markdown --stamp $(date +%F) > docs/AGENT-READINESS-SCORECARD.mdIf you added or removed a scorecard surface, also re-fold the portfolio:
python tools/scorecard_control_pane.py (agent-readiness reports friction_debt).
Step 5 — Commit only the scorecard lane, by explicit path
This is a shared trunk; commit your lane, never a peer's work:
fak sync reconcile --apply
fak commit \
--path internal/agentreadinessscore/agentreadinessscore.go \
--path internal/agentreadinessscore/agentreadinessscore_test.go \
--path cmd/fak/agentreadinessscore.go \
--path docs/AGENT-READINESS-SCORECARD.md \
-F <msgfile> [--push]
fak sync push- Stage by explicit path via
fak commit --path, nevergit add -A— stage + commit in one shell call so a peer's bare commit can't sweep your files. - Subject: a code change to the tool →
feat(tools): … (fak tools); a docs-only snapshot regen →docs(scorecard): … (fak docs). End with the(fak <leaf>)trailer; lead with a verb. - The control pane (
tools/scorecard_control_pane.py),INDEX.md, and this skill are co-edited by peers adding sibling scorecards — if one shows in your diff and you didn't change it, exclude it; if aMERGE_HEADis set, wait it out, then commit by explicit path.
When to run this
- After a change to any agent surface: AGENTS.md, llms.txt/llms-full.txt,
CLAIMS.md, the
docs/integrations/recipes, the surfaced guardrails,fak new-leaf. - When onboarding a new agent harness (add its
agent_config+ a recipe). - On a
/loopcadence to keep the front door agent-friendly as the repo grows.
The scorecard is fak's agent-experience checking layer, the way industry-score
is its competitive layer and repo-hygiene is its structural one. Same discipline:
a number you can move, and prove you moved.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

