Cc Proficiency

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](#ai-grading) across 5 outcome-focused domains using Claude's /insights data.

| Domain | Weight | What it measures | |--------|--------|-----------------| | CC Mastery | 20% | CLAUDE.md, hooks, plugins, plan mode, skills, rules | | Tool & MCP | 20% | Tool chains, MCP servers, LSP, selective edits | | Agentic | 20% | Subagents, parallel execution, worktrees, task management | | Prompt Craft | 20% | Structured prompts, code blocks, error traces, refinement | | Context Mgmt | 20% | Cross-session memory, CLAUDE.md updates, sustained projects |

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.

Usage

First-time setup

$ cc-proficiency init

Initializing cc-proficiency...

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

  Add to your README:
  

  ✓ 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 (//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:

| Phase | Sessions | What's shown | |-------|----------|-------------| | Calibrating | 0–2 | Setup checklist + progress toward first scoring | | Early Results | 3–9 | 5 domain bars + 8 feature mini-bars (low-confidence indicators ○) | | Full Badge | 10+ | Full domain bars, feature heatmap, confidence dots (● ◐ ○) |

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

| Domain | What it measures | |--------|-----------------| | Goal Achievement | Goal clarity, achievement rate, complexity progression, session purposefulness | | Collaboration Quality | Friction recovery, direction clarity, feedback quality, outcome satisfaction | | Workflow Mastery | Session strategy diversity, output-to-effort ratio, multi-session coordination | | Growth & Learning | Friction trajectory, outcome trajectory, capability expansion, resilience | | Verification & Quality | Outcome reliability, error handling, iterative refinement, course-correction |

Each domain is scored 0–100% with levels: Novice (50% error rate |

5 Domain Bars

| Domain | What it measures | |--------|-----------------| | CC Mastery | CLAUDE.md structure, hooks with matchers, plugins, plan mode, skills, rules files | | Tool & MCP | Investigation chains, Read-before-Edit, tool variety, MCP server usage, LSP, selective edits | | Agentic | Subagent type variety, parallel agents, background runs, worktrees, task management | | Prompt Craft | Structured requests, code blocks, error traces, file references, iterative refinement | | Context Mgmt | Active memory files, CLAUDE.md updates, sustained projects, session depth |

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:

| Bucket | Max Points | Source | |--------|-----------|--------| | Config | 25 pts | Config-based rules (CLAUDE.md, hooks, plugins; available immediately) | | Behavior | 75 pts | Behavior-based rules (transcript patterns; grow over time) | | Penalty | -15 pts max | Anti-pattern deductions |

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:

| Phase | Sessions | Config scale | Behavior scale | |-------|----------|-------------|---------------| | Calibrating | 0–2 | 2.0× | 0.8× | | Early | 3–9 | 1.5× | 1.0× | | Full | 10+ | 1.0× | 1.15× |

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

| Concern | How it's handled | |---------|-----------------| | Data location | All analysis happens locally on your machine | | What's stored | Only aggregate counts, ratios, and boolean flags (no file paths, code, or prompts) | | Gist visibility | Private by default (secret URL, not listed on your profile) | | Offline mode | Works fully offline without gh CLI (local-only mode) | | CI/CD | Non-interactive sessions are automatically detected and excluded |

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 ` 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/.ts, translate all strings, and register the locale in src/i18n/index.ts.

Commands

| Command | Description | |---------|-------------| | cc-proficiency init | Set up hooks and Gist | | cc-proficiency analyze [--full] | Parse sessions and compute scores | | cc-proficiency process | Process queued sessions from hook | | cc-proficiency badge [--output ] | Generate SVG badge | | cc-proficiency push | Upload badge to Gist | | cc-proficiency explain | Show score drivers and tips | | cc-proficiency achievements | View achievement progress | | cc-proficiency status | Show hook activity, queue, and config | | cc-proficiency config [key] [value] | View/set configuration | | cc-proficiency ai-grade [--model m] [--full] | AI-powered proficiency grading | | cc-proficiency share [--remove] | Join or leave the community leaderboard | | cc-proficiency leaderboard | View community rankings | | cc-proficiency update | Update to the latest version | | cc-proficiency uninstall | Remove hooks and clean up |

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 (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](LICENSE)

---

Built with Claude Code. Not affiliated with or endorsed by Anthropic.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Z-M-Huang
• Source: Z-M-Huang/cc-proficiency
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.