# Team (https://docs.neuralisapp.com/package-system/team)

`team/<slug>/` ships a ready-made agent character — package-provided base
configuration for the agent-creation flow:

```text
team/
  search-agent/
    member.json        # slug, name, role, description, config, permissions, appearance
    identity/          # *.md identity files injected for this member
    files/             # *.md additional member files
```

`member.json` carries the create-agent shape:

```json
{
  "slug": "search-agent",
  "name": "Search",
  "role": "assistant",
  "description": "What this coworker is for, and when to pick it.",
  "config": {
    "settings": {
      "maxSteps": 15,
      "defaultModelId": "provider/model-id",
      "guardProfile": "balanced"
    }
  },
  "permissions": { "sources": ["brain"], "features": ["core.agents"] },
  "appearance": { "icon": "search", "color": "#3b82f6" }
}
```

A team directory without a `member.json` is skipped.

## Four rules that are easy to get wrong [#four-rules-that-are-easy-to-get-wrong]

- **`description` is the field that reaches a model.** A member may also carry
  `descriptionForModel`, but nothing reads a *member's* copy — only the
  package-level `descriptionForModel` is advertised. Put the "when to pick this
  coworker" sentence in `description`.
- **Pin a model and a guard posture inside `config.settings`**, as
  `defaultModelId` and `guardProfile`. There is no top-level `model`, `icon`, or
  `color` key — appearance nests under `appearance`.
- **Identity placeholders substitute once, at provisioning.** When an agent is
  created from the member, each `identity/*.md` and `files/*.md` is *copied* into
  the agent's own data directory with a fixed eight-key substitution:
  `{{agentId}}`, `{{agentName}}`, `{{createdAt}}`, `{{packageId}}`,
  `{{memberSlug}}`, `{{role}}`, `{{projectId}}`, `{{userId}}`. There is **no**
  per-turn re-substitution, and `{{conversationId}}` is not in the set — write it
  and it ships to the model literally. Dotted forms such as `{{user.name}}` ship
  literally everywhere.
- **Identity-file frontmatter is stripped, not parsed.** `activation`, `pinned`,
  and `priority` on an identity file do nothing; injection order is fixed by
  filename, so name the files in the order you want them read.

A spawn-time sub-agent persona is an [agent](https://docs.neuralisapp.com/package-system/agents.md) instead.
A [workflow template](https://docs.neuralisapp.com/package-system/workflows.md) can name a member through
`teamMemberSlug` (validated, but no runtime reads it yet).
