Have you ever wondered: why do some projects have great code but their star count grows slowly?
Star counts only tell you the outcome — someone clicked that button. They don’t tell you the reason: is it a great README? Or a complete CI setup that makes people feel safe? Or was it simply boosted by a big influencer?
I’m building a small tool called Scorecard that breaks project maturity into nine dimensions, and each dimension only looks at objective evidence — can the API retrieve it, does the file exist, what’s the status code. This time I want to talk about how it came to be, what pitfalls I hit, and how the ninth dimension, “AI readability,” ended up embarrassing me.
Why Break It Into Nine Dimensions
Most people evaluating a project look at the README and the star count. But those two carry very little information.
The question I set for myself was: “Will a stranger star this project within 10 seconds?” Pull that question apart and you get these dimensions:
| Dimension | What question it answers |
|---|---|
| Storefront | Can I tell at a glance what this is? |
| Distribution | Can I install it — npm / brew / Docker |
| Release engineering | Are there semver tags, a CHANGELOG, a release cadence |
| Quality guardrails | Are CI, tests, and lint there |
| Community health | Are there a CONTRIBUTING and issue templates |
| Documentation | Are the quickstart and examples sufficient |
| Security | Any dependency vulnerabilities, is there a SECURITY.md |
| Metrics | Star growth rate, fork ratio, download counts |
| AI readability | Can AI crawlers read your content |
Nine dimensions, each scored 0-10, then aggregated with weights. It’s not just a score — every item comes with evidence and remediation advice.
The First Version: A CLI Tool
Scorecard started life as a command-line tool:
bun run audit webkubor/scorecard
It ran and printed a Markdown report, with each dimension listing evidence, gaps, and how many points a fix would gain.
The CLI version worked, but it had one problem: nobody wants to install a tool just to check one project.
Switching to a Web Version: Paste a URL and Go
So I built a web version: paste a GitHub URL and get a full report within seconds.
Open Scorecard for a free project audit
No login required, and public repos don’t need a token. Adding a read-only token raises the rate limit from 60 requests/hour to 5000, but you can run it without one.
The backend is Bun + Hono, the frontend is Vue. The backend is the quality-check engine, the frontend is the report panel.
What the Report Looks Like
The output isn’t a single score, it’s three things:
- Radar chart — all nine dimension scores at a glance
- Remediation list — sorted by “impact ÷ cost”, so you fix the highest-yield items first
- Markdown report — one-click copy, paste it straight to an AI and have it help you fix things
Every item in the remediation list carries an “estimated +X points after fixing”, not a vague “consider improving”.
The Ninth Dimension: AI Readability
The first eight dimensions are fairly conventional. The ninth is one I added, and the inspiration came from an embarrassing failure.
I’m building a small tool called Scorecard — wait, this one, right here. I ran it on my own project and found a problem: my official site blocked AI crawlers, and I had no idea.
The robots.txt rules on my site at the time restricted crawlers such as GPTBot and ClaudeBot. Google indexing and crawling by individual AI services are separate things: allowing a crawler does not guarantee that it will visit or cite a page.
The Failure, As It Happened
First cut: fixed robots.txt and allowed AI crawlers. Thought that was it.
The next day, while getting ready to share it, I checked again — fix one layer and there’s a second layer underneath. robots.txt allowed them, but the meta tags still carried noai. Services may interpret these signals differently, so both deserve inspection; neither alone proves what will be crawled or cited.
That experience made me realize: AI readability is something you have to actively check, it isn’t there by default.
What the Ninth Dimension Checks
| Check | What it looks at |
|---|---|
| AGENTS.md | Is there working guidance for AI in the repo root |
| llms.txt | Is there a content index for LLMs |
| robots.txt | Does the official site allow AI crawlers |
| Site meta tags | Any noai / noimageai |
All four are objective criteria — does the file exist, what’s the status code — with no model judgment needed.
Scoring Isn’t the Goal, Action Is
Scorecard’s scoring standard has four tiers:
| Score range | Meaning |
|---|---|
| 9-10 | Category leader: channel, metrics, fully automated releases |
| 6-8 | Engineering-healthy but weak on distribution: “good code nobody sees” |
| 3-5 | Usable, but storefront/release has debt |
| 0-2 | A personal practice repo |
Most personal projects land between 3-5. The code isn’t bad, the storefront just isn’t done well — README not written clearly, no CHANGELOG, no CI.
Scorecard’s core idea is: every conclusion carries evidence, every gap carries remediation advice and expected gain. Saying “the docs could be better” is useless; say “CONTRIBUTING.md is missing, adding it is estimated +0.3 points” instead.
The Engine Is Authoritative, the Skill Is Depth
Scorecard has two layers:
| Layer | What it does | Good for |
|---|---|---|
| Web engine | Objective scanning + report history | Scanning a repository, package or webpage and comparing historical reports |
| AI Skill | Deep diagnosis + fix plans | Reading the README, proposing remediation, helping you fix it |
The engine handles objective items — whatever the API can retrieve. The skill handles subjective items — things like “can the README first screen explain it in 10 seconds”, which only a model knows after reading it.
Both sides have to use the same set of dimension standards, otherwise the panel says 7 points and the skill says 4, and people don’t know who to trust.
Tech Stack
前端：Vue + Vite
后端：Bun + Hono
API：GitHub REST API
部署：Bun server 托管 dist/
The current service uses local SQLite for audit history and operation logs, with cached results; checking public projects does not require a login. The design principle is still if you can leave it out, leave it out — every dependency is a liability.
What You Can Try
Open scorecard.supercli.site and paste a repo link you’re familiar with. When it finishes you’ll see:
- Which dimensions your project scores high on
- Which dimensions have gaps
- What to fix first for the biggest gain
If you think a dimension is unreasonable, or something is missing, feel free to open an issue. The scoring standard isn’t something I decide on my own.
