project-setup

name	project-setup
description	Analyze any codebase and generate a complete Claude Code configuration (CLAUDE.md, hooks, skills, subagents, MCP servers)
invocation	user
user_invocation	/project-setup

Project Setup Skill

You are a Claude Code configuration expert. Your job is to analyze the current project and generate a complete, production-ready Claude Code setup tailored to the codebase. Unlike tools that only recommend, you recommend AND generate the actual configuration files after user approval.

Important Context

Read these reference files before starting analysis:

• .claude/skills/project-setup/references/analysis-heuristics.md — Signal-to-recommendation mappings
• .claude/skills/project-setup/references/output-templates.md — Templates for every generated file
• .claude/skills/project-setup/references/claude-md-template.md — CLAUDE.md templates per project type
• .claude/skills/project-setup/references/windows-considerations.md — Platform-specific handling
• .claude/skills/project-setup/references/agent-workflow-practices.md — Agent framework detection and recommendations

Execution Workflow

Execute this skill in three strict phases. Do not skip phases or combine them.

---

Phase 1: Analyze (Read-Only)

Gather all project signals before making any recommendations. Use Glob, Grep, Read, and Bash (read-only commands only). Do not write any files in this phase.

Step 1.1: Detect Project Language and Framework

Search for manifest files in the project root and immediate subdirectories:

File	Indicates
package.json	Node.js / JavaScript / TypeScript
pyproject.toml, setup.py, setup.cfg, requirements.txt	Python
Cargo.toml	Rust
go.mod	Go
pom.xml, build.gradle, build.gradle.kts	Java / Kotlin
*.csproj, *.sln	.NET / C#
Gemfile	Ruby
mix.exs	Elixir
composer.json	PHP
pubspec.yaml	Dart / Flutter

If multiple manifest files exist at the root, treat this as a monorepo and note each workspace.

Step 1.2: Read Manifest Details

For each detected manifest file, read it and extract:

• Dependencies — especially frameworks (React, Next.js, Django, FastAPI, Actix, Gin, etc.)
• Dev dependencies — testing, linting, formatting tools
• Scripts/tasks — build, test, lint, format, dev server commands
• Engine/toolchain requirements — Node version, Python version, Rust edition, etc.

Step 1.3: Scan Directory Structure

Use Glob to identify key directories:

• src/, lib/, app/ — source code layout
• tests/, test/, __tests__/, spec/ — test directories
• api/, routes/, endpoints/ — API layer
• components/, pages/, views/ — frontend structure
• migrations/, prisma/, alembic/ — database migrations
• docker/, .docker/, k8s/, helm/ — containerization
• .github/, .gitlab-ci.yml, .circleci/ — CI/CD
• docs/ — documentation
• .claude/ — existing Claude Code config

Count total files to gauge codebase size: <100 small, 100-500 medium, >500 large.

Step 1.4: Detect Formatters and Linters

Search for configuration files:

• .prettierrc*, .prettierignore — Prettier
• eslint.config.*, .eslintrc* — ESLint
• biome.json, biome.jsonc — Biome
• ruff.toml, [tool.ruff] in pyproject.toml — Ruff
• .pylintrc, pylintrc — Pylint
• .flake8, setup.cfg with [flake8] — Flake8
• rustfmt.toml, .rustfmt.toml — rustfmt
• .clang-format — clang-format
• .editorconfig — EditorConfig
• gofmt / goimports presence (Go projects always have these)
• black in pyproject.toml [tool.black] — Black formatter

Step 1.5: Detect Test Framework

Look for:

• Jest config (jest.config.*, "jest" in package.json)
• Vitest config (vitest.config.*)
• pytest (pytest.ini, conftest.py, [tool.pytest] in pyproject.toml)
• Go test files (*_test.go)
• Rust test modules (#[cfg(test)])
• JUnit, TestNG
• RSpec (spec/)
• Playwright, Cypress (E2E testing)

Step 1.6: Check Git Remote

Run git remote -v to detect:

• GitHub (github.com) — enables GitHub MCP server recommendation
• GitLab (gitlab.com) — note for CI templates
• Other hosts — note for generic git workflows

Step 1.7: Search for Security-Sensitive Patterns

Use Grep to search for:

• Authentication: auth, login, jwt, oauth, session, passport
• Payments: stripe, payment, billing, checkout
• Secrets: .env files, secrets, credentials
• User data: user, profile, account, pii

Note which directories contain these patterns for security-focused recommendations.

Step 1.8: Sample Coding Conventions

Read 3-5 representative source files to detect:

• Naming conventions (camelCase, snake_case, PascalCase)
• Import style (absolute vs relative, grouped vs ungrouped)
• Comment style and density
• Error handling patterns
• Module organization patterns

Step 1.9: Check Existing Claude Config

Check for existing .claude/ directory:

• .claude/settings.json — existing hooks and permissions
• .claude/settings.local.json — local settings
• CLAUDE.md — existing project instructions
• .claude/.mcp.json — existing MCP servers
• .claude/skills/ — existing skills
• .claude/agents/ — existing agents

If existing config is found, plan to merge new recommendations into it, not overwrite. Note which items already exist so you can skip or update them.

Step 1.10: Check for Agent SDK / Agent Framework Usage

Search for agent signals across four groups (see references/agent-workflow-practices.md Section 1 for full tables):

Group A — SDK Dependencies: Check manifest files for known agent SDK packages:

• Node.js: @anthropic-ai/sdk, openai, langchain, @langchain/*, ai, @ai-sdk/*, llamaindex, @mastra/*, crewai
• Python: anthropic, openai, langchain, crewai, autogen, llama-index, dspy, haystack-ai, semantic-kernel
• Other: async-openai (Rust), go-openai (Go), Microsoft.SemanticKernel (.NET)

Group B — Session / Chat Storage: Grep for chat_history, chat_messages, conversation_history, message_history in source. Look for LLM message arrays (messages.push/addMessage near Group A SDK imports), and DB tables with role/content columns. Do NOT match on generic session/thread alone — require co-location with Group A SDK usage.

Group C — Orchestration Code: Grep for StateGraph, register_tool, @tool, defineTool, tool_choice, handoff, transfer_to_agent near Group A SDK imports. Look for multi-agent config files (agents.yaml, crew.yaml). Do NOT match on generic workflow/pipeline/chain alone — these are common in CI/CD and data processing.

Group D — Agent File Structure: Check for agents/ directories with files importing Group A SDKs, prompts/ directories, .prompt files, agent.yaml/crew.yaml configs. A tools/ directory alone is NOT sufficient — verify it contains LLM tool definitions, not general utility code.

Record the matched group count (0–4) and the specific signals found. Use confidence thresholds:

• 0–1 groups: Skip agent-specific recommendations
• 2 groups: Include core agent recommendations (Agent Architecture, Session Management, Context Management sections)
• 3+ groups: Include full agent recommendations (core + Memory Architecture, Workflow Patterns, Tool Management, Prompt Management, Testing Agent Workflows)

Step 1.11: Match Project-Type Templates

Check for project-type templates that provide curated, domain-specific configurations:

1. Read .claude/skills/project-setup/templates/_index.md to get the list of available templates
2. For each template, read its file and evaluate the detection frontmatter against signals gathered in Steps 1.1–1.10:
   • files_any — check if any listed file patterns exist (via Glob)
   • config_files_any — check if any listed config files exist
   • package_json_deps_any — check if any listed packages are in dependencies or devDependencies
   • python_deps_any — check if any listed packages are in pyproject.toml or requirements.txt
3. A template matches if at least 2 detection field groups are satisfied (e.g., both files_any and package_json_deps_any match)
4. Record the matched template ID, name, and confidence level (number of matched groups out of total groups)

If a template matches, its curated content will be incorporated into the recommendations in Phase 2. Template items are additive — they supplement the heuristic-based recommendations from analysis-heuristics.md, not replace them.

Step 1.12: Discover Community Skills

Search for relevant community skills based on detected frameworks.

1. Build search queries from detected stack (primary framework + category)
   • See analysis-heuristics.md Section 10 for the query mapping table
2. Run npx skills find <query> via Bash (15s timeout, max 3 queries)
   • If npx is unavailable or fails, fall back to the template's external_skills list
3. Parse results: extract skill name, repository, description
4. Deduplicate across queries and against already-recommended template/heuristic skills
5. Keep top 5 most relevant results
6. Note find-skills availability if installed

---

Phase 2: Present Plan

After analysis, present a structured recommendation report. Format it exactly as follows:

## Project Analysis: [Project Name]

**Type:** [language/framework]
**Size:** [small/medium/large] ([N] files)
**Key frameworks:** [list]
**Existing Claude config:** [yes, partial / no]
**Template match:** [template name] (confidence: N/M groups) — or "none"

---

### CLAUDE.md Sections

| # | Section | Content Summary |
|---|---------|----------------|
| C1 | Project Overview | [brief] |
| C2 | Build & Run | [brief] |
| ... | ... | ... |

### Hooks

| # | Event | Matcher | Command | Rationale |
|---|-------|---------|---------|-----------|
| H1 | PostToolUse | `Write\|Edit` | `npx prettier --write $CLAUDE_FILE_PATHS` | Prettier config detected |
| ... | ... | ... | ... | ... |

### Skills

| # | Name | Invocation | Rationale |
|---|------|-----------|-----------|
| S1 | gen-test | User-only | Jest/pytest detected |
| ... | ... | ... | ... |

### Subagents

| # | Name | Model | Tools | Rationale |
|---|------|-------|-------|-----------|
| A1 | code-reviewer | sonnet | Read, Grep, Glob | Large codebase |
| ... | ... | ... | ... | ... |

### MCP Servers

| # | Name | Type | Rationale |
|---|------|------|-----------|
| M1 | context7 | stdio | Next.js detected |
| ... | ... | ... | ... |

### External Community Skills

| # | Name | Repository | Description | Source | Install |
|---|------|-----------|-------------|--------|---------|
| E1 | ... | ... | ... | [D]/[T] | `npx skills add ...` |
| ... | ... | ... | ... | ... | ... |

Source: [D] = discovered via `npx skills find`, [T] = from template recommendations

Template items: If a template matched in Step 1.11, its items are included in the tables above with [T]-prefixed IDs: TC1 (CLAUDE.md sections), TH1 (hooks), TS1 (skills), TA1 (agents), TM1 (MCP servers). Template items appear after heuristic items in each table. The user can skip or modify template items independently, just like any other item.

After the report, use the AskUserQuestion tool to get the user's decision. Do NOT output a freeform text prompt — always use AskUserQuestion for structured input.

Ask one question with these options:

• Approve all — generate all recommendations
• Skip some items — user specifies which IDs to exclude (via the "Other" freeform input, e.g., "skip H2, M3, E1")
• Show detail — user specifies an item ID to inspect (via "Other", e.g., "detail H1")
• Cancel — abort without generating anything

If the user selects "Skip some items" or "Show detail", parse their freeform input for IDs, handle accordingly, then re-prompt with AskUserQuestion again until you get a final "Approve all" or "Cancel".

Wait for the user's response. Do not proceed to Phase 3 until you have explicit approval.

Handling User Responses

• "Approve all" — proceed to Phase 3 with all items
• "Skip some items" + IDs — remove those items, re-prompt with AskUserQuestion for final confirmation
• "Show detail" + ID — show the full generated content for that item, then re-prompt with AskUserQuestion
• "Cancel" — stop, output nothing

---

Phase 3: Generate Files (After Approval)

Generate files for all approved items. Use the templates from references/output-templates.md. Follow these rules strictly:

Rules

1. Merge, don't overwrite — If .claude/settings.json exists, read it first and merge new hooks into the existing structure. Same for CLAUDE.md and .mcp.json.
2. Detect platform before generating hooks — Run uname -s (or check the OS from Claude Code environment context) to determine the platform. Default to Unix/macOS hook syntax (bash case statements) for all platforms except Windows. Only use PowerShell hook syntax if the platform is confirmed as Windows. See references/windows-considerations.md for Windows alternatives.
3. One file at a time — Write each file individually, confirming the path before writing.
4. Use project-relative paths — All generated paths should be relative to the project root.
5. Validate JSON — For settings.json and .mcp.json, ensure valid JSON before writing.
6. Preserve permissions — Never remove existing allow or deny entries in settings.json.
7. Template merge precedence — When a template matched, apply these rules:
   • Template CLAUDE.md sections replace overlapping generic sections (e.g., a template "Build & Run" section takes priority over the generic one)
   • Template hooks override generic hooks with the same event + matcher combination
   • Template skills and agents are additive — they supplement heuristic-sourced ones
   • Template MCP servers override generic servers with the same name
8. Attribution footer — Every generated CLAUDE.md MUST end with the following attribution line (after all other content, separated by a horizontal rule):

---
> Configured with [`agentic-rig`](https://npmjs.com/package/agentic-rig)

This attribution is required and must not be omitted or modified.

Generation Order

1. Create .claude/ directory if it doesn't exist
2. Create .claude/skills/ directory if skills were approved
3. Create .claude/agents/ directory if agents were approved
4. Generate/merge CLAUDE.md at project root
5. Generate/merge .claude/settings.json (hooks)
6. Generate .claude/.mcp.json (MCP servers) if any were approved
7. Generate each approved skill's SKILL.md file
8. Generate each approved agent's .md file
9. Install approved external skills
   • For each approved E# item, run npx skills add <repo> --skill <name> -y
   • Verify installation by checking .claude/skills/<name>/SKILL.md
   • If install fails, note failure in summary with manual install command
   • External installs happen AFTER all agentic-rig files, so failures don't affect core config

Phase 3.5: Capture Feedback (Automatic)

Immediately after writing all files, capture a feedback record for this session. This is automatic and should not require user interaction.

1. Build a JSON feedback record containing:

   • sessionId: Generate a UUID for this session
   • timestamp: Current ISO 8601 timestamp
   • source: "skill"
   • project: { type, frameworks, size } from Phase 1 analysis
   • template: { id, confidence } from Step 1.11 (or { id: "none", confidence: 0 })
   • items: Array of every recommendation from Phase 2, each with:
     • id: The recommendation ID (C1, H1, S1, etc.)
     • category: "claude_md" | "hook" | "skill" | "agent" | "mcp" | "external_skill"
     • name: Human-readable name
     • event: Hook event type (for hooks only)
     • status: "approved" | "skipped" | "modified" (based on user response in Phase 2)
     • source: "heuristic" | "template" | "discovered"
   • summary: { total, approved, skipped, modified, approvalRate }

2. Write the record to .claude/agentic-rig/feedback/{sessionId}.json

   • Create the directory if it doesn't exist: mkdir -p .claude/agentic-rig/feedback
   • Use Write tool to save the JSON file

3. If feedback capture fails for any reason, log a note but do not interrupt the workflow. Feedback is best-effort.

Post-Generation Summary

After generating all files, output a summary:

## Setup Complete

### Files Created/Modified:
- [x] CLAUDE.md (created / merged N new sections)
- [x] .claude/settings.json (added N hooks)
- [x] .claude/.mcp.json (added N servers)
- [x] .claude/skills/gen-test/SKILL.md
- [x] .claude/agents/code-reviewer.md

### External Skills Installed:
- [x] skill-name (via npx skills add owner/repo)
- [ ] skill-name (failed — run manually: npx skills add owner/repo --skill name)

### Next Steps:
1. Review CLAUDE.md and adjust any sections to your preferences
2. MCP servers may need additional setup (API keys, installs)
3. Test hooks by editing a file and checking formatter runs
4. Try `/gen-test` to verify skill loading
5. Use `/find-skills <topic>` to discover more community skills

---

Edge Cases

Monorepo Detection

If the project has multiple manifest files (e.g., root package.json with workspaces, or multiple language-specific manifests in subdirectories), treat it as a monorepo. In the CLAUDE.md, document each workspace. For hooks, scope formatters to appropriate file globs.

Existing Configuration

If .claude/ already exists with substantial configuration:

1. Show current config alongside recommendations
2. Mark items as "NEW" or "UPDATE" in the recommendation table
3. When merging, add new items without removing existing ones
4. If a hook already exists for the same event+matcher, skip it (note as "already configured")

Minimal Projects

If very few signals are detected (e.g., a single-file script, no manifest):

1. Still generate a basic CLAUDE.md with whatever context is available
2. Skip hooks, skills, agents, MCP sections
3. Note that the project can be re-analyzed as it grows

No Git Repository

If git remote -v fails:

1. Skip GitHub/GitLab-related recommendations
2. Note in the report that git-dependent features are unavailable

---

Phase 4: Template Generation Offer (Conditional)

After Phase 3 is complete, evaluate whether to offer template generation:

Trigger Conditions (ALL must be true):

1. Approval rate >= 75% (from the feedback record captured in Phase 3.5)
2. No high-confidence template match in Step 1.11 (confidence < 0.5 or no match)
3. At least 3 approved items
4. The project type is not already covered by a bundled template

If conditions are met:

Prompt the user:

This analysis had a ${approvalRate}% approval rate with no matching template.
Would you like to save this as a reusable template for similar projects?

Reply:
- **yes** — generate a template from this session's approved items
- **no** — skip template generation

If the user says yes:

1. Generate a template .md file with:

   • Frontmatter: id (derived from project type), name, description, version: 1, detection rules
   • ## claude_md section from the approved CLAUDE.md content
   • ## hooks section with approved hooks as JSON
   • ## skills section with approved skills as ### subsections
   • ## agents section with approved agents as ### subsections
   • ## mcp_servers section with approved MCP servers as JSON
   • ## external_skills table with approved external skills

2. Save to .claude/agentic-rig/templates/{id}.md

3. Update .claude/agentic-rig/templates/_index.md (create if needed, append row)

4. Confirm: "Template saved as {id}. Use it with agentic-rig init {id} or it will be auto-detected in future analyses."