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
npx skills add daffy0208/ai-dev-standards --skill system-diagnostician -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/system-diagnostician/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/system-diagnostician/
1Skills CLI (Vercel)
npx skills add daffy0208/ai-dev-standards --skill system-diagnostician -a codex2Manually: put the files in place
.agents/skills/system-diagnostician/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add daffy0208/ai-dev-standards --skill system-diagnostician -a cursor2Manually: put the files in place
.cursor/skills/system-diagnostician/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install daffy0208/ai-dev-standards skills/system-diagnostician2Manually: put the files in place
.github/skills/system-diagnostician/SKILL.md1Skills CLI (Vercel)
npx skills add daffy0208/ai-dev-standards --skill system-diagnostician -a gemini-cli2Platform CLI
gemini skills install https://github.com/daffy0208/ai-dev-standards --path skills/system-diagnosticianManually: put the files in place
.devin/skills/system-diagnostician/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add daffy0208/ai-dev-standards --skill system-diagnostician -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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