GitHub - Z-M-Huang/cc-proficiency: Generate a proficiency badge for your Claude Code usage — rule-based scoring engine with 53 pattern-matching rules across 5 CCA-aligned domains, auto-updating SVG badge via GitHub Gist

Generate a proficiency badge for your Claude Code usage, aligned with the 5 Claude Certified Architect exam domains.

Install  ·  Usage  ·  Embed  ·  AI Grading  ·  Scoring  ·  Privacy  ·  Localization  ·  English · 中文 · Español · Français · 日本語 · 한국어

What it does

Analyzes your Claude Code session transcripts locally with a rule-based engine, scoring usage patterns across 5 domains. Optionally adds AI-powered grading across 5 outcome-focused domains using Claude's /insights data.

Also shows 8 feature mini-bars (Hooks, Plugins, Skills, MCP, Agents, Plan, Memory, Rules) as a heatmap row.

Click to see animated version

Click to see animated version

Disclaimer: This is an unofficial usage estimate, not an actual Anthropic certification score. Not affiliated with or endorsed by Anthropic.

Install

npm install -g cc-proficiency
cc-proficiency init

init will:

1. Detect your GitHub username (via gh CLI)
2. Inject a Stop hook into ~/.claude/settings.json
3. Create a private GitHub Gist for your badge (if gh is authenticated)

If gh is not installed or not authenticated, the badge is saved locally to ~/.cc-proficiency/cc-proficiency.svg.

First-time setup

$ cc-proficiency init

Initializing cc-proficiency...

  GitHub user: @yourname
  Creating private Gist...
  Gist created: a1b2c3d4e5f6

  Add to your README:
  ![CC Proficiency](https://gist.githubusercontent.com/yourname/a1b2c3d4e5f6/raw/cc-proficiency.svg)

  ✓ Configuration saved to /home/you/.cc-proficiency
  ✓ Hook injected into ~/.claude/settings.json

  Run 'cc-proficiency analyze' to compute your first scores.

Analyze your proficiency

$ cc-proficiency analyze --full

Running full analysis...
  Claude Code Proficiency — @yourname
  ────────────────────────────────────────
  CC Mastery     ███████████████░░░░░   77  ●
  Tool & MCP     ███████████████████░   96  ◐
  Agentic        ██████████████░░░░░░   69  ◐
  Prompt Craft   ████████████████░░░░   81  ◐
  Context Mgmt   ████████████████████  100  ●
  ────────────────────────────────────────
  Hooks   Edit (1411x), Bash (928x), Write (542x) +5
  Skills  dev-buddy-once (5x), chatroom (2x) +5
  Tools   Read 2046 · Bash 1045 · Write 379 · Edit 367 (+12 more)
  ────────────────────────────────────────
  139 sessions · 4 projects

Get improvement tips

$ cc-proficiency explain

  Claude Code Proficiency — @yourname

  Strengths:
    Context Mgmt   100/100
    Tool & MCP      96/100
    Prompt Craft    81/100
    CC Mastery      77/100
    Agentic         69/100

  Areas to Improve:
    Agentic (69/100)
       → Try more CC features: subagents, MCP servers, skills,
         plan mode, worktrees
    CC Mastery (77/100)
       → Enhance CLAUDE.md with imports, add hooks with matchers,
         create rules files

  Feature Usage:
    Hooks:  Edit (1411x), Bash (928x), Write (542x) +5
    Skills: dev-buddy-once (5x), chatroom (2x) +5
    Tools:  Read (2046), Bash (1045), Write (379) +12 more
    Flags:  ✓ Plan  ✓ Memory  ✗ Rules

  139 sessions · 4 projects

Generate and push your badge

# Save badge locally
$ cc-proficiency badge --output my-badge.svg
Badge written to my-badge.svg

# Or push directly to your Gist
$ cc-proficiency push
✓ Badge pushed to Gist
  https://gist.githubusercontent.com/yourname/a1b2c3d4e5f6/raw/cc-proficiency.svg

Automatic updates (zero effort)

After init, a Stop hook runs automatically after every Claude Code session:

You use Claude Code normally
  → Session ends
  → Hook queues the session (<1s, invisible to you)
  → Background process analyzes + updates your badge
  → Your README badge reflects your latest scores

No manual steps needed after setup.

Without GitHub CLI

If you don't have gh installed or prefer local-only mode:

$ cc-proficiency init

  ⚠ GitHub CLI not authenticated.
  Badge will be saved locally to: ~/.cc-proficiency/cc-proficiency.svg
  To enable auto-upload: gh auth login && cc-proficiency init

$ cc-proficiency analyze --full
$ cc-proficiency badge --output badge.svg

Embed in your README

After running cc-proficiency init, add this to your README:

<!-- Static badge -->
![Claude Code Proficiency](https://gist.githubusercontent.com/<username>/<gist-id>/raw/cc-proficiency.svg)

<!-- Animated badge (click to view) -->
[Click to see animated version](https://gist.githubusercontent.com/<username>/<gist-id>/raw/cc-proficiency-animated.svg)

Both badges update automatically after each Claude Code session (via the Stop hook).

Progressive Badge

The badge adapts based on how much data is available:

Improve your scores

The Gamification Guide covers:

• First day through expert-level progression path
• Tips for each of the 5 domains
• How to unlock all 18 achievements (including 3 AI achievements)
• What drives each feature mini-bar from 0 to 100
• Streak system and leaderboard

Gamification Guide | 游戏化攻略（中文）

AI Grading

In addition to the rule-based engine, cc-proficiency offers AI-powered grading that evaluates your usage patterns across 5 outcome-focused domains using Claude's /insights data (facets + session metadata).

AI Domains

Each domain is scored 0–100% with levels: Novice (<34%), Proficient (34–66%), Expert (67%+).

How it works

1. Reads /insights facets and session-meta from ~/.claude/usage-data/
2. Precomputes stats locally (outcome rates, friction trends, tool distributions)
3. Sends stats + rubric to claude -p (via stdin — no data leaves your machine except to Claude API)
4. AI returns only per-criterion scores (1–5); totals, levels, and achievements are computed locally
5. Renders an animated SVG badge with "AI Graded" indicator

The grading rubric is stored as editable markdown files in docs/ai-grading/ — you can review and customize the criteria.

Usage

# Enable AI grading
cc-proficiency config aiGrading true

# Run AI grading (requires Claude CLI ≥ 2.1.0)
cc-proficiency ai-grade                  # uses sonnet by default
cc-proficiency ai-grade --model opus     # use a specific model
cc-proficiency ai-grade --full           # force re-grade (ignore cache)

Results are cached based on evidence hash — re-running without new data returns the cached result instantly.

Auto-trigger

When aiGrading is enabled, the process command automatically triggers AI grading weekly (after releasing the queue lock). No manual steps needed.

Phase system

AI Achievements

Three achievements unlock based on your /insights data (deterministic, not AI judgment):

Privacy

AI grading sends precomputed statistics to Claude, not raw transcripts. Project paths are sanitized to slugs. The report.html narrative is excluded to avoid AI grading AI-generated text.

How scoring works

Rule-based engine

cc-proficiency uses a pattern-matching rule engine with ~55 rules across 5 domains instead of counting tool calls. Each rule detects a specific behavior pattern and awards points by tier:

5 Domain Bars

8 Feature Mini-Bars

Below the domain bars, a heatmap row shows depth per feature:

Hooks · Plugins · Skills · MCP · Agents · Plan · Memory · Rules

Each mini-bar uses depth-based scoring with logarithmic curves that reflect actual usage, not just whether you've tried a feature once. Having hooks configured gets you ~30; firing them across hundreds of sessions gets you closer to 100. See the Gamification Guide for details.

Bucket aggregation with caps

Scores are not raw sums. Each domain has capped buckets:

This means:

• Fresh installs can score up to ~25 raw config points per domain (boosted to ~50 during calibration via 2.0x scaling)
• After calibration (10+ sessions) config alone caps at ~25 per domain; transcript evidence drives the rest
• Anti-patterns are capped, so a few bad sessions don't destroy your score

Phase-aware weighting

Config evidence is weighted more heavily during calibration, less as transcripts accumulate:

Anti-gaming

• Rules fire per-session with caps; repeating the same tool 100x doesn't help
• Anti-pattern rules deduct points for bad habits (shotgun parallel calls, unstructured walls of text)
• Each rule has maxPerSession; investigation chains cap at 3 per session
• Config scores are capped at 25, so you can't max a domain by just installing plugins

Privacy

Localization

cc-proficiency supports 6 languages: English, 中文, Español, Français, 日本語, 한국어.

Your locale is auto-detected from system environment on init. To change it:

cc-proficiency config locale zh-CN   # Chinese
cc-proficiency config locale es       # Spanish
cc-proficiency config locale fr       # French
cc-proficiency config locale ja       # Japanese
cc-proficiency config locale ko       # Korean
cc-proficiency config locale en       # English (default)

SVG badges automatically display in the viewer's preferred language using SVG <switch> elements with systemLanguage attributes. All 6 languages are embedded in a single SVG file -- no need to generate separate badges per locale.

Contributing Translations

To add a new language, copy src/i18n/locales/en.ts to src/i18n/locales/<code>.ts, translate all strings, and register the locale in src/i18n/index.ts.

Commands

Community Leaderboard

Opt into the community leaderboard to compare your proficiency with other Claude Code users:

# Join the leaderboard (creates a separate public profile)
$ cc-proficiency share

# View rankings
$ cc-proficiency leaderboard

# Leave the leaderboard
$ cc-proficiency share --remove

Your private data (session details, project names, file paths) is never shared. Only scores, streak, and achievement count are public. See the wiki for full documentation.

Architecture

Stop hook fires (< 1s)
  → Writes session path to ~/.cc-proficiency/queue.jsonl
  → Spawns `cc-proficiency process` as detached child

cc-proficiency process
  → Acquires queue.lock (stale >60s → break)
  → Deduplicates by session_id
  → Parses transcripts (streaming JSONL, per-line error handling)
  → Extracts signals → computes scores → renders SVG
  → Pushes to Gist (if configured) or saves locally
  → Atomically rotates queue

Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change.

git clone https://github.com/Z-M-Huang/cc-proficiency.git
cd cc-proficiency
npm install
npm test              # 433 tests
npm run build         # compile to dist/
npm run typecheck     # tsc --noEmit
npm run lint          # eslint
npm run check         # typecheck + lint + test

License

Apache 2.0

_{Built with Claude Code. Not affiliated with or endorsed by Anthropic.}