Skip to content

kithek/scorecard

v0.1.3MIT

Turn any repo into a descriptive project manual with Write mode. Never grades.

What Scorecard does

Scorecard is an agent skill plus a small web kit. You point your coding agent (Cursor, Claude Code, Codex, GitHub Copilot, or any agent that reads Agent Skills) at a repository. It interviews you, scans the code, and writes a short, honest site about the work:

PartWhat the reader learns
The jobOne sentence: for whom, and what it does
Brief vs outcomeWhat you set out to do, next to what actually shipped
Status per featureworks · partial · stubbed · cut, plus the biggest gap
Built vs borrowedYour own work, separated from libraries, templates, APIs and starters
ProofA demo, screenshot, test or metric, only when one is real
Run itSetup steps and a 60-second demo script
NextWhat you’d do with more time

You finish it yourself in Write mode, a diary-style editor in the browser, and publish a static build.

Why it never grades

READMEs and slide decks tend to flatten finished work into either hype or silence. Course markers, hackathon judges, teammates and future-you all need the same thing: an honest map of what is real, what is mocked, and how to run it. They don’t need a score, a leaderboard or a performance review.

AI tools make it easy to generate docs that sound finished. Scorecard steers them toward evidence instead:

  • 🖋 Draft until you confirm. Agents can only write draft or inferred claims. Only you can mark something confirmed, in Write → Review.
  • 🔎 Inferred means cited. An inferred claim must point at a file path or a commit.
  • 🛡 Your words are safe. Re-running the skill updates generated text and proposes diffs for anything you wrote; it never overwrites it.
  • 🌱 Sized to the work. Lite (one page), Standard (chapters when earned) or Full (long-lived, multi-service). Empty sections stay hidden, so a weekend hackathon never gets a fake branch history.
WhoWhy it fits
Students and courseworkA requirements map with file paths. Partial work stays partial.
Hackathon teamsA Lite page plus a 90-second demo script, with stubs called out
Solo buildersCLIs and side projects described without overselling
Small teamsShared ownership areas, with no invented individual glory

Want to see a Full manual? Libretto is one, live at 499team1.com/make.

A tour

These are real screenshots of the kit in this repo, running npx scorecard-kit dev on its own content/.

The five demo packs

Run npx scorecard-kit demos inside the kit, or open /demos while npx scorecard-kit dev is running.

DemoRepo shapeDeep link
Hackathon weekendGreenfield demo with mocked bank sync/demos/hackathon
Personal CLISolo tool, brittle edges called out/demos/personal-cli
Course assignmentRubric map, partial persistence/demos/assignment
Team productMulti-owner areas, no fake metrics/demos/team
No READMESparse repo, draft-heavy until you add your voice/demos/no-readme

The look: typefaces and ornaments

Manuals are set in Libretto Paléologue, a display face drawn after Jean de Paléologue’s 1900 lithograph posters, with Newsreader, Source Sans 3 and Departure Mono. Run npx scorecard-kit look to browse the schemes (libretto, plate, poster, plain) and ornaments, then name the ones you want when the skill asks. If you’d rather have no ornaments, ask for the plain scheme.

Quick start

  1. Install the skill for your agent. See Install below; it takes about a minute.
  2. Open your project in that agent and ask:

    Use the scorecard skill on this repo. Infer first, confirm with me, scaffold ./scorecard, then hand off to Write mode.

  3. Answer a few short batches of questions. The skill suggests answers from the code, and you confirm or correct them. Skipping is fine; skipped items stay draft.
  4. Finish it in Write mode. The skill copies the kit into ./scorecard, then:
    cd scorecard
    npx scorecard-kit dev      # opens Write mode in your browser (port 5199, or the next free one)
    
  5. Publish.
    npx scorecard-kit build    # static site in scorecard/dist/, with no Write mode or save endpoint
    

Tip

Just want to look around first? You don’t need an agent:

git clone https://github.com/KitheK/scorecard.git
cd scorecard
npm install
npx scorecard-kit demos

Install

Scorecard is one Agent Skill, skills/scorecard/ (a SKILL.md plus references), following the open Agent Skills format. The repo is also its own plugin marketplace for Cursor (.cursor-plugin/) and Claude Code (.claude-plugin/). It also has an Agent Plugins manifest (plugin.json) and ready-made copies of the skill in each agent’s project folder, so cloning this repo and opening it in any of these agents already works.

To use Scorecard on your own projects, install it once. Cursor and Claude Code install it from GitHub in one step. Every agent also has a manual route, which is a plain folder copy.

AgentWhere the skill goesInvoke it with
CursorOne step: Customize → import from GitHub → KitheK/scorecard. Manual: ~/.cursor/plugins/local/scorecard//scorecard, or just ask
Claude CodeOne step: /plugin marketplace add KitheK/scorecard. Manual: ~/.claude/skills/scorecard//scorecard:scorecard (plugin), /scorecard (manual), or just ask
OpenAI Codex~/.agents/skills/scorecard/ or <project>/.agents/skills/scorecard/$scorecard, or just ask
GitHub Copilot<project>/.github/skills/scorecard/ (+ the agent file), or ~/.copilot/skills/The scorecard agent, or just ask
Other agentsThat agent’s skills folder, or a pointer in AGENTS.mdAsk for a Scorecard

The manual routes start from one shared copy of the repo. This is the same path the skill uses when it scaffolds a kit:

git clone --depth 1 https://github.com/KitheK/scorecard.git /tmp/scorecard-kit

Windows (PowerShell)

git clone --depth 1 https://github.com/KitheK/scorecard.git "$env:TEMP\scorecard-kit"

Cursor

One step, from GitHub. This repo is a Cursor plugin marketplace (.cursor-plugin/marketplace.json), named kithek, which lists one plugin, scorecard.

  1. Open Customize in the sidebar and import a marketplace From GitHub Repository.
  2. Paste https://github.com/KitheK/scorecard.
  3. Find scorecard and choose Install, at user or project scope.
  4. In Agent chat, type /scorecard, or just ask for a Scorecard.

Manual: a local plugin. Cursor also loads the whole repo as a plugin from ~/.cursor/plugins/local. It reads .cursor-plugin/plugin.json and the logo, and finds the skill in skills/.

git clone https://github.com/KitheK/scorecard.git ~/.cursor/plugins/local/scorecard

Windows (PowerShell)

git clone https://github.com/KitheK/scorecard.git "$env:USERPROFILE\.cursor\plugins\local\scorecard"

Then restart Cursor (or run Developer: Reload Window), and check under Customize that scorecard appears under Skills.

Prefer a plain skill, without the plugin?

Cursor also loads skills from ~/.cursor/skills/ and ~/.agents/skills/ (all projects), or from .cursor/skills/ and .agents/skills/ inside one project:

mkdir -p ~/.cursor/skills
cp -R /tmp/scorecard-kit/skills/scorecard ~/.cursor/skills/scorecard

Note

For the manual route, clone straight into the local folder rather than symlinking it, because Cursor skips symlinks that point outside that folder. On Enterprise plans, an admin may have to allow GitHub or local plugin imports. Docs: Plugins · Plugins reference › marketplace manifest · Agent Skills

Claude Code

One step, from GitHub. This repo is a Claude Code plugin marketplace (.claude-plugin/marketplace.json) named kithek. Inside a claude session, run:

/plugin marketplace add KitheK/scorecard
/plugin install scorecard@kithek

To do the same from your shell:

claude plugin marketplace add KitheK/scorecard
claude plugin install scorecard@kithek

Plugin skills are namespaced, so the skill becomes /scorecard:scorecard, or you can just ask for a Scorecard. On Claude Code 2.1.275 or later, one command does both steps: /plugin install scorecard --marketplace KitheK/scorecard.

Manual: a plain skill. Claude Code also loads skills from your personal folder (every project) or from a project’s .claude/skills/.

For every project:

mkdir -p ~/.claude/skills
cp -R /tmp/scorecard-kit/skills/scorecard ~/.claude/skills/scorecard

Windows (PowerShell)

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse "$env:TEMP\scorecard-kit\skills\scorecard" "$env:USERPROFILE\.claude\skills\scorecard"

For one project only (run it from the project root and commit the folder to share it with your team):

mkdir -p .claude/skills
cp -R /tmp/scorecard-kit/skills/scorecard .claude/skills/scorecard
  1. Start a new claude session in your project.
  2. Check that it loaded by asking “What skills are available?”
  3. Run /scorecard, or ask for a Scorecard of the repo.

Note

Docs: Plugin marketplaces · Marketplace reference · Extend Claude with skills. The manifests pass claude plugin validate --strict.

OpenAI Codex

Codex (CLI, IDE extension and the ChatGPT desktop app) reads skills from ~/.agents/skills and from .agents/skills in the repo you’re working in.

For every repo:

mkdir -p ~/.agents/skills
cp -R /tmp/scorecard-kit/skills/scorecard ~/.agents/skills/scorecard

Windows (PowerShell)

New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills" | Out-Null
Copy-Item -Recurse "$env:TEMP\scorecard-kit\skills\scorecard" "$env:USERPROFILE\.agents\skills\scorecard"

For one repo (run it from the repo root):

mkdir -p .agents/skills
cp -R /tmp/scorecard-kit/skills/scorecard .agents/skills/scorecard
  1. Codex picks up new skills automatically. If Scorecard doesn’t show up, restart Codex.
  2. Run /skills to check, then type $scorecard, or just describe what you want.

Note

Docs: Codex › Build skills. The .agents/skills/ folder in this repo is the same skill, already in place for anyone who clones it.

GitHub Copilot (VS Code and CLI)

Copilot uses the skill from .github/skills/. It also gets a custom scorecard agent, from .github/agents/scorecard.agent.md, that you can pick in the chat’s agent dropdown.

For one project (run it from the project root; this copies both the skill and the agent):

mkdir -p .github/skills .github/agents
cp -R /tmp/scorecard-kit/.github/skills/scorecard .github/skills/scorecard
cp /tmp/scorecard-kit/.github/agents/scorecard.agent.md .github/agents/

For every project (skill only; the agent file points at .github/skills/, so it stays per-project):

mkdir -p ~/.copilot/skills
cp -R /tmp/scorecard-kit/skills/scorecard ~/.copilot/skills/scorecard
  1. In VS Code, run Chat: Open Customizations and check that scorecard is listed.
  2. In Chat, pick the scorecard agent from the agent dropdown, or just ask Copilot for a Scorecard.

Note

Docs: Use Agent Skills in VS Code · Custom agents

Any other agent

Scorecard is a standard Agent Skill: a folder with a SKILL.md whose frontmatter holds name and description, plus plain Markdown references.

  • If your agent supports Agent Skills, copy skills/scorecard/ into its skills folder, keeping the folder name scorecard.
  • If it only reads AGENTS.md, copy the folder anywhere in your project and point to it from AGENTS.md:
## Project manual (Scorecard)
When asked to summarise or document what this repo built, follow
`tools/scorecard/SKILL.md` and the files it references. Never grade,
never invent metrics, never set provenance to "confirmed".
mkdir -p tools
cp -R /tmp/scorecard-kit/skills/scorecard tools/scorecard

The tools/scorecard path is just an example; any path works as long as AGENTS.md points to it.

What’s not supported yet

To keep this list honest:

  • Public marketplace listings. Scorecard installs straight from this GitHub repo. It isn’t listed in the Cursor Marketplace (which needs Cursor’s review) or in Anthropic’s official plugin directory.
  • npm. The CLI is called scorecard-kit, so it can’t be confused with the unrelated scorecard package on npm, but it isn’t published. Run npx scorecard-kit … inside the kit folder, where it resolves to this repo’s bin/scorecard.js, or run node bin/scorecard.js … directly.

Using it

Some prompts that work well in any of the agents above:

You sayWhat happens
“Use the scorecard skill on this repo. Infer first, confirm with me, scaffold ./scorecard, then hand off to Write mode.”The full flow: profile, bounded scan, interview, scaffold, fill, check
“Make a Lite Scorecard for this hackathon repo. Keep it to one page with a 90-second demo script.”Lite size; empty sections stay hidden
“Quick depth only. I’ll fill in the rest in Write mode.”Fewer questions; everything you skip stays draft
“Map this coursework to the requirements in brief.pdf. No grades.”A requirements map with file paths; partial stays partial
“Refresh the Scorecard from the repo. Propose diffs for anything I wrote.”Updates generated text only and proposes changes to your text
“Use the plain scheme, no ornaments.”Same kit, no Mucha
“Just fill it in, I trust you.”It still writes everything as draft. Confirming is your job.

What the skill does, step by step

  1. Profile (Stage A): what kind of project, who built it, who it’s for, how big it is, and how deep to go.
  2. Bounded repo scan: it reads the repo within limits rather than everything.
  3. Interview (Stages B–D) in batches of 3–5 questions. It suggests answers from the code, and you confirm or correct them.
  4. Look (Stage E): typeface, scheme and ornaments, or sensible defaults.
  5. Size: it proposes Lite, Standard or Full, and hides the sections that weren’t earned.
  6. Scaffold the kit into ./scorecard, reusing an existing one without touching your text.
  7. Fill scorecard/content/*.json with provenance tags.
  8. Redaction pass plus npx scorecard-kit check.
  9. Hand-off: cd scorecard && npx scorecard-kit dev, and you take it from there in Write mode.

Full detail: SKILL.md · interview.md · references/

The CLI

The CLI is scorecard-kit (the file is bin/scorecard.js) and needs Node 20 or newer. Run it from inside the kit folder (see the npm note above) as npx scorecard-kit <command>, or as node bin/scorecard.js <command>.

CommandWhat it does
devInstalls dependencies if needed, starts Vite on 127.0.0.1 at the first free port from 5199, waits until it answers, then opens Write mode at /write. Set SCORECARD_NO_OPEN=1 to skip opening a browser
demosThe same server, opened at /demos (the five demo packs)
buildType-checks and builds a static dist/. Write mode and the save endpoint aren’t included
checkValidates every content/*.json: schemaVersion: 1, no confirmed claims written by an agent, and warnings for architecture paths it can’t find
lookOpens look-gallery.html, the gallery of schemes, typefaces and ornaments
exportExplains how to print /export to PDF, and writes a README badge snippet to EXPORT-README-SNIPPET.md
refreshPrints the refresh routine: re-run the skill, review the proposed diffs in Write → Review
helpLists the commands

How the content works

A manual is data, not code. Everything lives in content/*.json (schemaVersion: 1), so agents fill it, Write mode edits it, and the kit renders it.

FileHolds
scorecard.jsonJob, brief, outcome, features, built/borrowed, proof, next
run.jsonSetup steps, env var names, demo script
decisions.jsonDecisions and dead ends
requirements.jsonThe rubric or requirements map (never grades)
team.json · interview.jsonPeople, and your interview answers
manual.jsonParts, chapters and blocks for Standard and Full manuals
stack.json · apis.json · architecture.json · branches.jsonThe technical plates
theme.jsonScheme, colour tokens, fonts, ornaments, tone

Every claim carries its provenance:

"job": {
  "text": "Scorecard turns a project into a short descriptive site: …",
  "provenance": "draft",
  "source": "generated"
}
provenanceMeaning
confirmedYou checked it in Write → Review. Agents never set this; check fails on any confirmed claim whose source is generated.
inferredBacked by evidence: needs an evidence path or commit, e.g. "evidence": "src/auth.ts"
draftAgent text you haven’t reviewed yet

source is either generated (the agent may refresh it) or authored (yours, so the agent only proposes diffs).

Privacy and security

  • The kit stays local. It’s a Vite app with no analytics, telemetry or remote service, and it loads its fonts from public/fonts. The interview and repo scan happen inside your agent, so your agent’s own data policy applies to them.
  • Redaction comes first. Before writing content, the skill drops API keys, tokens, passwords and private URLs. Env var names like DATABASE_URL are fine; their values never are. It prefers public paths and commit SHAs as evidence.
  • Write mode stays local. npx scorecard-kit dev adds a save endpoint, /__scorecard/save, that only writes allow-listed content/*.json files and rejects path escapes. Don’t expose the dev server to the internet. npx scorecard-kit build leaves Write mode and the endpoint out.

Found a problem? See SECURITY.md to open a private advisory.

Development

npm install
npm test                          # vitest: provenance rules, generators, redaction
npm run check                     # same as npx scorecard-kit check
npm run build                     # tsc --noEmit && vite build
node scripts/sync-agent-skills.mjs

skills/scorecard/ is the canonical skill. After you edit it, run the sync script. It replaces the copies in .claude/skills/, .agents/skills/ and .github/skills/ and rewrites .github/agents/scorecard.agent.md, so don’t edit those copies by hand.

Repository layout

scorecard/
├─ skills/scorecard/        canonical Agent Skill (SKILL.md, interview.md, references/)
├─ .agents/skills/          copy for Codex and other .agents readers
├─ .claude/skills/          copy for Claude Code
├─ .github/skills/ agents/  copy and custom agent for GitHub Copilot
├─ .cursor-plugin/          Cursor plugin + marketplace manifests (uses logo.png)
├─ .claude-plugin/          Claude Code plugin + marketplace manifests, icon.png
├─ plugin.json              Agent Plugins manifest
├─ bin/scorecard.js         the CLI
├─ content/                 the manual as JSON (plus dogfood/ demo packs)
├─ src/                     React kit: pages, Write mode, generators, nouveau ornaments
├─ public/fonts/            Libretto Paléologue, Newsreader, Source Sans 3, Departure Mono
├─ public/previews/         specimen and ornament previews
├─ docs/assets/             README art: logo exports, dividers, frames, screenshots
└─ LICENSES/                font and ornament notes

Credits and licenses

  • Code: MIT © 2026 Kithe.
  • Ornaments: traced from Alphonse Mucha, Documents décoratifs (1902): plate 30 (the wild-rose medallion and seed pods in the logo), plate 33 (the lily frieze in these dividers), plate 46 (the tile-and-knot corners around the install guides) and plate 01. The plates are in the public domain. Notes on the traced components are in LICENSES/ORNAMENTS.txt.
  • Type: Libretto Paléologue (the wordmark above), drawn after Jean de Paléologue (PAL), OFL; Newsreader and Source Sans 3, SIL OFL; Departure Mono by Helena Zhang, SIL OFL. See LICENSES/FONTS.txt.
  • Logo: logo.png (with logo.svg vector source and 512 · 256 · 128 px PNGs in docs/assets/).