# Skill Crossroads

> Evidence-cited grading tool for Claude Code skills, agents, slash commands, MCP configs, and plugins — points you to ship, fix, or rethink before you publish.

Skill Crossroads grades Claude Code artifacts — skills, subagents, slash commands, `.mcp.json` configs, and plugins — against a versioned, evidence-based rubric and returns a letter grade, an embeddable badge, and a ranked fix list where every finding is cited to a specific file and line. It is available as an npm CLI (`npx skillcrossroads`), a hosted web app at skillcrossroads.com, and a GitHub Action for CI gating. The project is MIT-licensed and open source on GitHub under the `sgharlow/skillcrossroads` repository.

## What It Is

Skill Crossroads is a code-quality grader purpose-built for the Claude Code ecosystem. Where Anthropic's own `skill-creator` tool measures whether a skill lifts task success, Skill Crossroads — per the README — grades "craftsmanship and safety": is the artifact well-built, discoverable, and safe to ship? The tool runs 26 deterministic checks across six weighted rubric categories, plus optional LLM-assisted checks (bring your own Anthropic API key). The result is one of three verdicts: **Ship** (A/B), **Fix** (C/D), or **Rethink** (F).

## The Six-Category Rubric

The scoring rubric is versioned (currently v1.2) and covers:

- **Correctness & Structure** (20%) — valid frontmatter, resolvable references, manifest validity
- **Triggering & Discoverability** (22%) — will the model actually invoke it? The README identifies this as the #1 real-world skill failure
- **Clarity & Instruction Quality** (18%) — unambiguous, contradiction-free, properly phrased instructions
- **Token & Context Cost** (15%) — body budget, progressive disclosure, per-invocation cost estimate
- **Safety & Security** (15%) — hardcoded secrets, over-broad tool grants, MCP server pinning, hooks sweep
- **Verifiability & Maintainability** (10%) — evals/tests present, version hygiene

Deterministic checks always run without an API key. A key upgrades the Triggering check to an LLM verdict (the README reports 92.9% accuracy against a hand-labeled 14-skill set) and enables fix suggestions via `--suggest`.

## How the Workflow Works

Users can scan artifacts in several ways: point the CLI at a local path or folder, paste a `SKILL.md` directly at skillcrossroads.com/paste (content graded in memory, never stored), or scan any public GitHub repo by URL without cloning. The output surfaces include a terminal scorecard, self-contained HTML report, SVG badge, Markdown summary, JSON, and GitHub PR annotations. The `init` command inserts an always-fresh hosted badge under a README's H1. The GitHub Action posts a scorecard comment on every PR and can fail the build when any artifact grades below a configurable minimum.

## Artifact Coverage

The tool auto-detects artifact kind from the file path and applies kind-aware grading rules:

- **Skills** — full six-category rubric including progressive disclosure and supporting-file reference checks
- **Subagents** (`.claude/agents/*.md`) — checks for typo'd `model:` values and the inherits-every-tool trap
- **Slash commands** (`.claude/commands/*.md`) — Triggering is marked n/a (commands are explicitly invoked); checks `$ARGUMENTS`/`argument-hint` agreement
- **MCP configs** (`.mcp.json`) — version-pinned `npx` packages, TLS on remote transports, secret scan; `--mcp-live` spawns stdio servers and grades live tool descriptions
- **Plugins** (`.claude-plugin/plugin.json`) — manifest validity, component path resolution, hooks destructive-command sweep, roll-up grade across all contained artifacts

## Update: Rubric v1.2 and Production Status

The README documents rubric v1.2 (dated 2026-07), which added TRIGGER-05 (invocation-flag consistency), TOKEN-04 (recurring per-invocation cost estimate), CLARITY-02 (internal contradictions, LLM-assisted), and VERIFY-03 (maintenance hygiene, informational). The prior v1.1 added deterministic Triggering and Verifiability checks so that keyless skill scans score all six categories. The hosted app is described in the README as "live in production" — public scorecards, always-fresh badges, a public gallery leaderboard, score history trends, and the published State of Claude Code Skills report are all live at skillcrossroads.com. The CLI is published on npm as `skillcrossroads`. The README notes that the Stripe Pro tier and GitHub sign-in are "owner-dogfooded but not yet customer-proven."

## Features
- Evidence-cited grading with file and line citations
- Six-category weighted rubric (v1.2)
- Ship / Fix / Rethink verdict system
- 26 deterministic checks across skills, agents, commands, MCP configs, and plugins
- LLM-assisted triggering check (BYOK Anthropic key)
- Fix suggestions via --suggest flag (proposals only, never auto-applies)
- Embeddable SVG badge with always-fresh hosted variant
- GitHub Action for CI PR gating with scorecard comments
- Batch scanning of public GitHub repos without cloning
- Paste-to-scan for files not yet on GitHub
- MCP config grading including live server checks (--mcp-live)
- Plugin manifest and hooks safety sweep
- Score history and trend charts
- Public gallery leaderboard
- Ecosystem percentile ranking
- JSON, Markdown, HTML, and annotation output formats
- Configurable .skillcrossroads.json for CI suppression and grade gates
- init command to insert badge into README

## Integrations
Claude Code, GitHub, GitHub Actions, Anthropic API, Stripe, npm, MCP (Model Context Protocol)

## Platforms
CLI, WEB, API, BROWSER_EXTENSION

## Pricing
Open Source, Free tier available

## Version
rubric v1.2

## Links
- Website: https://skillcrossroads.com
- Documentation: https://skillcrossroads.com/docs/checks
- Repository: https://github.com/sgharlow/skillcrossroads
- EveryDev.ai: https://www.everydev.ai/tools/skill-crossroads