Use when starting work on an unfamiliar project or needing to understand a codebase - performs comprehensive analysis discovering architecture, patterns, dependencies, testing coverage, and improvement opportunities. Do NOT use on projects you already know well or for targeted questions about specific files - use direct exploration instead for focused queries.
/plugin marketplace add jrc1883/popkit-claude/plugin install popkit@popkit-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Perform deep analysis of a codebase to understand its architecture, patterns, dependencies, and opportunities for improvement.
Core principle: Understand before changing. Map before navigating.
Trigger: /popkit:project analyze command or when starting work on unfamiliar project
| Flag | Description |
|---|---|
--json | Output structured JSON instead of markdown, save to .claude/analysis.json |
--quick | Quick summary only (5-10 lines) |
--focus <area> | Focus analysis: arch, deps, quality, patterns |
When --json flag is provided:
output-styles/schemas/project-analysis.schema.json.claude/analysis.jsonimport sys
import json
from datetime import datetime
from pathlib import Path
# Add pattern detector to path
sys.path.insert(0, "hooks/utils")
from pattern_detector import analyze_project, detect_frameworks
# Detect patterns
project_dir = Path.cwd()
patterns = analyze_project(project_dir)
frameworks = detect_frameworks(project_dir)
# Build output
output = {
"project_name": project_dir.name,
"project_type": frameworks[0].name if frameworks else "unknown",
"analyzed_at": datetime.now().isoformat(),
"frameworks": [
{"name": p.name, "confidence": p.confidence, "version": ""}
for p in frameworks
],
"patterns": [
{
"name": p.name,
"category": p.category,
"confidence": p.confidence,
"examples": p.examples,
"description": p.description
}
for p in patterns if p.category != "framework"
],
"recommended_skills": [], # Populated based on patterns
"recommended_agents": [], # Populated based on analysis
"commands": {}, # Extracted from package.json
"quality_metrics": {} # TypeScript, linting, etc.
}
# Save to .claude/analysis.json
claude_dir = project_dir / ".claude"
claude_dir.mkdir(exist_ok=True)
(claude_dir / "analysis.json").write_text(json.dumps(output, indent=2))
print(json.dumps(output, indent=2))
Based on detected patterns, recommend:
| Pattern | Recommended Skill | Priority |
|---|---|---|
| nextjs + vercel-config | project:deploy | high |
| prisma OR drizzle | project:db-migrate | high |
| supabase | project:supabase-sync | medium |
| docker-compose | project:docker-dev | medium |
| feature-flags | project:feature-toggle | low |
| Pattern | Recommended Agent |
|---|---|
| Large codebase (>100 files) | performance-optimizer |
| React/Vue components | accessibility-guardian |
| API routes | api-designer |
| Security-sensitive | security-auditor |
| Low test coverage | test-writer-fixer |
# Map directory structure
find . -type d -name "node_modules" -prune -o -type d -print | head -50
# Find main entry points
ls index.* main.* app.* src/index.* src/main.* 2>/dev/null
# Count files by type
find . -name "node_modules" -prune -o -type f -print | \
sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20
Detect package managers:
ls package.json yarn.lock pnpm-lock.yaml Cargo.toml pyproject.toml go.mod 2>/dev/null
Detect frameworks:
next.config.*, app/ or pages/react in dependenciesvue.config.*express in dependenciesfastapi in dependenciesCargo.tomlDetect databases:
@supabase/supabase-jsprisma/schema.prismamongoosepg or postgresFrontend:
Backend:
Common:
# Check for linting config
ls .eslintrc* eslint.config.* .prettierrc* biome.json 2>/dev/null
# Check TypeScript config
ls tsconfig.json 2>/dev/null && grep "strict" tsconfig.json
# Find TODO/FIXME comments
grep -r "TODO\|FIXME" --include="*.ts" --include="*.tsx" --include="*.py" . | wc -l
# Find test files
find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" 2>/dev/null | wc -l
# Check test config
ls jest.config.* vitest.config.* pytest.ini 2>/dev/null
# Find coverage reports
ls coverage/ .coverage htmlcov/ 2>/dev/null
# Count dependencies
jq '.dependencies | length' package.json 2>/dev/null
jq '.devDependencies | length' package.json 2>/dev/null
# Check for outdated
npm outdated 2>/dev/null | head -10
# Check for vulnerabilities
npm audit --json 2>/dev/null | jq '.metadata.vulnerabilities'
# Find CI config
ls .github/workflows/*.yml .gitlab-ci.yml Jenkinsfile .circleci/config.yml 2>/dev/null
# Find Docker
ls Dockerfile docker-compose.yml 2>/dev/null
# Find deployment config
ls vercel.json netlify.toml fly.toml 2>/dev/null
# [Project Name] Analysis Report
## Summary
- **Type**: [Web App / API / CLI / Library]
- **Stack**: [Primary technologies]
- **Size**: [Files, Lines of code]
- **Health**: [Good / Needs attention / Critical issues]
## Technology Stack
### Frontend
- Framework: [Next.js 14 / React / Vue / etc.]
- Styling: [Tailwind / styled-components / etc.]
- State: [Redux / Zustand / Context]
### Backend
- Runtime: [Node.js / Python / Rust / Go]
- Framework: [Express / FastAPI / Actix]
- Database: [PostgreSQL / MongoDB / etc.]
### DevOps
- CI/CD: [GitHub Actions / GitLab CI / etc.]
- Deployment: [Vercel / AWS / etc.]
- Container: [Docker / etc.]
## Architecture
### Directory Structure
\`\`\`
[Tree output of main directories]
\`\`\`
### Key Patterns
- [Pattern 1]: [Where used]
- [Pattern 2]: [Where used]
### Entry Points
- Main: `[path]`
- API: `[path]`
- Tests: `[path]`
## Code Quality
| Metric | Value | Status |
|--------|-------|--------|
| Linting | [Configured/Missing] | [OK/Warning] |
| TypeScript Strict | [Yes/No] | [OK/Warning] |
| Test Coverage | [X%] | [OK/Warning] |
| TODO Comments | [N] | [OK/Warning] |
## Dependencies
### Production ([N] packages)
Top 5:
- [package]: [version]
### Security
- Vulnerabilities: [Low: X, Medium: Y, High: Z]
## Recommendations
### Critical
1. [Issue requiring immediate attention]
### High Priority
1. [Important improvement]
### Nice to Have
1. [Enhancement suggestion]
## Agent Opportunities
Based on analysis, these agents would be valuable:
- [agent-name]: [why]
- [agent-name]: [why]
## Next Steps
1. Run `/generate-mcp` to create project-specific tools
2. Run `/generate-skills` to capture discovered patterns
3. Run `/setup-precommit` to configure quality gates
Called by:
/analyze-project command/init-projectInforms:
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.