Agent Folder Scaffold

---
name: agent-folder-scaffold
description: Set up an AI agent's folder from nothing — the six-step build and the official layout that agents perform best on, from empty directory to working skeleton. Use when asked to set up an agent, create an agent folder, start a new agent project, structure a Claude Code project, fix a messy agent directory, or someone says 'where do I even start building an agent'. For the driver file's content, see claude-md-writer. For the secret keys, see env-and-keys-setup.
metadata:
  version: 1.0.0
---

# Agent folder scaffold

Every agent in the course starts the same way: **six steps, in order**, building
the empty skeleton before any skill is written. AI agents perform best on the
official layout — the structure is not tidiness, it is how the agent finds what
it needs at the moment it needs it and nothing sooner.

## Before you start

| Input | Why |
| --- | --- |
| The agent's one job | Names the folder and scopes everything in it |
| Which skills the workflow needs | Their folders are part of the skeleton |
| Which secrets the job requires | .env and .gitignore are created together, in the same breath |

## Step 1 — The six steps, in order

1. **Create an empty folder.** `lowercase-hyphen`, no spaces — `seo-agent`,
   `bulk-ads-agent`. This one folder is the agent's entire home: instructions,
   skills, keys, drafts, and output all live inside it.
2. **Open it in your workspace** (File → Open Folder). This is the cockpit where
   you talk to the agent and watch every file it writes.
3. **Start Claude Code and choose the model** — before you begin, so cost is
   controlled from the first token (see model-picker).
4. **Build the official structure** (step 2 below). Skeleton now, contents later.
5. **Create `.env` and `.gitignore` together.** `.env` goes on the first line of
   `.gitignore` in the same breath — one accidental push of a live password and
   someone else owns your accounts.
6. **Write `CLAUDE.md`** — the driver, read first every session, under 200 lines
   (see claude-md-writer).

## Step 2 — The official anatomy

```
<agent-name>/
  CLAUDE.md                # the driver, loaded every session, under 200 lines
  .env                     # every secret key
  .gitignore               # first line: .env — then drafts/, __pycache__/, *.log, .DS_Store
  .mcp.json                # MCP servers for this project (only what this job needs)
  requirements.txt         # if scripts need packages
  README.md                # human setup guide, not read by the agent
  .claude/
    settings.local.json    # which MCP servers are enabled here
    skills/
      <skill-name>/SKILL.md      # one job each, + helper files alongside
    commands/              # reusable slash commands
  drafts/                  # work in progress (gitignored)
  output/                  # deliverables + the registry
```

## Step 3 — Understand why each file loads when it does

| File | When it loads | What it must contain |
| --- | --- | --- |
| CLAUDE.md | Every session, always | Who you are, workflow order, rules that never break. Nothing task-specific |
| SKILL.md | Only when that job comes up | The full procedure for one job |
| Helper files | Only when the skill reads them | Deep detail that would bloat the skill |
| .env | Read at runtime by scripts | Keys only. Never a value hardcoded in a skill |

Progressive disclosure in one line: *the agent should carry the smallest possible
amount of context until the moment it needs more.*

## Step 4 — Add the three files students always forget

1. **`.gitignore`** — first line `.env`, then `drafts/`, `__pycache__/`, `*.log`,
   `.DS_Store`.
2. **`.mcp.json`** — project-level beats global, so the agent behaves the same on
   every machine in the team.
3. **`output/<registry>.md`** — the running log of what the agent has produced.
   This is the agent's memory of its own work (see agent-memory-designer).

## Output

```
# Scaffold: <agent-name>/

Six steps: folder ✓ · opened ✓ · model chosen: <model> ✓ ·
           structure ✓ · .env + .gitignore together ✓ · CLAUDE.md ✓
Skills stubbed: <list, one folder each>
.gitignore first line: .env ✓
Registry: output/<name>-registry.md created empty ✓
Next: fill CLAUDE.md (claude-md-writer), then the first skill (skill-writer)
```

## When it breaks

| What you see | What it means | The fix |
| --- | --- | --- |
| Agent can't find its instructions | Files scattered outside the one folder | Everything lives inside the agent's home directory |
| A key appears on GitHub | .env created without .gitignore in the same breath | Step 5 is one step, not two; rotate the leaked key now |
| Agent behaves differently per machine | MCP config global, not project | .mcp.json in the project; project-level beats global |
| Every task is slow and expensive | Task detail loaded every session | The when-it-loads table; push detail down to skills |
| Folder name breaks tooling | Spaces or capitals in the name | lowercase-hyphen, no spaces |
| Agent re-does finished work | No registry of its own output | output registry from day one |
| Skills exist but never fire | Wrong location | Skills live at .claude/skills/<name>/SKILL.md exactly |

Never start writing skills into an unstructured folder to save setup time. The
layout is what makes every later file load at the right moment — retrofitting it
costs more than the six steps ever did.

## Rules

- **Six steps, in the given order**, because each step assumes the previous —
  the model choice belongs before the first token, the structure before the
  first skill.
- **.env and .gitignore are born together**, because the gap between them is
  exactly when credentials leak.
- **One folder is the whole home**, because an agent that reads outside its
  folder is an agent you cannot reason about or hand to anyone else.
- **Nothing loads sooner than needed**, because a 3,000-line always-loaded
  context makes every task slower, pricier, and less accurate.
- **The registry exists from day one**, because memory added later starts empty
  exactly when it was needed most.

## Related skills

- **claude-md-writer** — step 6's file, in full.
- **env-and-keys-setup** — what goes into .env and how each key is obtained.
- **skill-writer** — filling the .claude/skills/ folders.
- **model-picker** — step 3's choice.
- **agent-memory-designer** — the registry the scaffold creates empty.