AgentSkillsCN

quarto-survey-setup

Quarto 问卷分析项目的环境搭建。从零开始配置 uv + Quarto + Typst PDF 流程。“创建问卷分析项目”、“survey project setup”等请求中使用。

SKILL.md
--- frontmatter
name: quarto-survey-setup
description: Quarto アンケート分析プロジェクトの環境構築。uv + Quarto + Typst PDF パイプラインをゼロからセットアップする。「アンケート分析プロジェクトを作成」「survey project setup」などのリクエストで使用する。
disable-model-invocation: true
argument-hint: "[project-name]"

Quarto アンケート分析プロジェクト環境構築

CSV アンケートデータを分析するための Quarto + Python プロジェクトをゼロから構築する。

目次

  1. •前提チェック
  2. •ディレクトリ構成作成
  3. •pyproject.toml 生成
  4. •_quarto.yml 生成
  5. •WSL検出・.mise.toml 生成
  6. •.gitignore/.python-version 生成
  7. •uv sync
  8. •CLAUDE.md 生成

進捗チェックリスト

code
- [ ] Step 1: 前提チェック（uv, quarto）
- [ ] Step 2: ディレクトリ構成作成
- [ ] Step 3: pyproject.toml + run_commands.py 生成
- [ ] Step 4: _quarto.yml 生成
- [ ] Step 5: WSL検出・.mise.toml 生成（該当時）
- [ ] Step 6: .gitignore, .python-version 生成
- [ ] Step 7: uv sync 実行
- [ ] Step 8: CLAUDE.md 生成

ステップ1: 前提チェック

uv と quarto の存在を確認する。いずれかが存在しない場合、インストール手順を案内して中断する。

bash
uv --version
quarto --version

ステップ2: ディレクトリ構成作成

引数 [project-name] をディレクトリ名として使用する。既にプロジェクトディレクトリにいる場合はカレントディレクトリを使う。

bash
mkdir -p data output/figures output/tables

ステップ3: pyproject.toml 生成

{project-name} を実際のプロジェクト名に置換して作成する:

toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["."]

[project]
name = "{project-name}"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "pandas>=2.2",
    "matplotlib>=3.9",
    "matplotlib-fontja>=1.1",
    "jupyter>=1.0",
    "ipykernel>=6.29",
    "nbformat>=5.10",
    "nbclient>=0.10",
    "python-pptx>=1.0",
]

[project.scripts]
render = "run_commands:render"
preview = "run_commands:preview"

同時に run_commands.py をプロジェクトルートにコピーする:

bash
cp "$SKILL_ROOT/scripts/run_commands.py" .

ステップ4: _quarto.yml 生成

日本語 Typst PDF 出力用の Quarto 設定を作成する:

yaml
project:
  title: "{project-name}"
  type: default
  output-dir: output
  preview:
    port: 4200

format:
  typst:
    toc: true
    toc-depth: 3
    number-sections: true
    mainfont: "Yu Gothic"
    fontsize: 10pt
    papersize: a4
    margin:
      x: 2cm
      y: 2cm
    lang: ja
    columns: 1

execute:
  echo: false
  warning: false

ステップ5: WSL 検出と .mise.toml 生成

WSL 環境（パスが /mnt/ で始まる）では、venv をユーザーディレクトリに配置する。Windows ファイルシステム上の venv はパフォーマンスが著しく低下するため。

bash
pwd | grep -q "^/mnt/" && echo "WSL" || echo "native"

WSL の場合、.mise.toml を作成する:

toml
[env]
_.python.venv = "{{env.HOME}}/.venvs/{project-name}"
UV_PROJECT_ENVIRONMENT = "{{env.HOME}}/.venvs/{project-name}"

ネイティブ Linux / macOS の場合、.mise.toml は不要（デフォルトの .venv/ を使用）。

ステップ6: .gitignore と .python-version 生成

.gitignore:

code
# Output
output/

# Python
__pycache__/
*.pyc
.venv/

# Quarto
.quarto/
/.quarto/

# Jupyter
.ipynb_checkpoints/

.python-version:

code
3.13

ステップ7: uv sync 実行

bash
uv sync

mise を使用している場合は先に mise trust を実行:

bash
mise trust && uv sync

ステップ8: CLAUDE.md 生成

$SKILL_ROOT/templates/CLAUDE.md を参考に、プロジェクト固有の CLAUDE.md を作成する。テンプレート内の汎用記述をプロジェクトの実情に合わせて調整する。

bash
# テンプレートを確認
cat "$SKILL_ROOT/templates/CLAUDE.md"

完了確認

以下をユーザーに報告する:

  1. •作成されたファイル一覧
  2. •uv sync の成否
  3. •次のステップ: data/ に CSV を配置し、/survey-report-builder でレポート構築

注意事項

  • •Jupyter カーネルはカスタム名を使わず python3 に自動解決させる（ポータブル性のため）
  • •WSL 環境では必ず venv をユーザーディレクトリに逃がす
  • •uv run render / uv run preview がすぐ使えることを確認する
  • •output/ ディレクトリは .gitignore に含める