idagents-team-builder

Files (1)

• SKILL.md

SKILL.md (first lines)

# ID Agents Team Builder

How to build an id-agents team that actually works. Distilled from real-world team builds that hit every avoidable footgun.

## When to use

- Designing a new team config under `configs/<team>.yaml`.
- Adding agents to an existing team and wondering "where does the role come from".
- An agent deployed but has no unique personality (just framework boilerplate).
- An agent is supposed to have specialist skills but only has the defaults.
- A deploy fails with `EEXIST` from `cpSync`.
- Multiple agents are stepping on each other's `CLAUDE.md`.

## The seven rules

These come from rebuilding the same team three times to get it right.

### 1. `workingDirectory` MUST be per-agent. Defaults are silently dropped.

`defaults.workingDirectory` in the YAML is not merged into each agent. The config parser only merges `runtime`, `model`, `plugins`, `skills`, `allowedTools`, and `resources` from defaults (see `mergeDefaults` in `src/config-parser.ts`). If you put `workingDirectory` in `defaults`, every agent falls back to `<workspace>/agents/<agent-id>/` and the parser cannot find their role files.

Always set `workingDirectory` explicitly per agent:

```yaml
agents:
  - name: cso
    workingDirectory: /Users/me/projects/security/agents/cso
    description: "..."
  - name: security-stack-a
    workingDirectory: /Users/me/projects/security/agents/security-stack-a
    description: "..."
```

### 2. Role files are read from `<workingDirectory>/.claude/agents/<name>.md` at deploy time.

The parser calls `loadSubAgentTemplate(workingDirectory, name, runtime)`. Two patterns are accepted, directory wins over single-file:

- **Directory pattern**: `<wd>/.claude/agents/<name>/CLAUDE.md` (priority)
- **Single-file pattern**: `<wd>/.claude/agents/<name>.md`

Whichever the parser finds, its body (everything after the frontmatter) becomes `roleBody`. The framework appends roleBody to its boilerplate (scheduling, task discipline, output convention) and writes the combined personality to `<wd>/.claude/CLAUDE.md` at spawn time.

If `workingDirectory` is unset (see rule 1) the parser returns early and no role is loaded. The agent gets framework boilerplate only and acts identical to every other underspecified agent in the team.

### 3. Each agent owns its workspace. No shared `workingDirectory`.

The framework writes per-agent personality to `<wd>/.claude/CLAUDE.md`. If two agents share a `workingDirectory`, they overwrite each other's CLAUDE.md as they spawn. Last writer wins. Every other agent ends up with the wrong personality.

Give each agent its own directory. The portfolio pattern: a parent umbrella project with per-agent subdirs.

```
my-security/
├── .claude/agents/       # canonical role files (optional, for Claude-Code-subagent mode)
│   ├── cso.md
│   ├── cso/CLAUDE.md
│   └── ...
└── agents/               # per-agent workspaces for the daemon team
    ├── cso/
    │   └── .claude/agents/cso.md
    ├── security-stack-a/
    │   └── .claude/agents/security-stack-a.md
    └── ...
```

### 4. No symlinks in the per-agent workspace. Copy real files.

The deploy uses `cpSync(srcDir, destDir, {recursive, force})` to overlay agent dir contents. If your role file or context dir is a relative symlink, cpSync creates a symlink at the destination pointing to the resolved target. If that destination already exists as a real directory, the deploy fails with `EEXIST: file already exists, symlink 'target' -> 'destination'`.

Always copy. Never symlink.

```bash
# WRONG
ln -s ../../../../.claude/agents/cso.md agents/cso/.claude/agents/cso.md

# RIGHT
cp .claude/agents/cso.md agents/cso/.claude/agents/cso.md
```

Acceptable duplication: if you also keep canonical role files at `idx-security/.claude/agents/`, you have two copies. They drift if you edit one without the other. Live with it, or regenerate with a script when role files change.

### 5. Library agent templates compose with custom roles.

`agent: <template-name>` in an agent's YAML pulls a library template (from `configs/agents/<template>/`) into the agent's workspace. The deploy calls `copyLibraryAgentOverlay`:

- Template's `CLAUDE.md` goes to `<wd>/.claude/rules/agent-<template>.md` (sidecar, NOT overwriting your custom role).
- Template's bundled `skills/` get merged into `<wd>/.claude/skills/`.

So you keep your custom role at `<wd>/.claude/agents/<name>.md`, and the library template provides extra skills + reference rules on the side.

Available templates today (under `configs/agents/`): `security`, `solidity-security`, `pashov-solidity-security`, `foundry-dev`, `frontend`, `frontend-react`, `fullstack-nextjs`, `devops`, `editor`, `copywriter`. Inspect each template's `skills/` to see what it adds.

### 6. Skills come from three sources and merge in the agent's `.claude/skills/`.

- **Bundled framework skills** (`<id-agents>/skills/`): `identity`, `inter-agent`, `catalog`, `task-discipline`, `wallet`, `xmtp`, etc. Listed in `defaults.skills` or per-agent `skills:`. Deploy copies them via `deploySkillsToAgent`.
- **Library template skills** (`configs/agents/<template>/skills/`): bundled with the template. Pulled in by `agent: <template-name>`.
- **Per-agent custom skills**: drop a directory at `<wd>/.claude/skills/<skill-name>/` with a `SKILL.md`. The agent owns it.

The per-agent skill copy is **a full copy at deploy time**. Each agent owns its skills and can modify them independently. Edits do not affect other agents and do not get clobbered on `/agents rebuild` (rebuild restarts existing agents from DB; it does not re-overlay).

`/deploy <team>` re-overlays skills, but it is CREATE-ONLY — it refuses an existing team, so it can no longer clobber a live one. `/sync` is REMOVED. Per-agent skill edits survive `/agents rebuild`. If an agent has customizations worth keeping, fold them back into a library template.

### 7. Structure: defaults + org + agents.

```yaml
version: "1"
team: <team-name>

# Inherited by every agent EXCEPT workingDirectory (rule 1).
defaults:
  local: true
  runtime: claude-code-cli
  model: claude-opus-4-7
  dangerouslySkipPermissions: true
  skills:
    - identity
    - inter-agent
    - catalog
    - task-discipline

From idchain-world/id-agents, MIT.

More from idchain-world/id-agents