init-python-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Initialize Python Project

初始化Python项目

Help the user create a production-ready Python project or upgrade an existing one without inlining large file bodies inside this skill. Use the bundled references and templates as the source of truth.

帮助用户创建可投入生产的Python项目或升级现有项目，无需在此skill中嵌入大段文件内容。请以附带的参考文档和模板为权威来源。

Skill Directory Layout

Skill目录结构

text

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── architecture.md
│   ├── new-project.md
│   ├── fork-enhancement.md
│   └── best-practices.md
├── scripts/
│   └── scaffold_new_project.py
├── template_manifest.json
└── templates/
    ├── common/
    │   ├── .gitignore
    │   ├── .env.example
    │   ├── README.md
    │   ├── CLAUDE.md
    │   ├── pyproject.toml.tmpl
    │   ├── tests/
    │   └── docs/
    └── ml/
        ├── .agent/
        ├── docs/
        ├── experiments/
        ├── infra/
        ├── eval/
        └── scripts/

text

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── architecture.md
│   ├── new-project.md
│   ├── fork-enhancement.md
│   └── best-practices.md
├── scripts/
│   └── scaffold_new_project.py
├── template_manifest.json
└── templates/
    ├── common/
    │   ├── .gitignore
    │   ├── .env.example
    │   ├── README.md
    │   ├── CLAUDE.md
    │   ├── pyproject.toml.tmpl
    │   ├── tests/
    │   └── docs/
    └── ml/
        ├── .agent/
        ├── docs/
        ├── experiments/
        ├── infra/
        ├── eval/
        └── scripts/

Progressive Loading

渐进式加载

Read only the references needed for the current path:

Always read
```
references/architecture.md
```
For new projects, read
```
references/new-project.md
```
For fork/enhancement work, read
```
references/fork-enhancement.md
```
If you need policy, tradeoff, or failure-handling guidance, read
```
references/best-practices.md
```

Use

templates/

as the source of truth for file contents instead of reproducing long inline snippets. Use

template_manifest.json

as the source of truth for which template groups and placeholders the scaffold supports.

仅读取当前流程所需的参考文档：

始终读取
```
references/architecture.md
```
若为新建项目，读取
```
references/new-project.md
```
若为复刻/优化工作，读取
```
references/fork-enhancement.md
```
若需要策略、权衡或故障处理指导，读取
```
references/best-practices.md
```

请以

templates/

作为文件内容的权威来源，而非重复生成冗长的内嵌代码片段。请以

template_manifest.json

作为脚手架支持的模板组和占位符的权威来源。

Step 1 — Gather Project Information

步骤1 — 收集项目信息

Ask the user in a single message:

Project type:
- ```
new
```
  — create a new project
- ```
fork
```
  — clone and enhance an existing repository
If
```
new
```
:
- Project name
- Package name (default: snake_case of project name)
- Short description
- Python version (default:
```
3.11
```
  )
- Project type:
```
ml
```
  ,
```
web
```
  ,
```
lib
```
  , or
```
general
```
If
```
fork
```
:
- GitHub repository URL
- Whether they want a fork workflow or just a local enhancement
For both:
- GitHub repository URL for the target repo, if available
- Author name and email

Wait for the answer before continuing.

通过一条消息询问用户：

项目类型：
- ```
new
```
  — 创建新项目
- ```
fork
```
  — 克隆并优化现有仓库
若为
```
new
```
：
- 项目名称
- 包名（默认：项目名称的蛇形命名法）
- 简短描述
- Python版本（默认：
```
3.11
```
  ）
- 项目类型：
```
ml
```
  、
```
web
```
  、
```
lib
```
  或
```
general
```
若为
```
fork
```
：
- GitHub仓库URL
- 是否需要复刻工作流还是仅本地优化
两种类型均需：
- 目标仓库的GitHub URL（如有）
- 作者姓名和邮箱

等待用户回复后再继续。

Step 2 — Choose the Execution Path

步骤2 — 选择执行流程

Path A: New Project

流程A：新建项目

Read

references/new-project.md

and

references/architecture.md

读取

references/new-project.md

和

references/architecture.md

。

2A.1 Create the project root

2A.1 创建项目根目录

bash

mkdir <project-name>
cd <project-name>
uv init --name <package_name> --python <version>

If the directory already exists, stop and ask whether to choose a new name or reuse it.

bash

mkdir <project-name>
cd <project-name>
uv init --name <package_name> --python <version>

若目录已存在，请停止操作并询问用户是选择新名称还是复用现有目录。

2A.2 Preferred path for

new + ml

2A.2

new + ml

项目的首选流程

For a new ML project, prefer the bundled scaffold script:

bash

python3 <installed-skill-dir>/scripts/scaffold_new_project.py \
  <target-dir> \
  --project-name <project-name> \
  --package-name <package-name> \
  --description "<short-description>" \
  --python-version <version> \
  --author-name "<author-name>" \
  --author-email "<author-email>" \
  --repo-url "<repo-url-or-TBD>"

The script handles:

```
uv init
```
source/test/docs directory creation
copying templates from
```
templates/common/
```
and
```
templates/ml/
```
placeholder replacement
creating
```
.env
```
bootstrapping remote-project memory files for local-to-remote workflows
writing
```
.gitkeep
```
files

After it completes, continue with install, verification, and git setup in Steps 2A.6 and 2A.7.

If the user wants a non-ML layout or the script is not suitable, fall back to the manual path below.

对于新建ML项目，优先使用附带的脚手架脚本：

bash

python3 <installed-skill-dir>/scripts/scaffold_new_project.py \
  <target-dir> \
  --project-name <project-name> \
  --package-name <package-name> \
  --description "<short-description>" \
  --python-version <version> \
  --author-name "<author-name>" \
  --author-email "<author-email>" \
  --repo-url "<repo-url-or-TBD>"

该脚本会处理以下内容：

```
uv init
```
创建源码/测试/文档目录
从
```
templates/common/
```
和
```
templates/ml/
```
复制模板
替换占位符
创建
```
.env
```
文件
为本地到远程工作流引导远程项目内存文件
写入
```
.gitkeep
```
文件

脚本执行完成后，继续执行步骤2A.6和2A.7中的安装、验证和Git设置。

若用户需要非ML项目结构或脚本不适用，请回退到下方的手动流程。

2A.3 Manual fallback: create the directory layout

2A.3 手动回退：创建目录结构

For

ml

projects, create the full four-layer structure from

references/architecture.md

At minimum, create:

bash

mkdir -p src/<package_name>/{models,data,utils}
mkdir -p tests/{data,outputs}
mkdir -p docs/outlines docs/dev/features docs/src docs/results docs/reports docs/runs
mkdir -p .vscode .cursor .claude/commands
touch src/<package_name>/__init__.py
touch src/<package_name>/models/__init__.py
touch src/<package_name>/data/__init__.py
touch src/<package_name>/utils/__init__.py
touch tests/__init__.py

For non-ML projects, keep the common project files but only create ML-specific directories if the user explicitly wants them.

对于

ml

项目，从

references/architecture.md

创建完整的四层结构。

至少创建以下目录：

bash

mkdir -p src/<package_name>/{models,data,utils}
mkdir -p tests/{data,outputs}
mkdir -p docs/outlines docs/dev/features docs/src docs/results docs/reports docs/runs
mkdir -p .vscode .cursor .claude/commands
touch src/<package_name>/__init__.py
touch src/<package_name>/models/__init__.py
touch src/<package_name>/data/__init__.py
touch src/<package_name>/utils/__init__.py
touch tests/__init__.py

对于非ML项目，保留通用项目文件，但仅在用户明确要求时才创建ML特定目录。

2A.4 Materialize templates

2A.4 实例化模板

Use the templates under

templates/

and replace placeholders:

```
{{PROJECT_NAME}}
```
```
{{PACKAGE_NAME}}
```
```
{{DESCRIPTION}}
```
```
{{PYTHON_VERSION}}
```
```
{{AUTHOR_NAME}}
```
```
{{AUTHOR_EMAIL}}
```
```
{{REPO_URL}}
```

Write these common files from

templates/common/

```
.gitignore
```
```
.env.example
```
```
README.md
```
```
CLAUDE.md
```
```
pyproject.toml
```
```
tests/conftest.py
```
```
docs/outlines/project_plan.md
```
```
docs/outlines/progress.md
```
```
docs/results/.gitkeep
```
```
docs/reports/.gitkeep
```
```
docs/runs/.gitkeep
```
```
docs/dev/feature_template.md
```
```
docs/src/dependencies.md
```
```
.vscode/settings.json
```

For

ml

projects, also write:

```
experiments/config.py
```
```
experiments/configs/base.yaml
```
```
infra/envs/local.yaml
```
```
infra/envs/cluster.yaml.example
```
```
infra/remote-projects.yaml
```
```
infra/README.md
```
```
docs/ops/current-status.md
```
```
docs/ops/decision-log.md
```
```
.agent/local-overrides.yaml
```
```
eval/baselines/README.md
```
```
scripts/train.py
```
```
scripts/download_data.py
```

Create

.env

as an empty file with a short comment header if it does not exist.

使用

templates/

下的模板并替换占位符：

```
{{PROJECT_NAME}}
```
```
{{PACKAGE_NAME}}
```
```
{{DESCRIPTION}}
```
```
{{PYTHON_VERSION}}
```
```
{{AUTHOR_NAME}}
```
```
{{AUTHOR_EMAIL}}
```
```
{{REPO_URL}}
```

从

templates/common/

写入以下通用文件：

```
.gitignore
```
```
.env.example
```
```
README.md
```
```
CLAUDE.md
```
```
pyproject.toml
```
```
tests/conftest.py
```
```
docs/outlines/project_plan.md
```
```
docs/outlines/progress.md
```
```
docs/results/.gitkeep
```
```
docs/reports/.gitkeep
```
```
docs/runs/.gitkeep
```
```
docs/dev/feature_template.md
```
```
docs/src/dependencies.md
```
```
.vscode/settings.json
```

对于

ml

项目，还需写入：

```
experiments/config.py
```
```
experiments/configs/base.yaml
```
```
infra/envs/local.yaml
```
```
infra/envs/cluster.yaml.example
```
```
infra/remote-projects.yaml
```
```
infra/README.md
```
```
docs/ops/current-status.md
```
```
docs/ops/decision-log.md
```
```
.agent/local-overrides.yaml
```
```
eval/baselines/README.md
```
```
scripts/train.py
```
```
scripts/download_data.py
```

若

.env

文件不存在，则创建一个带简短注释头的空文件。

2A.5 Add placeholder files for empty directories

2A.5 为空目录添加占位文件

Use

.gitkeep

where needed so empty directories are tracked:

bash

touch experiments/configs/.gitkeep
touch eval/benchmarks/.gitkeep
touch eval/baselines/reproduced/.gitkeep
touch infra/submit/slurm/.gitkeep
touch docs/results/.gitkeep
touch docs/reports/.gitkeep
touch docs/runs/.gitkeep
touch tests/data/.gitkeep
touch tests/outputs/.gitkeep

Only create placeholders for directories that actually exist in the chosen project type.

在需要的地方使用

.gitkeep

以便追踪空目录：

bash

touch experiments/configs/.gitkeep
touch eval/benchmarks/.gitkeep
touch eval/baselines/reproduced/.gitkeep
touch infra/submit/slurm/.gitkeep
touch docs/results/.gitkeep
touch docs/reports/.gitkeep
touch docs/runs/.gitkeep
touch tests/data/.gitkeep
touch tests/outputs/.gitkeep

仅为所选项目类型中实际存在的目录创建占位文件。

2A.6 Install and verify

2A.6 安装与验证

For ML projects:

bash

uv pip install -e ".[dev,ml]"

For non-ML projects:

bash

uv pip install -e ".[dev]"

Run an initial test:

bash

pytest tests/ -v

If there are no tests yet, create a placeholder test and rerun:

bash

cat > tests/test_placeholder.py <<'EOF'
def test_placeholder():
    assert True
EOF
pytest tests/

对于ML项目：

bash

uv pip install -e ".[dev,ml]"

对于非ML项目：

bash

uv pip install -e ".[dev]"

运行初始测试：

bash

pytest tests/ -v

若尚无测试用例，请创建一个占位测试并重新运行：

bash

cat > tests/test_placeholder.py <<'EOF'
def test_placeholder():
    assert True
EOF
pytest tests/

2A.7 Initialize git and optional remote

2A.7 初始化Git及可选远程仓库

bash

git rev-parse --git-dir >/dev/null 2>&1 || git init
git add .
git commit -m "Initial Python project structure"

If the user provided a GitHub URL, add

origin

, show

git remote -v

, and ask before pushing:

bash

git remote add origin <github-ssh-url>
CURRENT_BRANCH="$(git branch --show-current)"
git push -u origin "$CURRENT_BRANCH"

bash

git rev-parse --git-dir >/dev/null 2>&1 || git init
git add .
git commit -m "Initial Python project structure"

若用户提供了GitHub URL，添加

origin

，显示

git remote -v

，并在推送前询问用户：

bash

git remote add origin <github-ssh-url>
CURRENT_BRANCH="$(git branch --show-current)"
git push -u origin "$CURRENT_BRANCH"

Path B: Fork / Existing Project

流程B：复刻/现有项目

Read

references/fork-enhancement.md

references/architecture.md

, and

references/best-practices.md

读取

references/fork-enhancement.md

、

references/architecture.md

和

references/best-practices.md

。

2B.1 Clone and inspect

2B.1 克隆与检查

bash

git clone <github-ssh-url> <project-name>
cd <project-name>
ls -la

Check for:

```
pyproject.toml
```
,
```
setup.py
```
,
```
requirements.txt
```
```
src/
```
,
```
tests/
```
,
```
docs/
```
,
```
scripts/
```

.env.example

CLAUDE.md

.vscode/settings.json

bash

git clone <github-ssh-url> <project-name>
cd <project-name>
ls -la

检查以下内容：

```
pyproject.toml
```
、
```
setup.py
```
、
```
requirements.txt
```
```
src/
```
、
```
tests/
```
、
```
docs/
```
、
```
scripts/
```

.env.example

、

CLAUDE.md

、

.vscode/settings.json

2B.2 Report gaps before bulk edits

2B.2 在批量编辑前报告缺失项

Produce a concise report showing:

Existing structure
Missing high-value components
Whether the repo is already installable
Whether docs/test isolation are missing

Then ask whether to:

Add all missing components
Add only selected components
Generate a checklist without editing

生成一份简洁报告，包含：

现有结构
缺失的高价值组件
仓库是否已可安装
是否缺少文档/测试隔离

然后询问用户是否：

添加所有缺失组件
仅添加选定组件
生成检查清单但不进行编辑

2B.3 Add only missing components

2B.3 仅添加缺失组件

When the user approves edits, use the templates under

templates/common/

to fill gaps:

```
.env.example
```
```
CLAUDE.md
```
```
tests/conftest.py
```
docs templates
```
.vscode/settings.json
```
```
pyproject.toml
```
if migrating from
```
requirements.txt
```

Do not force the full ML layout onto an existing repo unless the user explicitly wants that migration.

当用户批准编辑后，使用

templates/common/

下的模板填补缺失项：

```
.env.example
```
```
CLAUDE.md
```
```
tests/conftest.py
```
文档模板
```
.vscode/settings.json
```
若从
```
requirements.txt
```
迁移，则添加
```
pyproject.toml
```

除非用户明确要求迁移，否则不要将完整ML结构强制应用到现有仓库。

Template Application Rules

模板应用规则

Keep existing substantial files when they are already good enough.
Prefer surgical edits over overwriting.
For templated files, replace placeholders consistently.
If a template is only partially relevant, copy the relevant sections instead of dumping the whole file verbatim.

若现有重要文件已足够完善，则保留它们。
优先进行精准编辑而非覆盖整个文件。
对于模板文件，统一替换占位符。
若模板仅部分相关，则复制相关部分而非完整粘贴整个文件。

Final Summary

最终总结

Report:

text

✓ Python project initialized or enhanced: <project-name>
✓ Project type: <new|fork> / <ml|web|lib|general>
✓ Common scaffolding applied
✓ UV environment configured
✓ Git status: initialized / existing repo reused
✓ Remote: <configured or skipped>

Project location: <full-path>

Next steps:
1. cd <project-name>
2. cp .env.example .env
3. Fill in project-specific settings
4. Start implementing in src/<package_name>/
5. Put stable experiment summaries in docs/results/, reports in docs/reports/, and run pointers in docs/runs/
6. Run pytest before the next commit

报告内容：

text

✓ Python项目已初始化或优化：<project-name>
✓ 项目类型：<new|fork> / <ml|web|lib|general>
✓ 已应用通用脚手架
✓ UV环境已配置
✓ Git状态：已初始化 / 复用现有仓库
✓ 远程仓库：<已配置或已跳过>

项目位置：<完整路径>

下一步操作：
1. cd <project-name>
2. cp .env.example .env
3. 填写项目特定设置
4. 在src/<package_name>/中开始实现功能
5. 将稳定的实验摘要放入docs/results/，报告放入docs/reports/，运行指针放入docs/runs/
6. 下次提交前运行pytest

Important Notes

重要说明

Use
```
references/best-practices.md
```
when you hit edge cases.
Keep this
```
SKILL.md
```
focused on orchestration; the detailed file content should live in
```
templates/
```
and
```
references/
```
.
```
experiments/
```
is runnable experiment logic, not a result archive. Raw outputs, checkpoints, logs, and wandb/tensorboard caches should stay in ignored paths or external storage, with small pointers in
```
docs/runs/
```
.
When this code repo belongs to a project control root, prefer sibling code worktrees under
```
<ProjectName>/code-worktrees/
```
instead of nested worktrees inside
```
code/
```
.

遇到边缘情况时，请使用
```
references/best-practices.md
```
。
请保持此
```
SKILL.md
```
聚焦于流程编排；详细文件内容应存放在
```
templates/
```
和
```
references/
```
中。
```
experiments/
```
用于存放可运行的实验逻辑，而非结果归档。原始输出、检查点、日志以及wandb/tensorboard缓存应存放在忽略路径或外部存储中，并在
```
docs/runs/
```
中放置小型指针。
当此代码仓库属于项目控制根目录时，优先在
```
<ProjectName>/code-worktrees/
```
下创建同级代码工作树，而非在
```
code/
```
内嵌套工作树。

init-python-project

Original

Translation

Initialize Python Project

初始化Python项目

Skill Directory Layout

Skill目录结构

Progressive Loading

渐进式加载

Step 1 — Gather Project Information

步骤1 — 收集项目信息

Step 2 — Choose the Execution Path

步骤2 — 选择执行流程

Path A: New Project

流程A：新建项目

2A.1 Create the project root

2A.1 创建项目根目录

2A.2 Preferred path for new + ml

2A.2 new + ml项目的首选流程

2A.3 Manual fallback: create the directory layout

2A.3 手动回退：创建目录结构

2A.4 Materialize templates

2A.4 实例化模板

2A.5 Add placeholder files for empty directories

2A.5 为空目录添加占位文件

2A.6 Install and verify

2A.6 安装与验证

2A.7 Initialize git and optional remote

2A.7 初始化Git及可选远程仓库

Path B: Fork / Existing Project

流程B：复刻/现有项目

2B.1 Clone and inspect

2B.1 克隆与检查

2B.2 Report gaps before bulk edits

2B.2 在批量编辑前报告缺失项

2B.3 Add only missing components

2B.3 仅添加缺失组件

Template Application Rules

模板应用规则

Final Summary

最终总结

Important Notes

重要说明

2A.2 Preferred path for
`new + ml`

2A.2
`new + ml`
项目的首选流程