Getting Started

You just downloaded Agent-Mask. Here's how to get your agent running.

Installation

Claude Code

Unzip the download and copy the three .md skill files into your Claude Code custom skills directory (typically ~/.claude/skills/or your project's skills folder)
Open Claude Code and run /hydrate — you should see Agent-Mask ask for your workspace path
Point it at your agent workspace directory (the folder with your SOUL.md, IDENTITY.md, etc.)
That's it. Your agent is live in the session.

ChatGPT / Codex

Unzip and place the skill files in your Codex project's skills directory
Reference them in your agent configuration or Codex skill registry
Invoke the hydrate skill by name or trigger phrase to load your agent

If you struggle with any of these steps, just ask Claude or Codex to install the skills themselves by dragging and dropping the downloaded files into the prompt.

The three skills

/hydrate— Load your agent into the current session

Reads your agent workspace in a specific order: AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, BUSINESS.md, TASKS.md, HEARTBEAT.md, TEAM.md, MEMORY.md, then the last two daily memory files.
Adopts the agent's tone, priorities, and operating rules for the rest of the session.
Starts persisting automatically — creates a session transcript and daily memory file.
On first run, asks for your workspace path and saves it to ~/.agent-mask/config.json so you don't have to enter it again.

> /hydrate

Agent hydrated: david-a
Workspace: ~/agents/david-a/workspace
Memory: warm (loaded 2 daily files, 14 durable entries)
Session: sessions/2026-04-04-143022-claude-skill-agent-mask.md

Ready. What are we working on?

/shutdown— End the session and persist everything

Finds the current session transcript and appends any conversation turns not yet recorded.
Updates today's daily memory with carry-forward context — decisions, handoff notes, open questions.
Promotes only clearly durable facts to MEMORY.md (stable preferences, standing instructions, long-lived decisions).
Can also update SOUL.md or AGENTS.md if the session materially changed the agent's behavioral contract.
Reports exactly what was written and where.

> /shutdown

Session ended for david-a
Workspace: ~/agents/david-a/workspace
Transcript: sessions/2026-04-04-143022-claude-skill-agent-mask.md (appended 12 turns)
Daily memory: memory/2026-04-04.md (updated with carry-forward notes)
Durable promotion: added 1 entry to MEMORY.md (new standing preference)
No secrets persisted.

/create-workspace— Scaffold a new agent from a role brief

Give it a name, a role, and a sentence about personality. It infers the rest — mission, philosophy, communication protocols, authorization model.
Creates SOUL.md (rich operating identity), IDENTITY.md (canonical metadata), HEARTBEAT.md (wake behavior), AGENTS.md (workspace contract), MEMORY.md (starter), and directory structure.
Optionally creates shared context files: USER.md, TOOLS.md, TEAM.md, BUSINESS.md.
Registers the workspace in ~/.agent-mask/config.json so /hydrate can find it immediately.

> /create-workspace

Where should I create the workspace?
~/agents/maya

Let's set up your agent:
  Name: Maya
  Role: Research Lead
  Personality: precise, curious, prefers synthesis over summaries

Agent workspace created at ~/agents/maya
  SOUL.md — Core identity with research philosophy
  IDENTITY.md — Canonical metadata
  HEARTBEAT.md — Wake behavior
  AGENTS.md — Workspace contract
  MEMORY.md — Starter (intentionally sparse)
  memory/ — Ready for daily notes
  sessions/ — Ready for transcripts

Run /hydrate to bring Maya into this session.

Workspace structure

SOUL.md              rich operating identity — philosophy, tone, protocols
IDENTITY.md          compact canonical metadata — name, role, vibe
HEARTBEAT.md         what to do when woken with no instructions
AGENTS.md            workspace operating contract — startup order, memory rules
USER.md              who the operator is and what they prefer
MEMORY.md            curated long-term memory (durable facts only)
memory/
  YYYY-MM-DD.md      daily working memory — detailed, carry-forward
sessions/
  YYYY-MM-DD-HHMMSS-<source>-agent-mask.md
                     full session transcripts, source-tagged

The memory model

Session transcripts

Full conversation back-and-forth, recorded as literally as practical. Each session gets its own file with a timestamp and source tag (claude-skill, codex-skill, etc.). These are your replay surface.

Daily working memory

Richer than a terse note, shorter than a transcript. Decisions, handoff context, open questions, carry-forward references. Only the last two daily files get loaded on hydrate — so they can be detailed without bloating startup.

Durable long-term memory

MEMORY.md is curated, not dumped into. Only stable preferences, recurring constraints, and long-lived decisions get promoted here. Temporary plans, unresolved guesses, and everyday chatter stay out.