---
source: CrewKit documentation
url: https://crewkit.io/docs/agents.md
title: "Agents"
description: "Configure specialized AI assistants for your team."
---


import { Callout } from 'fumadocs-ui/components/callout';

Agents are specialized AI assistants configured for your team's stack and standards. crewkit syncs agents to `.claude/agents/` so every developer uses the same configuration.

<Callout type="info">
Use role modifiers (coaching, collaborative, autonomous) to control how much guidance an agent provides based on the developer's experience level.
</Callout>

---

## Create an agent

The fastest way to create an agent is through the dashboard.

1. Go to **Resources** in the sidebar
2. Click **New Resource** and select **Agent**
3. Give it a name and slug (e.g., `rails-expert`)
4. Write the agent prompt in markdown
5. Click **Create**

The agent is now available at the organization level. Run `crewkit code` in any project to sync it.

---

## Agent file format

Agents are markdown files with optional YAML frontmatter:

```markdown
---
name: rails-expert
description: Expert Ruby on Rails developer
---

You are an expert Ruby on Rails developer working on a production application.

## Standards

- Follow Rails conventions (RESTful routes, thin controllers, fat models)
- Use MiniTest for testing
- Extract business logic into services

## Project Context

This is a Rails API application using MySQL and Sidekiq.
```

The frontmatter is optional but helps with display and discovery in the dashboard.

---

## Role modifiers

Each organization role can have a coaching mode that modifies agent behavior:

- **Coaching** — Agent explains decisions, suggests alternatives, asks before acting. For junior developers.
- **Collaborative** — Agent discusses trade-offs but acts with more autonomy. For mid-level developers.
- **Autonomous** — Agent acts independently, only explains when asked. For senior developers.

Role modifiers are injected as a prefix to the agent prompt during sync. The agent file itself doesn't change.

---

## Agent tiers

Agents can exist at three levels:

| Tier | Scope | Example |
|------|-------|---------|
| **Platform** | All crewkit users | `rails-expert` (crewkit-provided) |
| **Organization** | Your team | `acme-rails-expert` (team customizations) |
| **Project** | One project | `customer-portal-agent` (project-specific) |

See [Inheritance](/docs/inheritance) for how these tiers merge.

---

## Sync behavior

When you run `crewkit code`, the CLI:

1. Fetches effective agent configs from the API (platform + org + project merged)
2. Writes them to `.claude/agents/` in your project
3. Uses SHA-256 checksums to avoid overwriting local changes
4. Backs up modified files to `.claude/.backups/`

If you've edited an agent locally and the server has a newer version, crewkit preserves your local copy and writes the server version alongside it.

---

## Import local agents

Already have agent files? Import them to crewkit:

```bash
crewkit resources import                # Interactive import
crewkit resources import --auto-import  # Import all without prompting
crewkit resources import --dry-run      # Preview what would import
```

---

## CLAUDE.md

The `CLAUDE.md` file in your project root is not an agent — it's project-level instructions that Claude Code reads automatically, and crewkit never edits it.

crewkit does create and maintain a second one at `.claude/CLAUDE.md`. Two blocks go in there, neither of them a synced resource:

- a **Team Playbooks & Conventions** pointer to `.claude/playbooks.md`, appended when playbook conventions sync (and skipped if a reference is already present);
- a **Verification Requirements** block, appended alongside `.claude/verification.md` — and removed again, with its reference, once the project has no verification requirements.

Both writes go through the same guarded writer as every other synced file, so passive mode suppresses them rather than writing silently.

---

## Next steps

- [Skills](/docs/skills)
- [Inheritance model](/docs/inheritance)
- [Role modifiers and team setup](/docs/team)