/new-app

name: new-app
description: Scaffold a new Atomic Agents project from scratch — create the directory, `pyproject.toml`, env file, first agent, and a runnable entry point. Use when the user asks to start a new atomic-agents project from scratch, says "scaffold" / "new project" / "start from zero", or runs `/atomic-agents:new-app`.
disable-model-invocation: true
argument-hint: "[project-name]"

New Atomic Agents Project

Scaffold a fresh Atomic Agents project. The result is a single-package Python project with one working agent, one schema pair, a provider-wrapped client, and a runnable `main.py`.

This skill is opinionated. Produce a complete, tested skeleton the user can run immediately.

Phase 1 — Interrogate

Ask these questions in one message, not one-at-a-time. Skip any the user already answered (including via `$ARGUMENTS`).

1. **Project name** — used as both directory name and package name. Default from `$ARGUMENTS` if provided. Normalize to `kebab-case` for the directory and `snake_case` for the package. 2. **LLM provider** — OpenAI / Anthropic / Groq / Ollama / Gemini / OpenRouter / MiniMax. Default: OpenAI. 3. **Agent type** — a rough one-liner. Shapes the default `SystemPromptGenerator` content and the starter schema pair. Defaults to a generic chat agent. 4. **Tooling** — `uv` (default, because the repo uses uv) or `pip + venv`.

Do not ask about project layout, Python version, or dependency list. Pick them.

Phase 2 — Confirm the plan

State the plan in one short block and wait for a yes. Include:

• Directory: `<project-name>/`
• Package: `<project_name>/`
• Python: `>=3.12` (Atomic Agents uses PEP 695 generics)
• Dependencies: `atomic-agents>=2.7`, `instructor[<provider-extra>]>=1.14`, `python-dotenv`, `rich`
• Dev dependencies: `pytest`, `pytest-asyncio`, `ruff`
• First agent: `<agent-type>` — uses `BasicChatInputSchema`/`BasicChatOutputSchema` unless the agent type calls for custom schemas
• Default model for the chosen provider (see `framework/references/providers.md`)
• Entry point: `main.py` with a REPL

Phase 3 — Scaffold

Create files in this order. Verify each step before proceeding.

Directory and package

<project-name>/
├── pyproject.toml
├── .env.example
├── .gitignore
├── README.md
├── AGENTS.md
├── CLAUDE.md
└── <project_name>/
    ├── __init__.py
    └── main.py

`pyproject.toml`

Use the template from `framework/references/project-structure.md`, substituting the chosen provider extra and project name.

`.env.example`

Include the provider's API-key variable with a placeholder. Never the real key.

`.gitignore`

Use the template from `framework/references/project-structure.md`.

`<project_name>/main.py`

Produce a runnable REPL. Load `.env`, instantiate the provider client per `framework/references/providers.md`, build an agent, wire a `ChatHistory` with a seed assistant message, loop on `console.input(...)`.

For the agent itself, follow the workflow from the `atomic-agents:create-atomic-agent` skill — same canonical imports, same per-provider `mode` matrix, same `SystemPromptGenerator` shape.

When a custom agent type was requested, build custom `InputSchema` / `OutputSchema` subclasses with field `description=` populated, following the `atomic-agents:create-atomic-schema` skill. Otherwise use `BasicChatInputSchema` / `BasicChatOutputSchema`.

Always use the canonical imports:

from atomic_agents import (
    AtomicAgent, AgentConfig,
    BasicChatInputSchema, BasicChatOutputSchema,
)
from atomic_agents.context import ChatHistory, SystemPromptGenerator
from instructor import Mode

Per-provider AgentConfig knobs — match the Instructor factory mode on `AgentConfig.mode`:

• **OpenAI**: defaults work. Omit `mode` (or set `Mode.TOOLS`).
• **Anthropic**: `mode=Mode.TOOLS`; include `max_tokens` in `model_api_parameters`.
• **Groq / Ollama / MiniMax**: `mode=Mode.JSON` (Instructor factory also uses `Mode.JSON`).
• **Gemini**: `assistant_role="model"` and `mode=Mode.GENAI_TOOLS` (Instructor factory uses `Mode.GENAI_TOOLS`).
• **OpenRouter**: `mode=Mode.TOOLS`.

`README.md`

Short. Include: what the project is, how to install (`uv sync` or `pip install -e .[dev]`), how to set the API key (`cp .env.example .env` and edit), how to run (`uv run python -m <project_name>.main` or equivalent).

`AGENTS.md` and `CLAUDE.md`

Every scaffolded project ships agent instructions so any coding assistant (Cursor, Codex, Copilot, Gemini CLI, ...) knows the framework conventions from the first commit. `CLAUDE.md` contains exactly one line — `@AGENTS.md` — so Claude Code reads the same file without duplication.

`AGENTS.md` template (substitute project specifics):

# <Project Name>

<One-line description from the agent-type answer.>

Built with [Atomic Agents](https://github.com/eigenwise/atomic-agents) — a schema-driven
framework on Instructor + Pydantic. Docs for LLMs:
https://eigenwise.github.io/atomic-agents/llms.txt

## Framework conventions

- Import from the top-level package: `from atomic_agents import AtomicAgent, AgentConfig,
  BaseIOSchema, BaseTool`; context pieces from `atomic_agents.context`.
- Agents are `AtomicAgent[InputSchema, OutputSchema](config=AgentConfig(...))` — the type
  parameters carry runtime information, keep them accurate.
- The LLM client must be wrapped with Instructor before it goes into `AgentConfig.client`.
- Every `BaseIOSchema` subclass needs a non-empty docstring and `Field(..., description=...)`
  on each field — both flow into the LLM prompt.
- Provider knobs (`temperature`, `max_tokens`, ...) go in `AgentConfig.model_api_parameters`.
- Provider: <chosen provider>. <Provider-specific line from the matrix below, if any.>

## Commands

- Install: `uv sync` (or the pip equivalent chosen at scaffold time)
- Run: `uv run python -m <project_name>.main`
- Test: `uv run pytest`

Provider-specific lines for the template: Anthropic → "Requires `max_tokens` in `model_api_