Assess

Claude Code Setup Assessment

Analyze the user's Claude Code configuration, produce a scored JSON report, and display the full results in the terminal.

This skill is read-only. It collects and evaluates configuration files. It does NOT create or modify any files other than saving the JSON report.

Workflow

Phase 1: Collect Configuration

Read all relevant configuration files. Run these checks in parallel where possible:

# Project-level files
ls -la ./CLAUDE.md ./.claude/CLAUDE.md ./.claude/settings.json ./.claude/settings.local.json ./.mcp.json 2>/dev/null

# User-level files
ls -la ~/.claude/CLAUDE.md ~/.claude/settings.json 2>/dev/null

# Directories (project + user)
ls -la ./.claude/skills/ ./.claude/agents/ ./.claude/rules/ 2>/dev/null
ls -la ~/.claude/skills/ ~/.claude/agents/ 2>/dev/null

# Plugin-sourced agents and skills (IMPORTANT — these count too!)
ls -la ~/.claude/plugins/cache/ 2>/dev/null
# For each plugin, check for agents/ and skills/ subdirectories
find ~/.claude/plugins/cache -name "AGENT.md" -o -name "SKILL.md" 2>/dev/null | head -50

# IDE markers
ls -la ./.vscode/ ./.idea/ 2>/dev/null

# Advanced
ls -la ./.claude/worktrees/ 2>/dev/null

For each file/directory that exists, read its contents. Specifically:

Config Surface	What to Read
Project CLAUDE.md	./CLAUDE.md or ./.claude/CLAUDE.md — read full content
User CLAUDE.md	~/.claude/CLAUDE.md — read full content
Project settings	./.claude/settings.json — parse JSON, extract permissions, hooks. Note: defaultMode and additionalDirectories are nested INSIDE permissions{}, not at top level.
User settings	~/.claude/settings.json — parse JSON, extract permissions, hooks. Same nesting applies.
MCP config	./.mcp.json — count servers, check types
User MCP config	~/.claude.json — check mcpServers section
Skills	./.claude/skills/*/SKILL.md — read frontmatter of each
User skills	~/.claude/skills/*/SKILL.md — read frontmatter of each
Plugin skills	~/.claude/plugins/cache/**/skills/*/SKILL.md — skills from installed plugins
Agents	./.claude/agents/*/AGENT.md or ./.claude/agents/*.md — read frontmatter of each
User agents	~/.claude/agents/*/AGENT.md — read frontmatter
Plugin agents	~/.claude/plugins/cache/**/agents/*/AGENT.md or ~/.claude/plugins/cache/**/agents/*.md — agents from installed plugins
Rules	./.claude/rules/* — list files, check for paths: in frontmatter
Memory	Find the memory directory for the current project under ~/.claude/projects/
Plugins	Check ~/.claude/plugins/ for installed plugins
Plugin hooks	~/.claude/plugins/cache/**/hooks/hooks.json — plugin-provided hooks (nested under {"hooks": {...}})

Phase 2: Evaluate Against Rubric

Read the scoring rubric at references/scoring-rubric.md.

For each of the 12 categories, evaluate every check and record:

• pass/fail status
• points earned (0 if fail, check's point value if pass)
• detail — brief explanation of what was found
• recommendation — if fail, get the recommendation from references/best-practices.md

Phase 3: Compute Scores

For each category:

1. Sum the points of passing checks
2. The category score is the sum (already 0-100 scale since max raw points = 100)

For the overall score:

1. Multiply each category score by its weight
2. Sum the weighted scores
3. Divide by 100 (weights sum to 100)
4. Round to nearest integer

Determine the letter grade and maturity level per the rubric tables.

Phase 4: Generate Top Recommendations

From all failing checks across all categories:

1. Sort by category weight (higher weight = higher priority)
2. Within each weight tier, sort by the check's point value (higher points = higher impact)
3. Select the top 5 recommendations
4. For each, include the category name, specific recommendation text, and impact level (high/medium/low based on weight)

Phase 5: Save JSON Report

Save the full assessment as .claude-assess-report.json in the project root:

{
  "version": "1.0",
  "generatedAt": "[ISO timestamp]",
  "generatedBy": "cc-assess/1.0.0",
  "overall": {
    "score": [0-100],
    "grade": "[letter grade]",
    "tier": "[maturity level]",
    "totalChecks": [count],
    "passingChecks": [count]
  },
  "categories": [
    {
      "id": "[category-id]",
      "name": "[Category Name]",
      "weight": [weight],
      "score": [0-100],
      "grade": "[letter grade]",
      "checks": [
        {
          "id": "[check ID]",
          "name": "[check name]",
          "pass": true/false,
          "points": [earned],
          "maxPoints": [possible],
          "detail": "[what was found]",
          "recommendation": "[if fail, action to take]"
        }
      ]
    }
  ],
  "topRecommendations": [
    {
      "priority": [1-5],
      "category": "[category name]",
      "checkId": "[check ID]",
      "message": "[recommendation]",
      "impact": "high|medium|low"
    }
  ]
}

Phase 6: Display Full Results in Terminal

After saving the JSON report, display the complete assessment results directly in the terminal. The terminal IS the primary experience.

Display this output structure:

╔══════════════════════════════════════════════════════════════╗
║              CLAUDE CODE SETUP ASSESSMENT                    ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║   Score: XX/100  |  Grade: X+  |  Level: [Maturity Level]   ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

## Category Breakdown

| Category             | Score | Grade | Bar                |
|----------------------|-------|-------|--------------------|
| CLAUDE.md (25%)      | 85    | B     | ████████░░         |
| Settings (20%)       | 70    | C-    | ███████░░░         |
| MCP Servers (15%)    | 100   | A+    | ██████████         |
| Security (12%)       | 45    | F     | ████░░░░░░         |
| Hooks (8%)           | 60    | D-    | ██████░░░░         |
| Skills (5%)          | 80    | B-    | ████████░░         |
| Agents (5%)          | 0     | F     | ░░░░░░░░░░         |
| Memory (4%)          | 50    | F     | █████░░░░░         |
| Rules (2%)           | 0     | F     | ░░░░░░░░░░         |
| Plugins (2%)         | 40    | F     | ████░░░░░░         |
| IDE (1%)             | 40    | F     | ████░░░░░░         |
| Advanced (1%)        | 25    | F     | ██░░░░░░░░         |

The bar uses 10 characters: █ for filled (each = 10 points), ░ for empty. Round to nearest block.

## Top Recommendations

1. **[Category Name]** — [Specific recommendation from best-practices.md]
2. **[Category Name]** — [Specific recommendation]
3. **[Category Name]** — [Specific recommendation]
4. **[Category Name]** — [Specific recommendation]
5. **[Category Name]** — [Specific recommendation]

---
Report saved to .claude-assess-report.json
Interactive version: https://claude-code-assess.web.app (paste report JSON)
Built by Deway (deway.ai)

Rules:

• Show ALL 12 categories with scores, grades, and visual bars
• Show the top 5 recommendations with actionable detail
• Keep it clean and scannable — the user should understand their setup at a glance
• Still mention the web app at the bottom as an optional interactive view, but don't push it

Output Guidelines

• Be factual and specific in check details within the JSON. Say "Found at ./.claude/CLAUDE.md (42 lines)" not "CLAUDE.md exists".
• For failing checks, give the specific recommendation from best-practices.md, not generic advice.
• If a file is missing, the detail should say "Not found" and the recommendation should say exactly what to create and where.
• The terminal output IS the primary experience. Show everything the user needs to understand and improve their setup.
• End with the "Built by Deway" attribution line.