# Setup

> Personalize or upgrade an Agent-OS instance only when the user explicitly invokes setup. Preview all writes, preserve fictional examples unless removal is approved, and never overwrite global runtime or third-party skill configuration.

- Skill: `aylee/setup` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add aylee/setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aylee/setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: aylee (https://skillmd.com/u/aylee)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aylee/setup

---


# Set up Agent-OS

## Safety preflight

1. Read `agent-os.yaml`, `README.md`, `docs/setup-contract.md`, and current identity/area/binder files.
2. Detect whether setup is fresh, partial, or an upgrade. If personal data already exists, create or request an out-of-band backup before bulk changes.
3. If a public upstream Git remote exists, warn before writing personal information and recommend a private copy or private fork. Git itself is optional.
4. Preview every file to create, update, tombstone, or leave untouched. Obtain confirmation before deleting or replacing examples.

## Personalize

- Gather the exact initializer answers first: instance name, profile name, owner display name, IANA timezone, and zero to ten active projects with stable slug, purpose, and start date.
- Run the deterministic initializer in preview mode. Show its exact operations and token, then apply only after confirmation. The helper generates the instance UUID.
- Update setup-owned files only. Create binders from `library/templates/binder.md` and link each active project to a compact workstream.
- After the minimal instance validates, offer separate previewed passes for role, voice, and area context; do not make them prerequisites for initialization.
- Put credentials, raw transcripts, caches, indexes, and private integration configuration in the external local-state directory keyed by the instance UUID. Never place them under the portable root, even if ignored by Git.
- Treat integrations and tooling as optional capabilities with a documented manual fallback.

Finish with changed paths, skipped choices, validation results, backup location, and the first recommended action. Do not install global skills, symlink runtime settings, run package managers, or commit unless separately authorized.