Setup Agent Machine

---
name: setup-agent-machine
description: Set up a directory as an agent-ready machine context by interviewing the user, recording searchable directories in a YAML manifest, building an indexes/ directory of per-directory index files, and writing an AGENTS.md that tells any agent where to look and how to maintain its own indexes. Use when the user says /setup-agent-machine, "set up this machine for agents", "build an AGENTS.md for my directories", "index my directories for agents", or wants an agent to know where to search on this machine.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir:*, ls:*, date:*)
argument-hint: "[path ...]"
---

# Setup Agent Machine

Prepares the current directory as a standing context for coding agents by producing three artifacts: `agent-machine.yaml` (the manifest of directories worth searching), `indexes/` (one index file per directory, built by delegating to the `index-directory` skill), and `AGENTS.md` (the instructions that tell any future agent how to use and maintain those indexes).

The point is lookup speed and accuracy: given a prompt, an agent should read the indexes, decide which two or three directories are relevant, and search only there instead of guessing or scanning the whole machine.

## Prerequisites

- The current working directory is where the artifacts will be created.
- The user is available to answer interview questions (this skill is interactive; never invent paths).
- Any path given as arguments (`$1`, `$2`, ...) is treated as a pre-confirmed manifest entry.
- If `AGENTS.md` already exists in the directory, ask the user before modifying it.

## Path Semantics

Manifest entries are absolute paths in one of two forms:

- `/some/path`: index that specific directory as a single unit.
- `/some/path/*`: index each directory directly under `/some/path` separately, and index any directory that appears there later.

A path must exist when it is added. A `/*` path itself must also exist; only its children are expanded.

## Steps

### 1. Check existing state

Look for `AGENTS.md`, `agent-machine.yaml`, and `indexes/` in the current directory.

- If none exist, this is a fresh setup.
- If some exist, this is a re-run: load the manifest, treat its entries as confirmed, and plan to add new paths and rebuild only missing or stale indexes (an index is stale if its `Last indexed` date is older than 30 days or the user says the directory changed significantly).
- If `AGENTS.md` exists and was not generated by this skill (it lacks the `Agent machine context` marker), ask whether to append a generated section, overwrite it, or abort.

### 2. Interview the user

Collect the list of directories containing code or documents an agent may need to search.

1. Explain the two path forms from Path Semantics with one example of each.
2. Ask for paths in rounds. Each round accepts one or more paths plus an optional one-line description per path (for example, "blog content repo" or "meeting notes"). Confirm each round before moving on.
3. If arguments were provided, list them as already confirmed and ask only for additions.
4. Offer to suggest candidates only if the user asks; suggest by listing immediate subdirectories of common roots (`~/src`, `~/Documents`, `~/notes`) and let the user pick. Never add a suggested path without confirmation.
5. Verify every path exists (`ls`). Drop and report any that do not, unless the user corrects the path.
6. Stop when the user says they are done. An empty list is a valid outcome only if arguments were provided; otherwise ask once more before aborting.

### 3. Write the manifest

Write `agent-machine.yaml` in the current directory, preserving existing entries on re-run:

```yaml
# Directories agents should be able to search on this machine.
# A path without /* is indexed as one directory.
# A path ending in /* indexes each directory under it separately,
# including directories added later.
paths:
  - /home/tomzx/src/agents
  - /home/tomzx/notes/*
```

Add a `# ` comment line above each entry holding the user's one-line description when one was given.

### 4. Build the indexes

Create `indexes/` if missing. For every manifest entry, expand `/*` entries into concrete child directories.

Index each directory by running `skills/index-directory/SKILL.md`, passing the directory as `$1` and `indexes/<name>.md` as `$2`.
When the user gave a one-line description during the interview, include it in the index's "What it is" line.

On re-run, index a directory only if its index is missing or stale (`Last indexed` older than 30 days or the user says it changed significantly).

### 5. Write AGENTS.md

Write (or update the generated section of) `AGENTS.md` using this template, adjusting the artifact names if the user chose different ones:

```markdown
# Agent machine context

This directory is an agent context for this machine.

## Where things are

- `agent-machine.yaml` lists every directory you may search. A path ending in `/*` means each directory under it is indexed separately, including new ones.
- `indexes/` holds one index file per indexed directory, named after the directory path.

## How to decide where to look

1. Before searching broadly, list `indexes/` and read the index files whose "What it is" line could match the current task.
2. Pick at most three candidate directories, then search inside them (Grep, Glob, file reads) instead of scanning unrelated paths.
3. If no index matches the task, say so rather than searching the whole machine.

## Keeping the indexes current

- If a directory from the manifest has no index file, index it with the index-directory skill when available, otherwise look inside it and write `indexes/<name>.md` matching the format of the existing index files.
- If a new directory appears under a `/*` path, index it the first time a task touches it or you notice it.
- If a directory's content has changed enough that its index is wrong, update that index.
- Running /sync-agent-machine in this directory refreshes stale and missing indexes in one pass.
- Only `agent-machine.yaml` and `indexes/` are yours to edit. Ask before changing anything else, including this file.
```

On re-run, keep the user's customizations to the generated section only if the user explicitly asks; otherwise regenerate it.

### 6. Verify and report

1. Confirm every manifest path (expanded for `/*`) has an index file, and every index file's `Last indexed` line is today's date.
2. Confirm `AGENTS.md` references the real artifact names.
3. Report using the output format below.

## Output Format

```markdown
## Agent machine setup (<date>)

Directory: <cwd>

### Manifest
- agent-machine.yaml: created / updated (N paths: N single, N globbed)

### Indexes
- Created: N
- Refreshed: N
- Still current: N

| Index file | Directory |
|------------|-----------|
| indexes/<name>.md | <path> |

### AGENTS.md
- created / section appended / updated / left untouched (reason)

### Next steps
1. Run /sync-agent-machine in this directory to refresh stale and missing indexes.
2. Re-run /setup-agent-machine here whenever you want to add paths.
3. Copy this directory's setup to other machines by re-running the skill there.
```

## Example Usage

**Scenario 1: Fresh setup**
```
/setup-agent-machine
```
Interviews the user, records 5 paths (3 single, 2 globbed), looks inside each of the 19 resulting directories, writes 19 index files, and generates `AGENTS.md` pointing at the manifest and `indexes/`.

**Scenario 2: Adding directories later**
```
/setup-agent-machine ~/src/new-project
```
Detects the existing setup, confirms `~/src/new-project` as a new single path, appends it to `agent-machine.yaml`, builds only its index, and leaves existing indexes untouched.

**Scenario 3: Re-run to refresh**
```
/setup-agent-machine
```
Finds three indexes older than 30 days and one directory the user says changed. Refreshes those four indexes and regenerates the `AGENTS.md` section, reporting 15 still-current indexes.