Create general agent

Create General Agent

Scaffold one standalone personal agent. One folder, one git repo, one set of instructions, optionally one tmux session. The agent works directly for its user and reports to no one.

What makes this agent durable is its two-part brain, both living inside the agent's own folder so they are portable and version-controlled:

1. Memory (memory/) — Claude Code-style file-based memory: durable facts, preferences, and recurring feedback. Fast to recall, small, frequently updated.
2. Knowledge base (knowledge-base/) — Andrej Karpathy's "LLM wiki" method: an append-only raw/ folder (every source verbatim, the single source of truth) and a distilled wiki/ folder (encyclopedia articles with [[backlinks]] and an index) that the agent writes and continuously revises.

A memory entry may point into the wiki with [[a-wiki-page]]. Rule of thumb: memory = what to remember about the user and the work; wiki = what you've learned about the subject.

Before you create

1. Understand the mission from context. What is this agent for — a tutor, a research companion, a coding assistant, a writing partner, a domain expert? What does "done" look like for it? Which CLI will it run in (Claude Code by default)?
2. Pick a short kebab-case slug (e.g. rust-tutor, paper-buddy, tax-helper).
3. Choose a location. Default is ~/agents/<slug>. Override with --project-dir if the user wants it somewhere specific (e.g. inside an existing repo or ~/dev).
4. Optional: write a context file. If you have extra mission detail (goals, constraints, starting material, links), drop it in a temp file and pass --context-file so it gets embedded for the agent's first boot.
5. Ask only if genuinely unclear. If the mission or a safety boundary can't be reasonably inferred, ask one concise question. Otherwise choose sensible defaults and proceed.

Create the agent

~/.claude/skills/create-general-agent/scripts/create_general_agent.sh \
  <agent-slug> "<one-line mission>" \
  --project-dir ~/agents/<agent-slug> \
  --command claude \
  --context-file /tmp/<agent-slug>-context.md

Useful options:

--project-dir PATH      # where to create it (default ~/agents/<slug>)
--command CMD           # claude (default), codex, opencode, cursor agent, etc.
--context-file PATH     # extra mission context, embedded for first boot
--launch                # also start it in a tmux session (off by default)
--session NAME          # tmux session name when launching (default <slug>)
--role ROLE             # tmux @role_name tag when launching (default <slug>)
--no-git                # skip git init / first commit
--force-instructions    # overwrite an existing CLAUDE.md

The simplest path creates files only; the user then runs the agent themselves:

cd ~/agents/<agent-slug> && claude

What gets created

<project-dir>/
├── CLAUDE.md                     # canonical instructions (mission + two-part brain + boot)
├── AGENTS.md -> CLAUDE.md        # symlink for Codex/OpenCode/Cursor parity
├── .gitignore
├── docs/                         # plans, specs (boot writes docs/plan.md)
├── tasks/  outputs/  scripts/  context/
├── memory/
│   ├── MEMORY.md                 # index loaded every session
│   └── _template.md              # one-fact-per-file format
└── knowledge-base/
    ├── README.md                 # the Karpathy update loop
    ├── raw/                      # APPEND-ONLY sources (single source of truth)
    └── wiki/
        ├── index.md              # map of all articles
        └── _templates/article.md # distilled-article format

Verify

ls -la <project-dir>                      # CLAUDE.md, AGENTS.md symlink, memory/, knowledge-base/
cat <project-dir>/CLAUDE.md               # mission correct, no "reports to" anyone
# if launched:
tmux has-session -t <session> && tmux list-panes -t <session> -F '#{pane_id} #{@role_name}'

Then point the new agent at its boot sequence (read CLAUDE.md → context/ → memory/MEMORY.md → wiki/index.md → write docs/plan.md).

Design notes

• Standalone by design. There is no reporting line, no parent agent, no shared message bus. If the user later wants agents to talk to each other, that's a different (multi-agent) setup — this skill deliberately keeps each agent independent.
• Self-contained. The created agent depends only on a normal shell, git, and the chosen CLI. No external memory service, no special infrastructure.
• Talking between agents (optional). This kit ships tm-send, a hardened tmux send-keys wrapper. If you ever run more than one agent and want them (or you) to message each other's panes, use tm-send -s <session> <role> "<msg>" instead of raw tmux send-keys — it targets the right pane and handles per-CLI submit quirks. Install it once with bin/install-tm-send.sh (puts it on your PATH).
• Keep the brain alive. The whole value is the loop: as the agent works, it writes durable facts to memory/ and distills sources into knowledge-base/wiki/. The CLAUDE.md instructs the agent to do this on every task. An agent that doesn't update its brain decays into a plain chatbot.