# 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

- **Type:** MCP server
- **Install:** `agentstack add mcp-z-m-huang-cc-proficiency`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Z-M-Huang](https://agentstack.voostack.com/s/z-m-huang)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Z-M-Huang](https://github.com/Z-M-Huang)
- **Source:** https://github.com/Z-M-Huang/cc-proficiency

## Install

```sh
agentstack add mcp-z-m-huang-cc-proficiency
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

```bash
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

```bash
$ 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

```bash
$ 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

```bash
$ 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

```bash
# 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](https://github.com/Z-M-Huang/cc-proficiency/wiki/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](https://github.com/Z-M-Huang/cc-proficiency/wiki/Gamification-Guide)** | **[游戏化攻略（中文）](https://github.com/Z-M-Huang/cc-proficiency/wiki/Gamification-Guide-zh)**

## 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](https://github.com/Z-M-Huang/cc-proficiency/wiki/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:

```bash
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:

```bash
# 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](https://github.com/Z-M-Huang/cc-proficiency/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.

```bash
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](https://github.com/Z-M-Huang)
- **Source:** [Z-M-Huang/cc-proficiency](https://github.com/Z-M-Huang/cc-proficiency)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-z-m-huang-cc-proficiency
- Seller: https://agentstack.voostack.com/s/z-m-huang
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.