Set up a project¶

Paths in this document are relative to the Zolletta-MetaSkill project root.

Initialize a project for use with Zolletta-metaskill review skills. Setup creates the .zolletta-metaskill/ directory and writes settings.json with the project's language, tool availability, and configuration. Every other subcommand reads from this file.

Prerequisites¶

A project directory with source code to review

Steps¶

Step 1 — Run setup¶

/zolletta-metaskill setup

The setup procedure runs automatically when any subcommand is invoked and settings.json is missing. Can also run it explicitly.

Step 2 — What setup detects¶

Setup detects and records the following:

Detection	What it finds
Project language	Python, TypeScript, PHP, Go, Rust, Java, Ruby, C/C++
Docker container	Service name from `compose.yml` / `docker-compose.yml`
tokensave	Whether the tokensave MCP server is available
Acronyms	Project-specific acronyms extracted from `AGENTS.md`
Python tooling	ruff, pytest, ty, vulture, mypy, uv availability
Python config	Line length, target version, ruff/mypy/ty/pytest config from `pyproject.toml`
Python code-style rules	Configurable rule toggles for `python-code-style`
Python testing rules	Configurable rule toggles for `python-testing-style`
Documentation directory	Read from `documentation.dir` in `settings.json` (default `docs/`)

See settings-schema.md for the corresponding field names.

Step 3 — settings.json¶

Setup writes .zolletta-metaskill/settings.json with all detected values. The file is added to the user's global ~/.gitignore so it is not committed. The setup guard checks this file before every subcommand invocation and re-runs the pyproject extraction step if pyproject.toml has been modified since the last setup.

Step 4 — Verify¶

After setup, verify the configuration:

cat .zolletta-metaskill/settings.json

Check that:

language matches the project's primary language
container_name is correct (or null if no container)
tokensave_available is true if tokensave is installed
acronyms lists any project-specific acronyms extracted from AGENTS.md
python.tools.* objects have the correct available flags (Python projects)
python.tools.* has the correct configuration extracted from pyproject.toml (Python projects)

Re-running setup¶

Setup is idempotent. Re-running it preserves existing user-customized values in settings.json and only adds keys that are new. The setup guard automatically re-runs the pyproject extraction step (Step 6.5) when pyproject.toml changes, without re-running full setup.