project-init
Initialize an ML research project control root. Use for paper/code/slides repos, shared memory, GitHub Project alignment, agent guidance, worktree policy, and lifecycle handoffs.
How do I install this agent skill?
npx skills add https://github.com/a-green-hand-jack/ml-research-skills --skill project-initIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a comprehensive workflow for initializing Machine Learning research projects with structured directories, memory management, and integration with standard development tools. It follows best practices for project organization and security auditing.
- Socketwarn
1 alert: gptAnomaly
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
Project Init Workflow
Initialize a research project as a control root, not just as two sibling repos.
Use this skill when the user wants a new ML research project where agents should work from <ProjectName>/ while paper/, code/, and optional slides/ remain independent component repositories.
Pair this skill with:
research-project-memoryto bootstrap cross-component memoryinit-latex-projectto create the paper repoinit-python-projectto create the code reporesearch-slide-deck-builderto create or maintain the optional slides repo using the externalprogress-slidestemplatenew-workspaceto create code experiment worktrees or paper version worktreesremote-project-controlwhen code runs on SSH/HPC serversremote-project-controlorsafe-git-opswhen GitHub CLI, repo remotes, or GitHub Project API operations are involvedsafe-git-opsbefore non-trivial Git work
Expected Project Shape
Default shape:
<ProjectName>/
├── PROJECT.md
├── AGENTS.md
├── CLAUDE.md
├── memory/
│ ├── project.yaml
│ ├── component-index.yaml
│ ├── current-status.md
│ ├── decision-log.md
│ ├── claim-board.md
│ ├── evidence-board.md
│ ├── provenance-board.md
│ ├── risk-board.md
│ ├── action-board.md
│ ├── handoff-board.md
│ ├── phase-dashboard.md
│ └── source-visibility-board.md
├── paper/ # independent LaTeX git repo
├── code/ # independent Python/ML git repo
├── code-worktrees/ # sibling worktree root for code repo branches
├── paper-worktrees/ # sibling worktree root for paper venue/arXiv/camera-ready versions
├── .uv-envs/ # ignored shared uv environments for code repo/worktrees
├── reference/ # project-local sources, cards, processing state, and project-use notes
├── slides/ # optional independent git repo
├── reviewer/ # reviewer simulation state
├── rebuttal/ # real review and response state
├── artifact/ # artifact-evaluation and release handoff state
└── docs/
├── overview.md
├── designs/
├── experiments/
├── updates/
├── audits/
└── timelines/
This structure is the textual source of truth for the project anatomy visual maintained in the repository README and asset/project-anatomy.png. If the layout changes, update the skill text and visual documentation together.
Do not create a top-level experiments/ directory by default. Experiment execution, run summaries, result reports, and raw artifact pointers belong inside code/ or the relevant code worktree.
Root-level docs/ is still useful, but it is project-level documentation, not a replacement for code-side evidence. Use it for staged method designs, cross-component experiment plans, project overviews, audits, timelines, and handoffs that coordinate paper/, code/, slides/, review, rebuttal, and artifact work.
Recommended code-side evidence paths:
code/docs/results/ # stable result summaries, table notes, figure notes
code/docs/reports/ # experiment-report-writer outputs
code/docs/runs/ # run registry, job pointers, config and commit pointers
Core Principles
<ProjectName>/is the agent control root.paper/,code/, andslides/are component repos, not mere folders.- The code component owns algorithm implementation, experiment execution, run records, result reports, server execution state, and code worktrees.
- Code worktrees should not be nested inside
code/by default. Use the sibling rootcode-worktrees/so Git, IDEs, search tools, and agents do not confuse worktrees with normal source files. - Code worktrees under the same project should share one code uv environment by default, e.g.
<ProjectName>/.uv-envs/code, invoked through absoluteUV_PROJECT_ENVIRONMENTanduv runfrom the active worktree. Create a separate stage environment only when dependencies, Python/CUDA stack, destructive package testing, or real concurrent sync risk requires it. - The paper component owns paper source, venue templates, submission modes, arXiv/public-source cleanup, camera-ready revisions, and paper worktrees.
- The reference component owns project-local sources (papers, collaborator docs, notes, specs, scripts, bundles), source cards, processing state, project-use notes, and source-to-project handoffs.
- Paper worktrees should not be nested inside
paper/by default. Use the sibling rootpaper-worktrees/for venue retargeting, arXiv releases, rebuttal paper edits, and camera-ready branches. - Paper source visibility is independent of venue. If
paper/mainis linked to Overleaf or visible to coauthors, treat it asauthor-visible, not private; keep agent-private files out of that branch. - Project memory stores durable cross-component state; root
docs/stores project-level design and planning artifacts; code docs store code-side implementation, run, and result details. - Root Git is optional. If enabled, do not accidentally commit nested component repos unless the user explicitly wants submodules.
- A GitHub Project is optional cloud coordination. It tracks collaborator-facing issues, PRs, blockers, and roadmap views across component repos; it does not replace root
memory/, component.agent/, or repo-native evidence docs. - Toolchain gates are explicit project policy. Code, paper, Git/GitHub, remote execution, release, and artifact workflows should record their check commands, mutation rules, and freshness expectations instead of relying on ad hoc agent memory.
Step 1 - Gather Project Information
Ask for these fields in one message:
- Project name and parent directory.
- Research summary: method idea, target problem, datasets, baselines, metrics, and current maturity.
- Target venue or milestone, if known.
- Component choices:
- paper repo: create new, connect existing, or skip for now
- code repo: create new, connect existing, or skip for now
- slides repo: create new, connect existing, or skip
- reference library: create
reference/, connect existing PDF/source folder, connect an initial source bundle, or skip - reviewer/rebuttal/artifact state dirs: create now or later
- Git policy:
- root control-plane git repo: yes/no
- component remotes for paper/code/slides, if available
- whether component repos should be submodules or ignored by root Git
- whether GitHub/GitLab repos should be created now, and if so whether
gh auth statusis valid - whether to create or link one GitHub Project board for this research project
- whether default toolchain gates should be enabled:
- code:
uv,ruff,mypy,pytest,pre-commit - paper:
tex-fmt,submit-paper, Overleaf/GitHub compile evidence - coordination:
git,gh, GitHub Project/PR checks - optional hygiene:
gitleaks,shellcheck,shfmt,actionlint,nbstripout,taplo,yamllint,lychee
- code:
- Worktree policy:
- default sibling root:
<ProjectName>/code-worktrees/ - default paper sibling root:
<ProjectName>/paper-worktrees/ - shared code uv environment path: default
<ProjectName>/.uv-envs/code - server worktree root, if different
- branch naming conventions, if any
- paper source visibility policy:
- whether
paper/mainis linked to Overleaf/GitHub - whether
paper/mainisauthor-visibleoragent-private - where
.agent/, AGENTS/CLAUDE guidance, raw CSVs, plotting scripts, and internal result docs should live
- whether
- default sibling root:
Wait for the user's answers before creating files.
Step 2 - Create the Control Root
Create:
<parent-dir>/<ProjectName>/
├── memory/
├── docs/overview.md
├── docs/designs/
├── docs/experiments/
├── docs/updates/
├── docs/audits/
├── docs/timelines/
├── reference/.agent/runs/
├── reference/sources/
├── reference/cards/
├── reference/project-use/
├── reference/notes/
├── reference/summaries/
├── reviewer/.agent/
├── rebuttal/.agent/
├── artifact/.agent/
├── .uv-envs/
├── code-worktrees/
└── paper-worktrees/
Create optional slides/ only when the user wants a slides component now.
If root Git is enabled, initialize it at <ProjectName>/ and add a root .gitignore that ignores component repos and worktrees unless the user explicitly wants submodules:
/paper/
/code/
/slides/
/.uv-envs/
/code-worktrees/
/paper-worktrees/
If the user wants submodules, use submodule commands deliberately rather than relying on accidental nested Git behavior.
If the user wants GitHub/GitLab repositories created during setup, first check the hosting CLI authentication such as gh auth status. If authentication fails, finish the local workspace setup and record Git remote creation as a blocker; do not let repo creation failure obscure the project initialization result.
If the user wants a GitHub Project board:
- Treat the board as optional cloud coordination for one research project across several repos.
- Before
gh project ...commands, checkgh auth status; if the token lacks theprojectscope, ask the user to approve or rungh auth refresh -s project. - If the agent runtime cannot access the macOS Keychain or GitHub API from the sandbox, record GitHub Project setup as a blocker instead of asking the user to repeatedly log in.
- Create or link the project only after the owner is clear: user account such as
@me/a-green-hand-jack, or an organization. - Link component repos to the board when appropriate, but keep the root repo and component repo remotes separate.
Useful CLI patterns:
gh project create --owner <owner> --title "<ProjectName>"
gh project view <number> --owner <owner>
gh project link <number> --owner <owner> --repo <owner>/<repo>
Recommended fields:
Component: root, code, paper, slides, reviewer, rebuttal, artifactWorkstream: method, experiment, writing, review, release, infraStatus: Backlog, Ready, In Progress, Blocked, Review, Done, ParkedPriority: P0, P1, P2, P3Target: venue, milestone, deadline, arXiv, camera-readyClaim ID,Evidence ID,Worktree,Blocker
Recommended views: Roadmap, Board, Experiments, Paper, Risks, and Worktrees.
Step 3 - Bootstrap Project Memory
Use research-project-memory templates or equivalent files to create:
memory/project.yamlmemory/component-index.yamlmemory/current-status.mdmemory/decision-log.mdmemory/claim-board.mdmemory/evidence-board.mdmemory/provenance-board.mdmemory/risk-board.mdmemory/action-board.mdmemory/handoff-board.mdmemory/phase-dashboard.mdmemory/source-visibility-board.md
The component index should record:
components:
code:
path: code
worktree_root: code-worktrees
worktree_index_path: code/.agent/worktree-index.md
shared_uv_environment: .uv-envs/code
owns:
- algorithm implementation
- experiment execution
- code-side result reports
- server execution state
paper:
path: paper
worktree_root: paper-worktrees
worktree_index_path: paper/.agent/worktree-index.md
default_visibility_tier: author-visible
source_visibility_board: memory/source-visibility-board.md
owns:
- paper claims and narrative
- figures and tables selected for submission
- venue/arXiv/camera-ready versions
- source visibility and cleanup policy
slides:
path: slides
status: optional
reviewer:
path: reviewer
rebuttal:
path: rebuttal
artifact:
path: artifact
Root memory should store pointers to code-side evidence, not duplicate detailed run logs.
Record default toolchain gates in memory/project.yaml:
toolchain_gates:
policy: check-before-mutate
code:
environment_check: "UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code uv sync"
format_check: "UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code uv run ruff format --check src tests experiments scripts"
lint_check: "UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code uv run ruff check src tests experiments scripts"
type_check: "UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code uv run mypy src"
test_check: "UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code uv run pytest tests -v"
local_gate_runner: "UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code uv run pre-commit run --all-files"
mutate_only_when_requested:
- "UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code uv run ruff format src tests experiments scripts"
- "UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code uv run ruff check --fix src tests experiments scripts"
optional_hygiene:
secret_scan: "gitleaks dir --no-banner --redact ."
shell_lint: "shellcheck jobs/*.sh scripts/*.sh"
shell_format_check: "shfmt -d jobs scripts"
notebook_output_check: "nbstripout --dry-run notebooks/*.ipynb"
github_actions_lint: "actionlint .github/workflows/*.yml"
toml_format_check: "taplo fmt --check pyproject.toml"
yaml_lint: "yamllint ."
link_check: "lychee --no-progress README.md docs/**/*.md"
paper:
source_format_check: "tex-fmt --check --nowrap --recursive ."
submission_check: "bash <submit-paper-skill-dir>/scripts/check.sh \"$PAPER_DIR\""
compile_truth: "Overleaf/GitHub or local LaTeX compile log"
mutate_only_when_requested:
- "tex-fmt --nowrap --recursive ."
coordination:
git_status_check: "git status --short --branch"
whitespace_check: "git diff --check"
github_auth_check: "gh auth status"
github_pr_check: "gh pr checks"
Preserve existing component-specific tools when connecting an existing repo. For example, if a code repo already uses black, isort, pyright, pre-commit, gitleaks, shellcheck, shfmt, actionlint, nbstripout, or CI-specific commands, record those actual commands instead of forcing the default scaffold policy. For non-ML repos, omit default paths such as experiments or scripts when they do not exist.
If a GitHub Project board exists, record it in memory/project.yaml:
github_project:
enabled: true
owner: <github-user-or-org>
title: <ProjectName>
number: <project-number>
url: <project-url>
sync_policy: issue-pr-links
scope_required: project
Use sync_policy: none when the board exists but agents should not manage it. Do not mirror private research rationale or hidden paper-review risks into GitHub fields unless the user explicitly wants that material visible there.
Step 4 - Create Root-Level Agent Guidance
Write both root agent entrypoints:
<ProjectName>/AGENTS.mdfor Codex and universal agent guidance<ProjectName>/CLAUDE.mdfor Claude Code compatibility
They should stay semantically aligned. Prefer either mirrored content or a short CLAUDE.md that tells Claude Code to follow AGENTS.md as the canonical project-control-root policy.
The root guidance must state:
- agents start from
<ProjectName>/unless a task is explicitly component-local - use
git -C code ...,git -C paper ..., andgit -C slides ...for component-repo inspection and repo-local commands - for routine final branch pushes after preflight, use
project-push <repo> <remote> <branch>instead of rawgit push,git -C <repo> push,cd <repo> && git push, or shell-wrapped push variants - code worktrees live under
code-worktrees/by default - paper worktrees live under
paper-worktrees/by default for venue, arXiv, and camera-ready versions - paper source visibility tiers are
agent-private,author-visible,anonymous-submission,public-preprint,camera-ready-public, andpublisher-artifact - if
paper/mainsyncs to Overleaf through GitHub, it isauthor-visible; do not put.agent/,AGENTS.md,CLAUDE.md, raw CSVs, internal result docs, plotting scripts, reviewer strategy, or private paths into that visible source - if
tex-fmtis installed, paper formatting gates usetex-fmt --check --nowrap --recursive .; runtex-fmt --nowrap --recursive .only when formatting is requested and review the diff before push/submission - code gates use
uv sync,uv run ruff format --check,uv run ruff check,uv run mypy src,uv run pytest tests -v, anduv run pre-commit run --all-fileswithUV_PROJECT_ENVIRONMENTpointing at the shared project-code env unless the code repo documents an existing alternative - optional hygiene gates include
gitleaks,shellcheck,shfmt,actionlint,nbstripout,taplo,yamllint, andlycheewhen the relevant files and tools exist - mutating format/fix commands such as
ruff format,ruff check --fix,shfmt -w,nbstripoutwithout--dry-run, andtex-fmtformat mode require an explicit request or documented project policy, followed by diff review - root
docs/is for project-level overviews, staged method designs, cross-component experiment plans, audits, timelines, and handoffs code/docs/is for code-side result summaries, run records, implementation reports, and server execution notes- experiment results live under
code/docs/results/,code/docs/reports/,code/docs/runs/, or the same paths inside a code worktree - raw outputs, logs, checkpoints, and wandb/tensorboard caches are not project-root artifacts
- paper version notes live in the relevant paper worktree
.agent/worktree-status.mdand durable decisions live in rootmemory/ - cross-worktree rollups live in
code/.agent/worktree-index.md,paper/.agent/worktree-index.md, and rootmemory/component-index.yaml - GitHub Project, when configured, is the collaborator-facing board for issues, PRs, blockers, targets, and roadmap views; root
memory/remains the durable research memory - arXiv/public-source paper worktrees must remove TODOs, internal comments, hidden figure/table descriptions, reviewer-response notes, and author-comment macros before source release
- author-visible Overleaf branches must exclude agent-private files even if the paper is not yet public
- anonymous conference paper worktrees must enforce venue anonymity and formatting rules
- project memory gets durable claim/evidence/provenance/risk/action/handoff summaries
- project memory tracks claim lifecycle, evidence provenance, cross-module handoffs, and phase dashboard state
- use
update-docsduring code changes, not only at release time - use
add-git-tagfor stable code, paper, artifact, or root milestones
Step 5 - Initialize or Connect Component Repos
Paper
If creating a new paper repo, use init-latex-project at:
<ProjectName>/paper/
If connecting an existing paper repo, clone or record its path and remote. Then inspect whether it is linked to Overleaf or visible to coauthors before creating or tracking agent-private files.
Ensure the paper workspace has both paper/AGENTS.md and paper/CLAUDE.md when agents will edit it, but treat these as agent-private guidance by default. If the active branch is author-visible, anonymous-submission, public-preprint, or camera-ready-public, keep these files untracked, ignored, or in an agent-private worktree rather than pushing them to the visible source. Keep them aligned with the same paper-local compile, venue, source hygiene, figure, table, and memory rules.
When tex-fmt is available, record it in the paper-local guidance as the source-format checker. Formatting status belongs with paper worktree/source-visibility state; it is not a substitute for Overleaf compile evidence.
Code
If creating a new code repo, use init-python-project at:
<ProjectName>/code/
For ML projects, ensure the code repo has:
code/AGENTS.md
code/CLAUDE.md
code/docs/results/
code/docs/reports/
code/docs/runs/
When initializing or connecting a code repo, record its toolchain gates in code/AGENTS.md, code/CLAUDE.md, and memory/project.yaml. In a project-control-root layout, default new-code gates should run with UV_PROJECT_ENVIRONMENT=<absolute-project-root>/.uv-envs/code so code/ and code-worktrees/* share the same dependency environment. Bare uv sync is fine only for standalone code repos or repos that explicitly choose per-worktree environments. If an existing repo already has CI, pre-commit, black, isort, pyright, gitleaks, shellcheck, shfmt, actionlint, nbstripout, or custom commands, preserve and document those commands.
If connecting an existing code repo, do not force a full scaffold. Add missing high-value memory/docs paths only after reporting gaps.
When the code repo is cloned from an upstream project, do not assume origin is writable. Record whether origin is upstream, a fork, or a newly created project repo, and keep it separate from the root control-plane repo remote.
Slides
If requested, create or connect:
<ProjectName>/slides/
Slides may be a separate git repo. Prefer using the external progress-slides template as the slides component instead of inventing a local scaffold:
git clone https://github.com/a-green-hand-jack/progress-slides.git <ProjectName>/slides
After cloning, inspect slides/README.md, slides/package.json, and the existing slide source files before editing. Use research-slide-deck-builder for deck structure, template-compatible source writing, preview/build commands, and slides/.agent/ story, audience, source-evidence, and stale-evidence notes.
Treat slides/ as a multi-deck workspace. Root and slides-local agent guidance should say that stable decks live under slides/decks/<YYYY-MM-DD>-<audience-or-purpose>-<slug>.md; slides/slides.md is only an active/default deck, staging file, or template sample. Record deck history in slides/.agent/deck-index.md, keep optional per-deck notes in slides/.agent/decks/<deck-id>.md, and run Slidev against the target deck file, for example npx slidev decks/2026-05-02-advisor-plan.md.
Step 6 - Establish Worktree Policy
Default code policy:
main code repo: <ProjectName>/code/
code worktree root: <ProjectName>/code-worktrees/
worktree path: <ProjectName>/code-worktrees/<branch-type>-<branch-name>/
Default paper policy:
main paper repo: <ProjectName>/paper/
paper worktree root: <ProjectName>/paper-worktrees/
worktree path: <ProjectName>/paper-worktrees/<version-type>-<venue-or-name>/
Use paper worktrees for:
- different conference targets with different templates or style files
- agent-private drafting when the main branch is Overleaf/coauthor-visible
- arXiv/preprint releases where LaTeX source may become public
- camera-ready versions after acceptance
- paper-only rebuttal edits that should not disturb the main submission branch
Paper version hygiene:
- agent-private: may contain
.agent/,AGENTS.md,CLAUDE.md, writing memory, provenance, internal result docs, CSVs, and plotting scripts; should not sync to visible remotes - author-visible / Overleaf: exclude
.agent/,AGENTS.md,CLAUDE.md, raw CSVs, internal result docs, plotting scripts, reviewer strategy, private paths, and agent-only notes - arXiv/public source: remove TODOs, internal figure/table descriptions in TeX comments, reviewer notes, hidden comments, author-comment macros, and anonymization leftovers
- anonymous conference: enforce anonymity, venue mode, and formatting; do not assume source comments are safe if source is uploaded
- camera-ready: de-anonymize, add acknowledgements/funding, close rebuttal promises, and remove draft-only notes
Record this in:
memory/project.yamlmemory/component-index.yamlmemory/source-visibility-board.md<ProjectName>/AGENTS.md<ProjectName>/CLAUDE.mdcode/docs/ops/current-status.mdwhen server execution is involved
If the execution server only has the code repo, record the server-specific worktree root in code/infra/remote-projects.yaml or code/docs/ops/current-status.md. Do not assume the server has paper/ or root project memory.
Step 7 - Write PROJECT.md
Create <ProjectName>/PROJECT.md from templates/PROJECT.md. Fill in <ProjectName>, the one-line description, and set the GitHub Project Board status to none, linked, or planned. All other sections are stable defaults — edit only when the project's component layout, visibility policy, or memory structure differs from the defaults.
Step 8 - Final Summary
Report:
Project initialized: <ProjectName>
Control root: <path>
Components:
paper: <created|connected|skipped>
code: <created|connected|skipped>
slides: <created|connected|skipped>
reviewer/rebuttal/artifact state: <created|deferred>
GitHub Project: <created|linked|deferred|not requested>
Toolchain gates: <configured|deferred|inherited from existing repos>
Code worktree root:
<ProjectName>/code-worktrees/
Paper worktree root:
<ProjectName>/paper-worktrees/
Next skills:
research-project-memory -> inspect or update project state
new-workspace -> create a code branch/worktree or paper version worktree
remote-project-control -> configure SSH/HPC execution for code
experiment-design-planner -> plan first experiment matrix
research-slide-deck-builder -> create progress/advisor/lab slides with progress-slides
Final Sanity Check
Before finishing:
- root agent guidance exists in both
AGENTS.mdandCLAUDE.md - component repos that agents edit have paired
AGENTS.mdandCLAUDE.md - root memory files exist or are explicitly deferred
paper/,code/, andslides/Git boundaries are clear- root and component Git remotes have been inspected separately when GitHub/GitLab setup is involved
gh auth statusor equivalent hosting CLI auth has been checked before attempting repo creation- GitHub Project setup is either recorded in
memory/project.yamlandPROJECT.md, or explicitly deferred as an action/blocker - toolchain gate defaults are recorded in
memory/project.yaml, or existing component-specific gates are documented as inherited ghtoken has theprojectscope beforegh project ...commands are attemptedcode-worktrees/policy is recordedpaper-worktrees/policy is recorded- paper source visibility policy is recorded, especially whether
paper/mainisauthor-visiblethrough Overleaf/GitHub - there is no top-level
experiments/directory unless the user explicitly requested it - root
docs/has a clear project-level role and is not confused withcode/docs/ - code-side evidence paths are inside
code/docs/ - component remotes and root Git policy are not ambiguous
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/a-green-hand-jack/ml-research-skills/project-init">View project-init on skillZs</a>