---
name: new-project
description: Set up a new personal or side project so it stays healthy as it grows — git, a short CLAUDE.md with rules for when to get more careful, IDEAS.md, an experiment log, a research folder, durable logging of user actions, server work and LLM calls, and a handoff command. Use when the user wants to start a new project or app, says "new project", "sett opp et nytt prosjekt", or asks how to structure a fresh repo for working with Claude Code.
argument-hint: "[what you want to build]"
---

# New project

Set up a project that Claude and the user can keep working on for months: every session starts from files, not from memory of an old chat. Keep the setup small. The point is a few habits that stop the project from decaying, not a framework.

Speak the user's language. Write the project files in English unless the user asks otherwise; they are read mostly by agents.

## 1. Understand what they want to build

If the user has already described the project (typed, or a long voice dump), work from that and ask only about what is missing. Otherwise ask, one question at a time, and offer likely answers so they can reply quickly:

- What it does and who it is for, in two sentences
- Stack, if they have a preference. If not, suggest one that fits the project and that Claude can run and test locally
- Whether it stores data, and whether that data is the valuable part
- Where it will run: nowhere yet, a static host such as Cloudflare Pages, or a small VM
- Where to create it (default: a new folder in the current directory)

Skip questions whose answers don't change the setup. If the idea still has many open decisions, suggest `/grill-me` for a deeper interview before planning (install: `/plugin install mattpocock-skills`).

## 2. Create the files

Create the folder and copy the templates in `templates/`, filling in the placeholders:

```
<project>/
  CLAUDE.md              ← templates/CLAUDE.md
  IDEAS.md               ← templates/IDEAS.md
  EXPERIMENTS.md         ← templates/EXPERIMENTS.md
  research/INDEX.md      ← templates/research-INDEX.md
  docs/data-practices.md ← references/data.md
  .claude/skills/handoff/SKILL.md  ← templates/handoff-SKILL.md
  .env.example
  .gitignore
```

- Keep CLAUDE.md short. Include only what Claude cannot work out from the code: commands, conventions, design principles and pointers to other docs. Delete template sections that don't apply rather than leaving them empty. Keep the "When to be more careful" table: it is how later sessions know when to slow down, since this skill only runs once.
- `.gitignore` must cover `.env`, `CLAUDE.local.md`, `data/logs/` and the database file, plus the usual files for the stack. Source data kept as files stays in git. API keys go in `.env`, never in code that reaches the browser.
- Add logging from the start, following the Logging section of the CLAUDE.md template: one small helper that appends JSONL events to `data/logs/`, used for user actions, server requests and background jobs, and every LLM call. It is far harder to add later, and it is what lets Claude answer "what actually happened?" instead of guessing. Check that one event actually lands in the log before moving on.
- Add one command that starts the app and one that runs the tests, and put both in CLAUDE.md. A fresh session should be able to verify the project without rediscovering how.

This skill sets up the project; it doesn't build the app. Even when the description reads like a build request, stop after the setup: research and a plan come first, and code written before them usually gets thrown away. The only code to add now is the logging helper, a start command and one test that runs, so the project can verify itself from the first session.

## 3. Initialize git

```bash
git init
git add -A
git commit -m "Project setup"
```

Commit after each working step from now on. Git is the undo button and the record of what each session did.

## 4. Suggest the next step

Tell the user, briefly, what was created and offer the natural next steps:

1. Research first: "Use subagents to research open-source libraries, free APIs and datasets for this. Write findings to research/ and keep research/INDEX.md updated."
2. Then a plan in a file: "Write PLAN.md with numbered steps. Don't write code yet." A new session can then do "Read PLAN.md and do step 1."
3. `/handoff` before ending a session, then `/clear`.

Mention the skills in the "Skills to suggest" table of CLAUDE.md in one line, so the user knows they exist; later sessions will suggest them when they fit.

## Additional resources

- `templates/` — the files to copy in step 2
- `references/data.md` — copied into the project as `docs/data-practices.md`: migrations, data as files, reviewed bulk changes