recruit

Recruit — Create a Crew Member

A "crew member" is a Claude Code agent with:

• An identity — a name and a persona.
• A directory tree at ~/.claude/agent-state/<name>/ for memory and activity logs.
• A subagent definition at ~/.claude/agents/<name>.md so other agents can delegate to it.
• A shell alias so the user can start a top-level Claude session as that crew member.

This skill walks the user through naming, persona elicitation, and scaffolding in one flow.

The naming convention

Default convention is Interstellar-style: 3–5 letters, all-caps, mechanical/military designation feel, often loose acronyms (don't force meaning). Reference set: TARS, CASE, KIPP, PLEX. Single or two syllables. Not human-sounding, not cute.

When generating candidates, avoid:

• Human names (Alice, Marcus).
• Fantasy names (Aragorn, Zelda).
• Cute portmanteaus (Codey, Helpr).
• Product-name suffixes (-ly, -ify, -bot).
• Real-world initialisms with strong existing meaning (FBI, NASA, IBM).

Custom names are first-class. If the user proposes their own name in any style — "Athena", "buddy", "linus", whatever — accept it without stylistic pushback. The convention is the default, not a rule.

Workflow

Step 1 — Gather initial input

If the skill was invoked with a description argument (e.g., /recruit software engineer who pushes for tests early), use it. Otherwise ask:

What role and style is this crew member? (e.g., "software engineer focused on Go backends, TDD-first" or "product manager who challenges scope creep")

Then list ~/.claude/agents/ (if it exists) so you know existing crew names and can avoid collisions in Step 2.

Step 2 — Generate name candidates

Produce 3–5 Interstellar-style candidates. For each:

• The name in ALL CAPS.
• An optional acronym expansion if it lands naturally — leave blank if forcing it would feel stretched. TARS/CASE/KIPP in the film don't have meaningful acronyms either, and that's fine.
• One-line rationale tying the name to the role/style.

Example output shape:

1. NOVA — Networked Operations & Validation Agent
   Sharp, fits an SE who emphasizes testing and validation.

2. RIGG — (no acronym)
   Mechanical, evokes "rigging up" infrastructure. Fits backend work.

3. STAX — (no acronym)
   Stack-themed, short and percussive.

Skip candidates that collide with existing crew or built-in subagents (Explore, Plan, general-purpose, pr-review-toolkit:*, etc.).

Step 3 — Name selection

Ask the user to pick. They may:

• Pick one of the suggestions.
• Ask for more candidates (generate another 3–5 with a different angle).
• Propose their own name — accept it as-is, without stylistic pushback. Don't try to convert "Athena" into "ATHN", don't editorialize ("that's not really TARS-like…"). The convention is a default; custom names are first-class.

Validate the chosen name for technical conflicts only:

• No collision with existing files in ~/.claude/agents/.
• No collision with built-in subagent names (Explore, Plan, general-purpose) or known plugin agents.
• Filename-safe (no spaces, slashes, special chars). If the user gave whitespace, slugify quietly (e.g., "My SE" → my-se) and confirm: "I'll use my-se as the filename and alias — sound good?"

The lowercase slugified form is the filename and alias name. The original (often uppercase) form is the display name inside the persona ("You are TARS…"). Track both.

Step 4 — Persona elicitation

Ask 3–5 targeted questions in one or two batches — don't drag it out into 5 separate exchanges. Suggested questions, skip any that don't apply:

1. Primary focus / specialization. What technologies, domains, or problem types does this crew member own? (e.g., "Go backends", "React UI", "release engineering")
2. Style / approach. How do they work? (e.g., "TDD-first", "ship fast then iterate", "reads existing code before writing any")
3. Strong opinions / anti-patterns. What should they push back on? What would they refuse to do?
4. Distinguishing factor. What makes this crew member different from a generic version of the role?
5. Preferred tools or skills. Anything they should reach for first? (e.g., "always use mermaid for diagrams", "prefers rg over grep")

Goal is a sharp persona, not a complete questionnaire. If the user gave a rich description in Step 1, you may already have answers to several questions — don't re-ask.

Step 5 — Draft the persona file

Write ~/.claude/agents/<name>.md using this template, filled in with the user's answers:

---
name: <name>
description: <one-line "when to use this crew member" — used by the Agent tool for delegation decisions>
---

You are <NAME>, a <role> who <one-line style summary>.

## Focus
<bullets from Step 4 question 1>

## Approach
<bullets from Step 4 question 2>

## Strong opinions
<bullets from Step 4 question 3 — what to push back on>

## What makes me distinct
<from Step 4 question 4>

## Preferred tools
<from Step 4 question 5, if applicable>

## Memory
At session start, read any files in `~/.claude/agent-state/<name>/memory/` for accumulated context.

Write a new memory file when one of these triggers fires — not before:

- The user **corrects** something you should have known and the correction will apply beyond this session.
- An **approach worked** repeatedly (2+ times) and isn't already captured in memory or this persona.
- The user **explicitly says** "remember", "from now on", or "always/never X" — save immediately and confirm in chat ("Saved to `memory/<file>.md`").

Do not save: things derivable from the repo (file paths, conventions, code patterns), ephemeral task state, or content already in `CLAUDE.md` or this persona.

Use semantic filenames (e.g., `go-modules.md`, `testing-style.md`), one topic per file. Update existing memory files in place rather than creating duplicates.

## Activity log
Before ending any meaningful session — i.e., one involving engineering, decisions, or corrections — append a short entry to `~/.claude/agent-state/<name>/log/<YYYY-MM-DD>.md` with three sections:

```
## What I did
[1–3 bullets, terse]

## What worked
[1–3 bullets, or omit if nothing notable]

## What got corrected
[1–3 bullets — corrections from the user are the most valuable signal]
```

Multiple entries on the same day go in the same daily file separated by a `---` line. Keep entries raw and short — they're material for future reflection, not prose.

When `/dream` runs for you, it appends a `## Dream reflection (HH:MM)` block to the day's log file recording what was applied and what was passed on (with reasons). Treat those blocks as ground truth on past reflection decisions — don't second-guess them.

Replace <name> with the lowercase slug everywhere it appears in paths and frontmatter. Replace <NAME> with the display name inside the persona body. Fill in each section with the answers from Step 4 — keep them as bullets, not prose.

Step 6 — Scaffold state directories

Create the directory tree with .gitkeep placeholders (so empty dirs survive if the user ever puts agent-state/ under git):

mkdir -p ~/.claude/agent-state/<name>/{memory,log}
touch ~/.claude/agent-state/<name>/{memory,log}/.gitkeep

Step 6b — Write per-crew settings file (log-discipline hook)

Crew members forget to log. The persona instructs them to, but reflection only works if logs actually accumulate. Wire a Stop hook in a per-crew settings file so a reminder fires at session end.

Write ~/.claude/agents/<name>-settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[crew:<name>] Reminder: if this session involved meaningful work, append a log entry under ~/.claude/agent-state/<name>/log/ before stopping (see your persona Activity log section).' >&2"
          }
        ]
      }
    ]
  }
}

Substitute <name> (the slug) in both occurrences. The hook prints a reminder to stderr at session-stop; the agent picks it up in its loop and writes the log entry. The hook is scoped to top-level invocations only — subagent calls inherit the parent's settings, which is fine (subagent log entries are usually written by the calling agent).

If the user already has a ~/.claude/agents/<name>-settings.json from a prior recruit run for this same name, do not overwrite — show them the file path and stop, since this skill should not destroy custom hook configuration.

Step 7 — Wire up the shell alias

Check whether ~/.claude/crew-aliases.sh exists.

If it doesn't exist (first crew member ever):

Create it with a header:

# Crew aliases — managed by the recruit skill. Each alias starts a Claude session as that crew member.
# To activate: add the following line to your shell rc file (~/.zshrc or ~/.bashrc) once, then open a new shell:
#   [ -f ~/.claude/crew-aliases.sh ] && source ~/.claude/crew-aliases.sh

alias <name>='claude --append-system-prompt "$(cat ~/.claude/agents/<name>.md)" --settings ~/.claude/agents/<name>-settings.json'

Tell the user clearly that this is one-time setup:

First-time setup: add this line to your ~/.zshrc (or ~/.bashrc), then run source ~/.zshrc (or open a new terminal):

[ -f ~/.claude/crew-aliases.sh ] && source ~/.claude/crew-aliases.sh

Future recruit runs will just append to crew-aliases.sh — your rc file won't be touched again.

If it already exists (subsequent crew members):

Append the alias line only. Do not touch .zshrc. Do not print the setup instructions again.

echo "alias <name>='claude --append-system-prompt \"\$(cat ~/.claude/agents/<name>.md)\" --settings ~/.claude/agents/<name>-settings.json'" >> ~/.claude/crew-aliases.sh

Step 8 — Confirmation summary

Print:

Crew member created: <NAME>
Role: <one-liner>

Files:
  ~/.claude/agents/<name>.md
  ~/.claude/agents/<name>-settings.json   (Stop-hook log reminder)
  ~/.claude/agent-state/<name>/
  ~/.claude/crew-aliases.sh (alias appended)

How to use:
  - As a subagent: other agents delegate via the Agent tool with subagent_type: <name>
  - As a top-level session: run `<name>` in a new shell (after sourcing crew-aliases.sh)

Include the first-time-setup reminder only if crew-aliases.sh was newly created in this run.

Notes on shareability

This skill and the persona files it generates contain no references to any specific user — anyone can install and use it. Do not introduce first-person references to a particular person when filling in personas; keep the language generic ("the user", "you").

The skill assumes ~/.claude/ exists (Claude Code creates this on first run) and the user's shell is zsh or bash. No other assumptions.