Configuration

Everything lives in one YAML file. Here's every field and option.

On this page

.teamrc.yaml Top-level fields Member fields Skill fields Global config Project vs global Environment variables Validation limits

The .teamrc.yaml file

This is your team definition. It lives in your project root and describes your entire team. You can edit it directly, or let the web UI and CLI manage it. Here's a complete example:

.teamrc.yaml 
version: 1
name: my-project

# Optional: link to a relay team
teamId: team_abc123
relay: https://relay.teamrc.dev
platforms:
  - claude-code
  - cursor

members:
  - name: frontend
    role: Frontend development
    soul: |
      You are the frontend specialist...
    skills:
      - code-style
      - testing

  - name: reviewer
    role: Code review
    skills:
      - code-review

skills:
  - id: code-style
    title: Code Style Guide
    alwaysApply: true
    body: |
      Follow the project's existing patterns.
      Use TypeScript strict mode.

  - id: testing
    title: Testing Requirements
    globs:
      - "*.test.ts"
      - "*.spec.ts"
    body: |
      Write tests for all new functions.

  - id: code-review
    title: Code Review
    body: |
      Review for correctness, readability,
      and security vulnerabilities.

Top-level fields

version Always 1 . Reserved for future schema changes.
name Your team name. 1-64 characters, alphanumeric with spaces, hyphens, and underscores.
teamId Optional. The relay team ID. Set automatically by init and join .
relay Optional. Relay server URL. Defaults to the URL in ~/.teamrc/config.json .
platforms Optional. List of platforms to target. If omitted, all detected platforms are used.
members List of team members (see below).
skills List of team skills (see below).

Member fields

name Required. Lowercase, hyphenated identifier. Used as the filename (e.g. trc-frontend.md ).
role Required. One-line description of what the agent does.
description Optional. Capability-based description used by AI platforms for task routing. Pattern: "[What it does]. Use when [trigger]." Auto-populated from the template catalog. Falls back to role if absent.
soul Optional. Markdown instructions that define the agent's identity and behavior. This is the same concept referred to as "instructions" elsewhere in the guide.
skills Optional. List of skill IDs to assign to this member. Must reference skills defined at the team level.

Skill fields

id Required. Unique identifier. Used as a filename.
title Optional. Human-readable label.
description Optional. Short explanation of what the skill does.
body Required. The instructions, written in markdown. You can also reference an external file with a source path.
alwaysApply Optional boolean. When true, applies to all agents automatically.
globs Optional list of file patterns. The skill activates only for matching files.

Global config (~/.teamrc/)

The ~/.teamrc/ directory stores machine-level configuration:

key Ed25519 keypair (JSON, mode 0600)
config.json Token, relay URL, account email, machine name
team.yaml Global team definition (when using --global scope)

Project vs global scope

Teams can be scoped to a project (default) or global.

Project .teamrc.yaml in the project root. Config files written to the project directory. This is the default for most workflows.
Global ~/.teamrc/team.yaml . Config files written to global platform directories (e.g. ~/.claude/agents/ ). Applies to all projects on the machine. Use --global flag.

Project scope takes precedence when both exist. The CLI resolves scope automatically: if .teamrc.yaml exists in the current directory, it uses project scope.

Environment variables

TEAMRC_RELAY Override the relay server URL. Takes precedence over config.json and .teamrc.yaml.

Validation limits

The relay enforces these limits for the web UI and sync endpoints:

Team name 1-64 chars, alphanumeric + spaces/hyphens/underscores
Agent name 1-64 chars, alphanumeric + hyphens/underscores
Max members 20 per team
Max skills 50 per team
YAML size 256 KB max
Knowledge 100,000 bytes max
Skill body 10,000 bytes max per inline body

The local CLI can accept larger YAML files in some cases. But anything sent to the relay must fit within these limits.