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:
Project name
— used for the directory name (kebab-case, e.g.
my-project
) and the
AGENTS.md
heading.
Location
— parent directory (default: current directory).
Brief description
— purpose, intended stack, key constraints. This replaces file-based inference in step 3.
Create the directory:
mkdir -p /
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