feat: add task 03 in 0.4.0

Author: hsnice16

AGENTS.md

@@ -37,7 +37,7 @@ bun run test           # unit tests (node --test + tsx) — requires Node ≥20.
 
 ## Layout
 
-```txt
+```text
 app/
   layout.tsx              # root layout (nav + footer) — defines root metadata + OG / Twitter cards
   page.tsx                # leaderboard

CONTRIBUTING.md

@@ -30,7 +30,7 @@ Keep it short. `feat/postgres-migration` is better than `feat/add-postgres-migra
 
 One logical change per commit. Short imperative subject (≤72 chars), body only if the change needs explanation.
 
-```txt
+```text
 Add license signal — scores repos by SPDX ID presence
 
 Reads LICENSE, LICENSE.md, or COPYING at repo root. If `license:` is

README.md

@@ -133,7 +133,7 @@ Run the unit tests with `bun run test` (uses `node --test` + `tsx`; requires Nod
 
 ## Layout
 
-```txt
+```text
 app/          Next.js App Router — pages + API + SEO
   layout.tsx       root layout, root metadata (OG + Twitter cards)
   page.tsx         leaderboard

lib/roadmap.ts

@@ -28,6 +28,12 @@ export const ROADMAP: RoadmapVersion[] = [
         taskFile: "tasks/0.4.0/02-score-diff-on-pr.md",
         summary: "GitHub Action that comments score delta on every PR.",
       },
+      {
+        title: "Claude Code skill",
+        taskFile: "tasks/0.4.0/03-claude-code-skill.md",
+        summary:
+          "Skill (installable via npx skills add) that checks the active repo's score and recommends a Claude model. Ships with the /api/score lookup endpoint and a UI integration page with a SessionStart hook snippet.",
+      },
     ],
   },
   {

tasks/0.4.0/03-claude-code-skill.md

@@ -0,0 +1,64 @@
+# 03 · Claude Code skill (with public score lookup)
+
+**Status**: planned
+
+## Goal
+
+Ship a Claude Code skill that fetches the active repo's score and recommends a model, plus the public lookup endpoint it depends on and a UI page that explains the integration. Bundled because the endpoint has no other consumer in 0.4.0 and the three pieces only make sense together.
+
+Installable via `npx skills add hsnice16/agent-friendly-code` (the [vercel-labs/skills](https://github.com/vercel-labs/skills) CLI auto-discovers a top-level `skills/` directory).
+
+## Pieces
+
+### 1. Public lookup endpoint
+
+`GET /api/score?host=github&repo=<owner>/<name>`
+
+- 200 with `{ repo, signals, modelScores }` — same shape as `/api/repo/[id]` so consumers share a type.
+- 404 with `{ error: "not_indexed" }` when not found — explicit so the skill can branch on it cleanly.
+- 400 on malformed `repo`. `host` defaults to `github`.
+- Thin wrapper around `getRepoByHostOwnerName` in `lib/db.ts`. No on-demand scoring; no GitHub token usage at request time.
+
+### 2. The skill
+
+```text
+skills/
+  agent-friendly/
+    SKILL.md
+```
+
+Frontmatter (per vercel-labs/skills convention):
+
+```yaml
+---
+name: agent-friendly
+description: Check the active repo's agent-friendliness score and recommend a Claude model. Use when the user asks "is this repo a mess?", "which model should I use here?", or invokes /agent-friendly.
+---
+```
+
+Body: instructions for Claude to (a) resolve `owner/name` from the git remote, (b) `GET /api/score` against the deployed instance, (c) on 200, render score + recommended model, (d) on 404, say so plainly and skip the recommendation, (e) on first invocation, surface the SessionStart hook snippet so the user can opt into automatic checks. Score → model mapping lives in this file (high score → Opus / Sonnet, low score → Haiku); exact thresholds and model IDs land during implementation.
+
+### 3. UI page
+
+New route (e.g. `/skill` or `/integrations/claude-code`):
+
+- One-paragraph pitch.
+- Install command: `npx skills add hsnice16/agent-friendly-code`.
+- Manual invocation: `/agent-friendly`.
+- Copy-paste `SessionStart` hook snippet for `.claude/settings.json` that `curl`s `/api/score` and prints score + recommendation into the session context.
+- Linked from the homepage and added to `lib/roadmap.ts`.
+
+The hook snippet on the UI page and the skill's first-invocation nudge must stay in sync — same content, two surfaces.
+
+## Acceptance
+
+- `GET /api/score?host=github&repo=owner/name` returns the documented shape; 404 body distinguishes `not_indexed` from generic errors.
+- `npx skills add hsnice16/agent-friendly-code` installs into `.claude/skills/agent-friendly/`.
+- `/agent-friendly` in a Claude Code session inside a git repo prints the score + model recommendation, or a clean "not indexed" message.
+- UI page is reachable from the homepage; install command + hook snippet match the skill's output.
+- README gains a short "Public API" section pointing skill / hook authors at `/api/score`.
+
+## Out of scope
+
+- On-demand scoring of unindexed repos.
+- Programmatic model switching. The skill recommends; the user runs `/model` themselves.

tasks/0.4.0/README.md

@@ -2,9 +2,10 @@
 
 **Status**: planned
 
-The cheapest two items on the roadmap, paired so they can ship in one cut. History-aware signals extend the existing host-API clients with ~3 new signal files; the PR-diff GitHub Action is a thin wrapper that calls the badge / API endpoints we already ship. No new infra, no new deps of consequence — high-impact additions that don't need a heavy release.
+The cheapest items on the roadmap, paired so they can ship in one cut. History-aware signals extend the existing host-API clients with ~3 new signal files; the PR-diff GitHub Action is a thin wrapper that calls the badge / API endpoints we already ship; the Claude Code skill bundles a small lookup endpoint, a `SKILL.md` shipped from this repo, and a UI integration page. No new infra, no new deps of consequence — high-impact additions that don't need a heavy release.
 
 ## Tasks
 
 - [01-history-aware-signals.md](./01-history-aware-signals.md) — extend the scorer with maintenance recency, commit velocity, and contributor activity. Hybrid fetch (shallow clone for files, host API for history) — degrades gracefully without a token.
 - [02-score-diff-on-pr.md](./02-score-diff-on-pr.md) — GitHub Action that comments the score delta on every PR using the existing `/api/repo/:id` and `/badge/...svg` endpoints.
+- [03-claude-code-skill.md](./03-claude-code-skill.md) — Claude Code skill (installable via `npx skills add`) that fetches the active repo's score and recommends a model, bundled with the public `/api/score` lookup endpoint it depends on and a UI integration page with the SessionStart hook snippet.

tasks/README.md

@@ -4,7 +4,7 @@ Per-version work breakdown, readable by any agent (Claude Code, Cursor, Codex, D
 
 ## Structure
 
-```txt
+```text
 tasks/
   README.md               <- this file
   <MAJOR.MINOR.PATCH>/    <- one folder per version, e.g. 0.1.0, 0.2.0
@@ -24,7 +24,7 @@ Each task file has a `**Status**: …` line:
 
 Starting a session, point the agent at a specific task:
 
-```txt
+```text
 Work on tasks/0.2.0/01-tests.md.
 ```