Skill Crossroads

New-user guide

Five journeys from first scan to shipped badge.

Skill Crossroads grades Claude Code artifacts — skills, subagents, slash commands, MCP configs, and plugins — against an evidence-cited rubric, then points you one of three ways: ship, fix, or rethink. These are the five things new users actually do, in the order they usually do them. Every screenshot below is the real product.

Ship — grade A/BFix — grade C/DRethink — grade F
  1. 1Scan any public repo — free, no signup30 seconds
  2. 2Read the scorecard and fix from receipts10 minutes
  3. 3Put the live badge in your README2 minutes
  4. 4Paste-to-scan when there's no repo yet1 minute
  5. 5Gate pull requests in CIone workflow file
1First contact

Scan any public repo — free, no signup.

The homepage is the product. Type any GitHub owner/repo that contains Claude Code artifacts and you get a graded scorecard for everything in it — yours or anyone's, before you install it.

What you do

  1. Go to skillcrossroads.com
  2. Enter owner/repo (try anthropics/skills)
  3. Press Scan

What you get

  • A letter grade per artifact and for the repo
  • Six rubric categories, weighted and scored
  • No account, no key, no install — deterministic checks run free
# the same journey in the terminal — no clone needed
npx skillcrossroads anthropics/skills
Skill Crossroads homepage: headline 'Every skill hits a crossroads before you ship it', a scan form accepting owner/repo, and the ship / fix / rethink signpost
2The core loop

Read the scorecard — then fix from receipts, not vibes.

Every finding is cited to a file and line, with the evidence quoted and a concrete fix. The “Top fixes” list is ranked by grade impact, so ten minutes of work goes where it moves the score most. Each check links to its own reference page.

What you do

  1. Open the top fix — it names the exact file:line
  2. Apply the smallest change that resolves it
  3. Re-scan; repeat until the grade stops improving

What you get

  • Grade dial + six category bars
  • Evidence-cited findings with fix guidance
  • With an API key, --suggest proposes the fixes for you — never auto-applies
# real output — three skills, after one fix pass
$ npx skillcrossroads ./skills

  A+   97.2  meeting-notes-to-actions
  A    96.7  summarize-document
  A      96  research-synthesis

  average 96.6/100 across 3 skills
A live scorecard: overall grade A 96.3, six category bars, and a Top Fixes list where each finding cites SKILL.md line numbers with quoted evidence and a fix

This scorecard is live: skillcrossroads.com/s/sgharlow/skillcrossroads/skill

3Show your work

Put the live badge in your README.

One command inserts an always-fresh badge under your README's title — it re-scans on its own, links to your public scorecard, and tells everyone who lands on your repo that the quality claim is checkable. The CLI never commits; you review the diff and push.

What you do

  1. In your repo: npx skillcrossroads init
  2. Review the one-line README diff
  3. Commit and push

What you get

  • A live grade badge that stays current with no further action
  • A click-through to your evidence-cited scorecard
  • The badge is how good work gets discovered — this is the loop
$ npx skillcrossroads init --dry-run   # preview first
$ npx skillcrossroads init             # inserts the badge under your H1
A GitHub README titled 'Top 100 Claude Code Recipes' with the Skill Crossroads A+ badge rendered directly under the heading
4No repo? no problem

Paste, scan, fix — before the repo exists.

Drafting a skill in an editor and not on GitHub yet? Paste the SKILL.md (or a subagent / slash-command file) and get the scorecard instantly. Pasted content is graded in memory and never stored — see how we handle your code.

What you do

  1. Open skillcrossroads.com/paste
  2. Paste the file, pick the artifact kind
  3. Press Scan it

What you get

  • The same evidence-cited scorecard, instantly
  • Deterministic checks — free, keyless
  • Nothing recorded: paste-to-scan keeps no copy
The paste-to-scan page: 'Paste, scan, fix.' with a file-contents textarea, an artifact-kind selector, and a Scan It button
5Keep it good

Gate pull requests in CI.

The GitHub Action scans on every PR, posts the scorecard as a comment (updated in place, with inline file:line annotations), and can fail the build when any artifact grades below your bar. Quality stops regressing the day you add one workflow file — and the Action is free.

What you do

  1. Add the workflow below to .github/workflows/
  2. Open a PR that touches a skill
  3. Read the scorecard comment; merge when green

What you get

  • A scorecard comment on every PR
  • Inline annotations at the exact lines
  • A hard gate: min-grade fails PRs below the bar
# .github/workflows/crossroads.yml
- uses: sgharlow/skillcrossroads/apps/action@v1
  with:
    path: ./skills
    min-grade: B
A merged pull request where the Skill Crossroads Action posted a scorecard comment: overall 100/100, per-category table, 'Clean scan — no warnings or failures', 3 checks passed

A real PR, gated and merged: github.com/sgharlow/skillcrossroads/pull/1