Bootstrap Project

Set up agent context files so Claude Code, Codex, and other AI agents understand a project from the first prompt.

When to Use This Skill

Use when the user:

Wants to start a new project with agent context from the beginning
Opens an existing repo that lacks AGENTS.md
Says "bootstrap this project", "set up agent context", or similar
Asks for help creating CLAUDE.md or AGENTS.md

Steps

1. Determine whether this is a new or existing project

Existing project — the current directory has source files, a README, or a .git directory:

Skip to step 3.

New project — the current directory is not a project, or the user wants to create one:

Ask for:
1. Project name — used for the directory name (kebab-case, e.g. my-project) and the AGENTS.md heading.
2. Location — parent directory (default: current directory).
3. Brief description — purpose, intended stack, key constraints. This replaces file-based inference in step 3.
Create the directory: mkdir -p <location>/<project-name>
cd into it.
Run git init.
Create a .gitignore appropriate for the described stack (e.g. Node, Python, Rust).

2. Guard against overwrites

If AGENTS.md already exists, stop and ask before overwriting.
If CLAUDE.md exists and is not a symlink to AGENTS.md, stop and ask.
If agent_docs/ already exists, skip creating it but mention it.

3. Gather project context

Read (do not modify) the following if they exist:

README.md / README
package.json, pyproject.toml, Cargo.toml, go.mod, or equivalent manifest
Top-level directory listing (one level deep)
CI config (.github/workflows/, .gitlab-ci.yml, Makefile, Justfile, etc.)

For new projects with no files, use the user's description from step 1 instead.

3b. Detect data projects

If the project is a data pipeline or analytics project — indicated by dependencies like dlt, sqlmesh, polars, duckdb in pyproject.toml, the presence of .duckdb files, ingest/ or transform/ directories, or the user's description — suggest the /data-pipelines skill's directory layout:

ingest/          # Extraction and loading scripts
transform/       # SQL models or transformation logic
notebooks/       # marimo notebooks (.py files)
data/            # Local data files (gitignored)

Include this layout in the Directory Structure section of AGENTS.md. For new data projects, create the directories. For existing projects that already have a different layout, document what exists — don't restructure.

Also mention in the Conventions section: "Use the /data-pipelines skill for ingestion, transformation, and analytics work."

4. Write `AGENTS.md`

Create AGENTS.md in the project root. Use the structure below as a guide — fill every section with specifics from step 3. Omit sections that don't apply. Never leave placeholder text or angle-bracket tokens in the output.

Structure:

Heading — project name.
Opening line — one-sentence purpose.
Stack — language, framework, major dependencies.
Directory Structure — table of key paths and their purpose.
Key Commands — build, test, lint/format, dev server (only those that exist).
Conventions — coding style, naming, branching model, PR process.
Gotchas — non-obvious things an agent should know (env vars, generated files, monorepo quirks, etc.).

5. Create `CLAUDE.md` symlink

ln -s AGENTS.md CLAUDE.md

Claude Code reads CLAUDE.md for project instructions. The symlink keeps AGENTS.md as the single source of truth. Codex reads AGENTS.md directly — no extra symlink needed.

6. Create `agent_docs/` directory

mkdir -p agent_docs

Add agent_docs/README.md so the directory is tracked by git:

# agent_docs

Supplementary context for AI agents working in this repository.
Place architecture decisions, API specs, or onboarding notes here.

7. Report results

Print a summary of what was created:

Created:
  AGENTS.md          — project context for AI agents
  CLAUDE.md          -> AGENTS.md (symlink)
  agent_docs/        — supplementary context directory

Next steps:
  - Review AGENTS.md and refine any sections
  - Add architecture docs or API specs to agent_docs/
  - Commit the new files

bootstrap-project