init-project

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:

1. Check gh:

   which gh
   gh auth status
   

2. If gh is missing, install it when the local package manager is obvious and the environment allows it; otherwise give concise install instructions.

3. If gh is not authenticated, run gh auth login --web --git-protocol https and let the user complete the browser flow.

4. Ask for the GitHub owner and visibility before creating a remote.

5. 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.