agent-friendly

Score the user's current repo locally with a bundled scorer and recommend a model class. Evaluates 16 static signals (AGENTS.md, CI, tests, README, linter, dev env, license, contributing, pre-commit hooks, deps manifest, type config, codebase size, plus four agent-specific instruction files) and produces overall + per-agent scores. Entirely local — no HTTP calls.

When to use

Invoke this skill when the user:

• Asks about the agent-friendliness of the current repo.
• Wants a model recommendation for the codebase they're in.
• Invokes /agent-friendly (or however their agent triggers skills) explicitly.

Skip when the user is asking about a different repo, a remote URL, or a concept rather than a specific local path — this skill operates only on the local file system.

How to run

1. Tell the user upfront: "I'll score the current working directory. Make sure you're at your project root — if you're in a subdirectory (src/, app/, etc.), the score will be artificially low. Pass the project root path explicitly if you want me to score somewhere else." Wait for confirmation only if cwd looks ambiguous (e.g. you can see they're inside a typical subdirectory name); otherwise just proceed.

2. Run the bundled scorer against the user's current working directory:

   node <skill-dir>/dist/index.js .

   <skill-dir> is the directory containing this SKILL.md (typically .claude/skills/agent-friendly/ for Claude Code, .agents/skills/agent-friendly/ for Codex / Cursor / Cline / others). Most agents resolve this automatically — if yours doesn't, look in the agent's skill directory.

   The CLI defaults to process.cwd() if no path is passed, so node <skill-dir>/dist/index.js (no argument) works equivalently. If the user explicitly asks to score a different repo on disk, pass that path as the first argument.

3. Parse the JSON output:

   {
     "overall": 87.4,
     "warnings": [], // string[] — surface to user before showing the score if non-empty
     "signals": [
       { "id": "agents_md", "label": "AGENTS.md", "pass": 1, "matchedPath": "AGENTS.md" }
       // 15 more signals...
     ],
     "modelScores": [
       {
         "modelId": "claude-code",
         "modelLabel": "Claude Code",
         "score": 89.2,
         "contributions": [
           /* ... */
         ]
       }
       // 8 more agents...
     ],
     "topImprovements": [
       { "label": "Contributing guide", "signalId": "contributing", "scoreGain": 2.1, "suggestion": "..." }
       // up to 3 entries
     ]
   }

   The warnings array is the CLI's heads-up channel. It fires when the path being scored doesn't look like a project root (no package.json, README.md, AGENTS.md, .git, or other project marker found). If non-empty, render the warning(s) to the user before showing the score so they can re-invoke from the right place.

How to render the result

The scorer profiles 9 agents and always returns scores for all of them in modelScores: Claude Code, Cursor, Devin, Codex, Gemini CLI, Kimi Code CLI, Aider, OpenHands, and Pi.

The recommendation is score-driven. Don't try to detect which agent is invoking this skill — the answer is the same either way: find the highest-scoring entry in modelScores, that's the agent this repo is most tuned for. Show the user; let them decide whether to switch. Never programmatically switch the agent or model.

Print a tight summary the user can read at a glance:

• Overall score with a band label (high / mid / low — see table below).
• Best-fit agent — the highest-scoring entry in modelScores, with its score.
• Runner-up if its score is within ~5 points of the best — gives the user a real alternative.
• Why — one short sentence pointing at the strongest signals (e.g. "strong AGENTS.md, tests in place, reproducible dev env"). Use the signals array (signals with pass: 1 and high weight in the best agent's profile).
• Recommended model class — mapped from the overall score (frontier / standard / small — see table). Note that the user can switch using /model (Claude Code, Codex, Gemini CLI, Cursor CLI) or their agent's equivalent — but don't switch for them, just suggest.
• Top improvements — up to 3 entries from topImprovements, each with its score gain.

Example output:

Agent-friendliness: 87.4 (high) — well-prepped for AI coding agents.
Best for: Claude Code (89.2). Cursor close behind at 86.1.
Why: strong AGENTS.md, tests in place, reproducible dev env.
Recommendation: frontier model (Opus, GPT-5, Gemini Pro). Switch via /model (or your agent's equivalent) if you want to — your call.
Top improvements:
  • Add a contributing guide (+2.1 pts)
  • Add pre-commit hooks (+1.4 pts)
  • Document the test command (+0.9 pts)

Score → model mapping

Provider-neutral. Recommend a model class — let the user pick the actual ID for their agent.

The reasoning: a high-scoring repo has the scaffolding (AGENTS.md, fast tests, clear dev env) that lets a frontier model actually deliver. A low-scoring repo lacks those affordances; a frontier model's extra reasoning has little to work with, so a smaller, faster model is the better trade.

On first invocation

After the first successful run, mention to the user that they can wire the skill into a SessionStart hook so it fires automatically each session — pointing at the website's /skill page for copy-paste snippets:

• Claude Code → .claude/settings.json: a SessionStart entry with "matcher": "startup" and a hooks list of { "type": "command" } handlers.
• Codex CLI → .codex/hooks.json: the same matcher-group shape. A bare command on the event is ignored.
• Other agents → run /agent-friendly whenever you want a fresh score.

Snippets live at https://agentfriendlycode.com/skill.

Failure modes

• Bundle missing. If dist/index.js doesn't exist next to this SKILL.md, the install was incomplete or the user is on an older skill version. Tell them to re-run npx skills add hsnice16/agent-friendly-skill#v0.
• Low score because cwd is a subdirectory. The scorer reads the path you pass it (default: cwd). If the user is in a subdirectory of their project (e.g. src/), 17 signals will mostly fail because root-level files like AGENTS.md, README.md, package.json aren't there. If the score looks unexpectedly low, mention this and ask the user to invoke from the project root (or pass the root path explicitly).
• Node not on PATH. Tell the user to install Node ≥ 20.9.0 (matches the bundle's runtime requirement).

Out of scope

• Scoring a remote URL, a different repo, or a package by name. This skill works on the active repo only. Direct the user to the website at https://agentfriendlycode.com or its /api/score?host=&repo=owner/name endpoint for indexed lookups.
• Programmatic model switching. The skill recommends; the user runs /model (or the agent's equivalent) themselves.
• Submitting the repo to the website. The skill is read-only — it never writes files, contacts the website, or registers the repo. Unindexed repos stay unindexed.