| name | init-project |
| description | Initialize a project workspace for Codex with project instructions, repository checks, notebook scaffolding, optional remotes, and optional O2/SLURM setup. Invoke manually with $init-project for first-time project setup, notebook bootstrap, project remotes, or O2/SLURM setup. |
| recommended_scope | global |
| disable-model-invocation | true |
Init Project
Invoke this skill manually with $init-project. Do not rely on automatic trigger behavior.
Initialize a project for Codex-assisted research work.
Use this skill for normal project setup. Do not use it to install Codex's user-level configuration.
What This Sets Up
AGENTS.md for project-local Codex context.notebook/ as a separate git repo for durable research memory..gitignore entries so notebook history stays out of the main repo.- Optional project-scope skills under
.agents/skills/.
- Optional GitHub remotes for the main project and notebook.
- Optional O2/SLURM setup guidance via
subskills/setup-o2/.
Do not create .claude/ files or CLAUDE.md unless the user explicitly asks for Claude compatibility.
Preflight
Inspect the project before editing:
pwd
git rev-parse --show-toplevel 2>/dev/null || true
git status --short --branch 2>/dev/null || true
git remote -v 2>/dev/null || true
test -f AGENTS.md && sed -n '1,220p' AGENTS.md
test -f README.md && sed -n '1,180p' README.md
test -f .gitignore && sed -n '1,220p' .gitignore
If the current directory is not a git repository, ask whether to run git init unless the user already made clear that this directory is the project root.
Main Repository Remote
If the main repository has no remote:
-
Check gh:
which gh
gh auth status
-
If gh is missing, install it when the local package manager is obvious and the environment allows it; otherwise give concise install instructions.
-
If gh is not authenticated, run gh auth login --web --git-protocol https and let the user complete the browser flow.
-
Ask for the GitHub owner and visibility before creating a remote.
-
Create the repo with the current directory name by default:
gh repo create <owner>/<repo-name> --private --source=. --remote=origin
Do not push unless the user explicitly asks or has already requested remote backup.
Notebook Setup
Create the notebook structure if missing:
mkdir -p notebook/{entries,feedback,plans}
test -d notebook/.git || git -C notebook init
Create these missing template files with the exact starting contents shown below.
If notebook/TODO.md exists but has no Next ID: line, repair it before committing: find the largest #N task id in both notebook/TODO.md and notebook/DONE.md, then insert Next ID: N+1 below the # To-Do heading.
notebook/INDEX.md:
# Notebook Index
| Date | Name | Summary |
|------|------|---------|
notebook/TODO.md:
# To-Do
Next ID: 1
notebook/DONE.md:
# Completed
Commit notebook initialization when there are notebook changes:
git -C notebook add -A
git -C notebook commit -m "Initialize notebook"
If the user wants notebook backup, create a private notebook remote. Use the same owner as the main repo unless the user chooses otherwise:
gh repo create <owner>/<repo-name>-notebook --private --source=notebook --remote=origin
Push only when the user approves backup/sync.
Main .gitignore
Ensure the main repo ignores the notebook:
# Codex project notebook (separate git repo)
notebook/
Do not automatically ignore AGENTS.md; project instructions are usually intended to be shared with collaborators. If the user wants private project instructions, recommend a private overlay or notebook entry instead.
Commit .gitignore only if the user wants setup changes committed.
Project AGENTS.md
If AGENTS.md exists, update it conservatively. If it does not exist, create a compact starter:
# Project Instructions
## Project Overview
Describe the project goal, key datasets, and expected outputs here.
## Commands
- Test:
- Lint:
- Run:
## Module Boundaries
No authoritative module boundaries have been defined yet. If Codex later infers boundaries from the code, review them and replace this placeholder with the accepted decomposition.
## Notebook
This project uses `notebook/` as a separate git repository for plans, analysis logs, and durable research memory. Start with `notebook/INDEX.md` when resuming prior work.
Preserve any existing project-specific instructions. Never overwrite a non-empty AGENTS.md without showing the proposed change.
Optional Project Skills
Project-scope skills are optional. Run ${CODEX_HOME:-$HOME/.codex}/bin/config-agent-tool list-skills from the project root. It prints a compact table of repo skills that are not already installed globally, including each skill's recommended scope, current project install state, and frontmatter description.
Ask the user which skills, if any, they want installed for this project. For standard project setup, recommend the skills whose recommended_scope is project. If the user chooses skills, install them:
${CODEX_HOME:-$HOME/.codex}/bin/config-agent-tool link-skills --add <chosen-skill-names>
If the user wants to remove project-local skills, use:
${CODEX_HOME:-$HOME/.codex}/bin/config-agent-tool link-skills --remove <skill-names>
Optional O2 Setup
If the user expects compute-heavy work, asks to configure O2, or mentions O2/SLURM setup, read subskills/setup-o2/SKILL.md after local project setup and follow that workflow. Do not make O2 setup a default requirement.
Completion Message
End with:
- what was created or updated
- whether notebook backup is local-only or remote-backed
- whether the main repo has a remote
- which project-scope skills were installed, if any
- whether a Codex restart is needed
- two next useful prompts based on the project
Keep the tour short. A new user should leave knowing they can ask for analysis, data inspection, project maintenance, or resume help.
