Project setup

Project Setup Skill

Set up a new project with a standardized, agent-legible structure.

When to Use

• User asks to create/set up a new project
• User has a folder with source material (transcript, article, notes) to bootstrap from
• User wants a consistent starting structure for a new repo

Inputs

Input	Required	Description
Project name	Yes	Directory name (kebab-case, e.g., cyber-readiness)
Project path	Yes	Usually ~/projects/[project-name]
Purpose	Yes	One sentence describing what the project is
Source material	No	Transcript, article, or notes to derive context from
Tech stack	No	If known; often TBD at setup time

Process

1. Gather Context

If source material exists:

• Read and analyze it
• Extract: purpose, key concepts, stakeholders, constraints, open questions
• Identify potential phases/milestones

If no source material:

• Ask user for: purpose, key context, any known constraints

2. Create Directory Structure

[project-name]/
├── CLAUDE.md
├── scratchpad.md
├── .gitignore
├── .claude/
│   ├── agents/        # Project-specific agents (empty)
│   └── skills/        # Project-specific skills (empty)
└── docs/
    ├── INDEX.md
    ├── plans/
    │   └── [project-name]-plan.md
    ├── sessions/      # Session history (empty)
    ├── research/      # Research outputs (empty)
    └── Archive/       # Obsolete docs (empty)

3. Configure .mcp.json Allowlist (if needed)

If the project needs project-scoped MCP servers, create .mcp.json at project root with an explicit allowlist — avoid a blanket "enable all project MCP servers" setting if your harness offers one. A server only belongs in .mcp.json if this project actually uses it; servers used by several of your projects are better configured globally instead. Skip this step entirely if the project has no MCP needs yet — add .mcp.json later when a server is actually needed.

4. Create CLAUDE.md

Use this template:

# [Project Name] - Project Rules

Inherits from `~/.claude/CLAUDE.md`. This file contains project-specific context only.

## Purpose

[One paragraph describing the project goal]

## Quick Links

| Resource | Location |
|----------|----------|
| Active Work | `scratchpad.md` |
| Project Plan | `docs/plans/[project-name]-plan.md` |
| Documentation | `docs/INDEX.md` |
[Add source material link if applicable]

## Key Context

[Bullet points of important context from source material or user input]

## Project-Specific Rules

[Any rules specific to this project - can start with placeholder]

## Lessons (Project)

*None yet.*

Optional sections (include if information available):

• Tech Stack
• Architecture Reference (if leveraging another project)
• Client/Stakeholder info
• Timeline/Deadlines

5. Create scratchpad.md

Use this template:

# Scratchpad - [Project Name]

<!--
INSTRUCTIONS FOR CLAUDE:
- Do not rename sections
- Append instead of deleting prior content (mark outdated content as such)
- Update this file frequently during work sessions
- Add lessons learned immediately when bugs/corrections occur
- Keep under 150 lines; move verbose history to sessions/
- Only the top-level session writes to this file (subagents report back verbally)
-->

## Background/Motivation

[Why this project exists — one or two sentences, e.g., "Bootstraps [X] to solve [Y] for [stakeholder]."]

## Active Plan

**Plan**: `docs/plans/[project-name]-plan.md`
**Current Phase**: [Phase name or "Setup complete"]

## Key Decisions

[Numbered list of key decisions, or placeholder if none yet]

## Work Completed

### [Date]: Project Setup

- Created project structure
- [Any other setup work]

## Work In Progress

*None — awaiting [next phase/action].*

## Open Questions

[Numbered list of open questions from source material or setup]

## Session Lessons

*None yet.*

## Respawn Prompt

You are picking up work on the [Project Name] project.

Read in order:

1. ~/projects/[project-name]/CLAUDE.md — Project rules
2. ~/projects/[project-name]/scratchpad.md — Current state
3. ~/projects/[project-name]/docs/plans/[project-name]-plan.md — Project plan

CURRENT STATE:

• [Brief state summary]

[Any critical context]

Then tell me: What would you like to work on?

---

**Last updated**: [Date]

Machine scratchpads: scratchpad.md above is the single shared file — create it always. If you work from more than one machine, only add per-machine files (scratchpad.laptop.md, scratchpad.desktop.md, etc.) once the project is actually worked from more than one — each holds that machine's env state and respawn prompt, keyed by hostname. Don't scaffold them speculatively for a single-machine project.

6. Create docs/INDEX.md

Use this template:

# [Project Name] Documentation Index

## Document Map

### Root Files

| File | Purpose |
|------|---------|
| `CLAUDE.md` | Project rules and context |
| `scratchpad.md` | Current work state |
[Add source file if applicable]

### Plans (`docs/plans/`)

| File | Purpose | Status |
|------|---------|--------|
| `[project-name]-plan.md` | High-level project plan | Active |

### Research (`docs/research/`)

*To be populated as research progresses*

### Sessions (`docs/sessions/`)

*Session history will be added as work progresses*

### Archive (`docs/Archive/`)

*Obsolete documents will be moved here*

## Agent Audit Manifest

| Agent | Authoritative Specs | Purpose |
|-------|---------------------|---------|
| Researcher | `docs/research/*.md` | Gather information |
| Implementer | `docs/plans/`, reference projects | Build components |
| Reviewer | `CLAUDE.md`, patterns | Ensure quality |

[Customize based on project needs]

7. Create docs/plans/[project-name]-plan.md

Use this template:

# [Project Name] Plan

**Status**: 🟡 Planning
**Created**: [Date]
**Goal**: [One-line goal]

---

## Vision

[1-2 paragraphs describing the project vision and why it matters]

## Background

[Context from source material or user input]

---

## Phases

### Phase 1: [Name]

**Goal**: [What this phase achieves]

**Tasks**:
- [ ] Task 1
- [ ] Task 2

**Deliverables**:
- Deliverable 1
- Deliverable 2

### Phase 2: [Name]

[Repeat structure]

---

## Success Criteria

1. [Criterion 1]
2. [Criterion 2]

---

## Open Questions

1. [Question 1]
2. [Question 2]

---

## Risk Factors

| Risk | Mitigation |
|------|------------|
| [Risk 1] | [Mitigation] |

---

*This plan will be updated as work progresses.*

8. Create .gitignore

# OS
.DS_Store

# Dependencies
node_modules/

# Environment
.env
.env.local
.env*.local

# Build outputs
dist/
build/
.next/
out/

# IDE
.idea/
.vscode/
*.swp

# Logs
*.log
npm-debug.log*

9. Initialize Git and Create Remote

Do this immediately at project start — a project folder without its own repo silently inherits the nearest parent repo (e.g. the home folder), which pollutes git status with unrelated files and blocks proper version control. git init first, before any other work, prevents this.

cd ~/projects/[project-name]
git init
git add -A
git commit -m "Initial project setup

- CLAUDE.md with project context and rules
- scratchpad.md with current state
- docs/INDEX.md with documentation map
- docs/plans/[project-name]-plan.md with phased approach
- Standardized directory structure

Co-Authored-By: Claude <[email protected]>"

gh repo create your-github-user/[project-name] --private --source=. --push --description "[One-line description]"

10. Create a Shell Alias (optional)

If you like quick cd-and-launch aliases, add one to your shell rc file for fast access:

# [Project Name] project
alias [short-name]='cd ~/projects/[project-name] && claude'

Naming convention for short-name:

• Use a recognizable abbreviation (e.g., cyber for cyber-readiness, mission for mission-control)
• Keep it short but unambiguous
• Check existing aliases first to avoid conflicts

After adding, remind the user to reload their shell config to activate it immediately.

11. Register the Project (optional)

If you keep your own project index or portfolio doc across projects, this is the point to add the new project to it — name, purpose, path, and a one-line status. Skip this step entirely if you don't maintain one; it's a nice-to-have for people running many projects side by side, not a requirement of this skill.

Output

Report to user:

• Project path and GitHub URL
• Directory structure created
• Plan summary (phases)
• Any open questions identified
• Shell alias created, if any
• Confirmation of project-index update, if applicable

Notes

• This skill creates the scaffolding only — it does not implement the project
• The plan should be high-level and legible; detailed PRDs are created separately (see prd-creation)
• Tech stack section in CLAUDE.md is optional (often TBD at setup)
• Source material is optional — skill works with or without it
• Always use kebab-case for project directory names
• Group related deliverables under a topic subdirectory. When a project produces multiple files about one topic, put them in a dedicated subdirectory (e.g. docs/<topic>/) rather than flat in the docs root. This keeps the docs tree legible as it grows; flat topic-files in the root become unmanageable quickly.