Skip to main content
skill CX Codex

System Diagnostician — Claude Code skill: what it does, how to install

System Diagnostician runs automated repository diagnostics, spots structural and security gaps, and produces an action plan ranked by impact and effort.

MIT 138 installs ★ 39 updated 2025-12-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daffy0208/ai-dev-standards --skill system-diagnostician -a claude-code
Open on GitHub

What System Diagnostician does

The skill inspects project structure using a pipeline of Bash scripts, Python, and the Codex CLI. It detects project frameworks (Node.js, Python, React, Next.js, or Express), counts source and test files, inspects package manifests, and verifies documentation alongside CI configurations.

Once raw statistics are stored, Codex scores repository health from 0 to 1 across eight key areas: testing, documentation, security, performance, code quality, architecture, dependencies, and CI/CD pipelines. If a capability-graph.json path is provided, it matches found issues against missing architectural capabilities.

Execution relies strictly on local tools: bash, jq, python3, and an authenticated codex binary must be available in your environment, otherwise the pipeline fails during the initial discovery step.

What it helps with

  • detect security risks and unvalidated user inputs
  • score repository health across eight structural dimensions
  • identify architectural anti-patterns and missing automated tests
  • prioritize remediation actions by comparing impact against required effort

Example prompts for the agent

  • Run a full repository health diagnostic focused on security and testing.
  • Analyze project gaps against capability-graph.json and generate an action plan.
  • Gather structure metrics including dependency counts and CI pipeline status.

How to install System Diagnostician

1Skills CLI (Vercel)

npx skills add daffy0208/ai-dev-standards --skill system-diagnostician -a claude-code

2Manually: put the files in place

~/.claude/skills/system-diagnostician/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/system-diagnostician/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about System Diagnostician

How to install System Diagnostician in Claude Code?

Run npx skills add daffy0208/ai-dev-standards --skill system-diagnostician -a claude-code in your terminal.

What does System Diagnostician do?

It discovers repo metrics, evaluates health across eight technical dimensions via Codex, and outputs a prioritized recommendation plan.

What local dependencies are required?

The workflow requires bash, jq, python3, and the codex CLI present in your system path.

Source text

SKILL.md · MIT
---
name: System Diagnostician
description: Performs Codex-assisted project health diagnostics, identifies capability gaps, and produces prioritized improvement plans.
version: 1.0.0
category: analysis
tags:
  - diagnostics
  - capability-planning
  - project-health
---

# System Diagnostician

**Analyze project health and recommend capabilities using Codex-powered system understanding**

## Purpose

Performs comprehensive project health analysis to diagnose issues, identify missing capabilities, and recommend improvements. Uses Codex to understand project structure, detect anti-patterns, analyze dependencies, and suggest optimal capability additions based on project goals.

## When to Use

- New project onboarding: "What does this project need?"
- Health checks: "Is this project following best practices?"
- Gap analysis: "What's missing to achieve X?"
- Performance audits: "Why is this slow?"
- Security audits: "What security risks exist?"
- Dependency audits: "Are dependencies up to date and safe?"

## Key Capabilities

- **Project Structure Analysis**: Understands project type, framework, architecture
- **Capability Gap Detection**: Identifies missing or incomplete capabilities
- **Health Scoring**: Quantifies project health across multiple dimensions
- **Recommendation Engine**: Suggests capabilities with impact/effort estimates
- **Dependency Analysis**: Checks for outdated, vulnerable, or unnecessary dependencies
- **Anti-Pattern Detection**: Identifies code smells and architectural issues
- **Prioritized Action Plan**: Orders recommendations by impact and effort

## Inputs

```yaml
inputs:
  project_path: string # Path to project directory
  capability_graph: string # Path to capability-graph.json
  focus_areas: array # Optional: ["security", "performance", "testing"]
  include_metrics: boolean # Include detailed metrics (default: false)
```

## Process

### Step 1: Project Discovery

```bash
#!/bin/bash
# Analyze project structure

PROJECT_PATH="${1:-.}"
cd "$PROJECT_PATH"

echo "Discovering project structure..."

# Detect project type
PROJECT_TYPE="unknown"
FRAMEWORK="unknown"

if [ -f "package.json" ]; then
  PROJECT_TYPE="nodejs"

  # Detect framework
  if grep -q "\"next\"" package.json; then
    FRAMEWORK="nextjs"
  elif grep -q "\"react\"" package.json; then
    FRAMEWORK="react"
  elif grep -q "\"express\"" package.json; then
    FRAMEWORK="express"
  fi
elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
  PROJECT_TYPE="python"
fi

# Gather file statistics
FILE_COUNT=$(find . -type f -not -path "./node_modules/*" -not -path "./.git/*" | wc -l)
CODE_FILES=$(find . -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.py" | wc -l)
TEST_FILES=$(find . -name "*.test.*" -o -name "*.spec.*" | wc -l)

# Check for common directories
HAS_TESTS=$([ -d "tests" ] || [ -d "test" ] || [ -d "__tests__" ] && echo "true" || echo "false")
HAS_DOCS=$([ -f "README.md" ] && echo "true" || echo "false")
HAS_CI=$([ -d ".github/workflows" ] || [ -f ".gitlab-ci.yml" ] && echo "true" || echo "false")

# Package.json analysis
if [ -f "package.json" ]; then
  DEPENDENCIES=$(jq -r '.dependencies // {} | keys | length' package.json)
  DEV_DEPENDENCIES=$(jq -r '.devDependencies // {} | keys | length' package.json)
  SCRIPTS=$(jq -r '.scripts // {} | keys | length' package.json)
fi

# Generate project state
cat > /tmp/project-state.json <<EOF
{
  "project_type": "$PROJECT_TYPE",
  "framework": "$FRAMEWORK",
  "statistics": {
    "total_files": $FILE_COUNT,
    "code_files": $CODE_FILES,
    "test_files": $TEST_FILES
  },
  "has_tests": $HAS_TESTS,
  "has_docs": $HAS_DOCS,
  "has_ci": $HAS_CI,
  "dependencies": ${DEPENDENCIES:-0},
  "dev_dependencies": ${DEV_DEPENDENCIES:-0},
  "scripts": ${SCRIPTS:-0}
}
EOF
```

### Step 2: Health Assessment with Codex

```bash
# Use Codex to assess project health
PROJECT_STATE=$(cat /tmp/project-state.json)

# Get file listing for context
FILE_STRUCTURE=$(find . -type f -not -path "./node_modules/*" -not -path "./.git/*" | head -100)

codex exec "
Analyze this project's health and identify issues:

PROJECT STATE:
$PROJECT_STATE

FILE STRUCTURE (first 100 files):
$FILE_STRUCTURE

PACKAGE.JSON:
$(cat package.json 2>/dev/null || echo "{}")

Perform health assessment across these dimensions:

1. **Testing**: Test coverage, test quality, missing tests
2. **Documentation**: README quality, API docs, comments
3. **Security**: Vulnerabilities, exposed secrets, auth patterns
4. **Performance**: Bottlenecks, optimization opportunities
5. **Code Quality**: Linting, formatting, type safety
6. **Architecture**: Structure, patterns, scalability
7. **Dependencies**: Outdated packages, security issues, bloat
8. **CI/CD**: Automation, deployment strategy

For each dimension, provide:
- score: 0.0-1.0
- status: \"excellent\" | \"good\" | \"needs_improvement\" | \"critical\"
- issues: array of problems found
- recommendations: array of specific actions

Output JSON:
{
  \"overall_health\": 0.75,
  \"dimensions\": {
    \"testing\": {
      \"score\": 0.60,
      \"status\": \"needs_improvement\",
      \"issues\": [\"Only 15% test coverage\", \"No E2E tests\"],
      \"recommendations\": [\"Add unit tests for core functions\", \"Set up Playwright for E2E\"]
    },
    \"security\": {
      \"score\": 0.50,
      \"status\": \"critical\",
      \"issues\": [\"No input validation\", \"SQL injection possible\"],
      \"recommendations\": [\"Add input sanitization\", \"Use parameterized queries\"]
    }
  }
}

Output ONLY valid JSON.
" > /tmp/health-assessment.json
```

### Step 3: Capability Gap Analysis

```bash
# Identify missing capabilities using capability graph
HEALTH_ASSESSMENT=$(cat /tmp/health-assessment.json)
CAPABILITY_GRAPH=$(cat META/capability-graph.json)

codex exec "
Based on this health assessment, identify missing or incomplete capabilities:

HEALTH ASSESSMENT:
$HEALTH_ASSESSMENT

AVAILABLE CAPABILITIES:
$CAPABILITY_GRAPH

For each identified issue, suggest capabilities that would address it.

Output JSON:
{
  \"gaps\": [
    {
      \"issue\": \"No input validation\",
      \"severity\": \"high\",
      \"dimension\": \"security\",
      \"suggested_capabilities\": [\"security-engineer\", \"input-validator-mcp\"],
      \"impact\": \"high\",
      \"effort\": \"medium\"
    }
  ]
}

Output ONLY valid JSON.
" > /tmp/capability-gaps.json
```

### Step 4: Generate Recommendations

```bash
# Prioritize recommendations by impact and effort
python3 <<'PYTHON_SCRIPT'
import json

# Load data
with open('/tmp/health-assessment.json') as f:
    health = json.load(f)

with open('/tmp/capability-gaps.json') as f:
    gaps = json.load(f)

# Score recommendations
for gap in gaps['gaps']:
    # Impact score
    impact_scores = {'critical': 1.0, 'high': 0.8, 'medium': 0.5, 'low': 0.3}
    impact = impact_scores.get(gap.get('impact', 'medium'), 0.5)

    # Effort score (inverted - lower effort = higher score)
    effort_scores = {'low': 1.0, 'medium': 0.6, 'high': 0.3}
    effort = effort_scores.get(gap.get('effort', 'medium'), 0.6)

    # Priority = impact * effort
    gap['priority_score'] = round(impact * effort, 3)

# Sort by priority
gaps['gaps'].sort(key=lambda x: x['priority_score'], reverse=True)

# Write prioritized gaps
with open('/tmp/recommendations.json', 'w') as f:
    json.dump(gaps, f, indent=2)

print(f"Generated {len(gaps['gaps'])} recommendations")
PYTHON_SCRIPT
```

### Step 5: Generate Action Plan

```bash
# Create structured action plan
python3 <<'PYTHON_SCRIPT'
import json
from datetime import datetime

# Load all data
with open('/tmp/health-assessment.json') as f:
    health = json.load(f)

with open('/tmp/recommendations.json') as f:
    recommendations = json.load(f)

# Generate action plan
action_plan = {
    'project': 'PROJECT_NAME',
    'analyzed_at': datetime.utcnow().isoformat() + 'Z',
    'overall_health': health.get('overall_health', 0),
    'health_assessment': health,
    'recommendations': recommendations['gaps'][:10],  # Top 10
    'quick_wins': [
        r for r in recommendations['gaps']
        if r.get('effort') == 'low' and r.get('impact') in ['high', 'critical']
    ][:3],
    'critical_issues': [
        r for r in recommendations['gaps']
        if r.get('severity') == 'high' or r.get('severity') == 'critical'
    ]
}

with open('/tmp/diagnostic-report.json', 'w') as f:
    json.dump(action_plan, f, indent=2)
PYTHON_SCRIPT
```

## Scoring System

### Health Dimensions

Each dimension scored 0.0-1.0:

```javascript
const dimensions = {
  testing: {
    weight: 0.15,
    factors: ['coverage', 'test_quality', 'test_types']
  },
  documentation: {
    weight: 0.1,
    factors: ['readme', 'api_docs', 'code_comments']
  },
  security: {
    weight: 0.2,
    factors: ['vulnerabilities', 'auth', 'input_validation']
  },
  performance: {
    weight: 0.15,
    factors: ['load_time', 'memory_usage', 'optimization']
  },
  code_quality: {
    weight: 0.15,
    factors: ['linting', 'typing', 'complexity']
  },
  architecture: {
    weight: 0.1,
    factors: ['structure', 'patterns', 'scalability']
  },
  dependencies: {
    weight: 0.1,
    factors: ['up_to_date', 'security', 'bloat']
  },
  ci_cd: {
    weight: 0.05,
    factors: ['automation', 'deployment', 'monitoring']
  }
}

// Overall health = weighted average
overallHealth = sum(dimension.score * dimension.weight)
```

### Recommendation Priority

```javascript
function calculatePriority(gap) {
  const impactScores = { critical: 1.0, high: 0.8, medium: 0.5, low: 0.3 }
  const effortScores = { low: 1.0, medium: 0.6, high: 0.3 }

  const impact = impactScores[gap.impact] || 0.5
  const effort = effortScores[gap.effort] || 0.6

  return impact * effort
}
```

## Example Output

```json
{
  "project": "my-nextjs-app",
  "analyzed_at": "2025-10-28T12:00:00Z",
  "overall_health": 0.68,
  "health_assessment": {
    "overall_health": 0.68,
    "dimensions": {
      "testing": {
        "score": 0.4,
        "status": "needs_improvement",
        "issues": ["Only 15% test coverage", "No E2E tests", "Missing integration tests"],
        "recommendations": [
          "Add unit tests for API routes",
          "Set up Playwright for E2E testing",
          "Add integration tests for database"
        ]
      },
      "security": {
        "score": 0.5,
        "status": "critical",
        "issues": [
          "No input validation on API routes",
          "CORS configured too permissively",
          "Environment variables exposed in client"
        ],
        "recommendations": [
          "Add input validation with Zod",
          "Restrict CORS to specific origins",
          "Use NEXT_PUBLIC_ prefix correctly"
        ]
      }
    }
  },
  "recommendations": [
    {
      "issue": "No input validation on API routes",
      "severity": "high",
      "dimension": "security",
      "suggested_capabilities": ["security-engineer", "api-designer"],
      "impact": "high",
      "effort": "medium",
      "priority_score": 0.48
    },
    {
      "issue": "Only 15% test coverage",
      "severity": "medium",
      "dimension": "testing",
      "suggested_capabilities": ["testing-strategist"],
      "impact": "high",
      "effort": "high",
      "priority_score": 0.24
    }
  ],
  "quick_wins": [
    {
      "issue": "Missing README documentation",
      "severity": "low",
      "dimension": "documentation",
      "suggested_capabilities": ["technical-writer"],
      "impact": "medium",
      "effort": "low",
      "priority_score": 0.5
    }
  ],
  "critical_issues": [
    {
      "issue": "No input validation on API routes",
      "severity": "high",
      "dimension": "security",
      "suggested_capabilities": ["security-engineer", "api-designer"],
      "impact": "high",
      "effort": "medium",
      "priority_score": 0.48
    }
  ]
}
```

## Integration

### With orchestration-planner

Recommendations include suggested capabilities that planner can use to generate workflows.

### With skill-validator

Health assessment includes validation of existing capabilities.

### With Repository Brain

Will integrate into `scripts/brain/diagnose` command for interactive diagnostics.

## Success Metrics

- ✅ Health scores correlate with manual audits
- ✅ Recommendations are actionable and specific
- ✅ Quick wins provide immediate value
- ✅ Critical issues correctly prioritized
- ✅ Suggested capabilities are relevant

## Related Skills

- orchestration-planner: Uses recommendations to plan improvements
- skill-validator: Validates existing capabilities
- capability-graph-builder: Provides capability options

© daffy0208 · MIT · daffy0208/ai-dev-standards

Similar skills

All skills for Code review and refactoring →

From the same set63

The whole set →
Deployment Advisor Deployment Advisor guides infrastructure selection and CI/CD setup based on runtime requirements, database needs, and traffic scale. CX Codex +1 145installs Go-to-Market Planner The Go-to-Market Planner skill structures product launches around positioning, messaging, channels, timing, and metrics. Use it when entering a market or preparing a campaign. CX Codex +1 145installs Context Preserver Context Preserver — a skill that saves your working state to .adhd/context.json and brings it back after a break: the file, the line, the next step. CX Codex +1 139installs User Researcher User Researcher runs a full user research cycle, from research questions and recruitment to personas and a report. Useful when product assumptions need checking before code gets written. CX Codex +1 138installs Framework Orchestrator The Framework Orchestrator skill maps frameworks and other skills to project phases. Use it when you need a project pattern, an ordered plan, or phase checks. CX Codex +1 136installs release-manager release-manager turns a risky deploy into stages: internal team first, then 5% of beta users, then everyone. Comes with feature flags, canary deploys and rollback rules. CX Codex +1 135installs Orchestration Planner The Orchestration Planner skill turns a high-level goal into a checked workflow with ranked paths and fallbacks. It fits projects that keep capabilities in a graph. CX Codex +1 134installs Manifest Generator Manifest Generator turns a skill or MCP description into a YAML capability manifest: preconditions, effects, domains, risk. Useful when the descriptions exist but the orchestration cards do not. CX Codex +1 131installs

Project sponsors

Companies that keep this analytics open