---
title: "dotagents"
description: "A package manager for .agents directories. Declare agent skill dependencies in agents.toml, lock versions for reproducibility, and share skills across your team."
url: https://docs.sentry.io/ai/dotagents/
---

# dotagents

dotagents is currently in beta. The project is in an early exploration phase and changes should be expected. Please share feedback on [GitHub](https://github.com/getsentry/dotagents/issues).

[dotagents](https://github.com/getsentry/dotagents) is a package manager for `.agents` directories. It lets you declare agent skill dependencies in `agents.toml`, lock versions for reproducibility, and ensure every tool on your team discovers skills from a single place.

## [Why dotagents?](https://docs.sentry.io/ai/dotagents.md#why-dotagents)

Without a package manager, agent skills end up copy-pasted between directories, versions drift across team members, and onboarding new tools requires manual setup. dotagents solves this:

* **One source of truth.** Skills live in `.agents/skills/` and symlink into `.claude/skills/`, `.cursor/skills/`, or wherever your tools expect them.
* **Reproducible.** `agents.lock` pins exact commits and integrity hashes. Running `npx @sentry/dotagents install --frozen` in CI guarantees everyone uses the same skills.
* **Shareable.** Skills are directories with a `SKILL.md`. Host them in any git repo, discover them automatically, and install with one command.

## [Quick Start](https://docs.sentry.io/ai/dotagents.md#quick-start)

### [Initialize a New Project](https://docs.sentry.io/ai/dotagents.md#initialize-a-new-project)

Run `init` in your project root to create an `agents.toml` and the `.agents/skills/` directory:

```bash
npx @sentry/dotagents init
```

### [Add a Skill](https://docs.sentry.io/ai/dotagents.md#add-a-skill)

Add a skill from a GitHub repository. The `--name` flag selects a specific skill from the repo:

```bash
npx @sentry/dotagents add getsentry/skills --name find-bugs
```

### [Install All Skills](https://docs.sentry.io/ai/dotagents.md#install-all-skills)

Install every skill declared in `agents.toml`:

```bash
npx @sentry/dotagents install
```

This creates an `agents.toml` at your project root:

`agents.toml`

```toml
version = 1
gitignore = false
agents = ["claude"]

[[skills]]
name = "find-bugs"
source = "getsentry/skills"
```

And a lockfile (`agents.lock`) that pins the exact commit and SHA-256 integrity hash for each skill.

## [Commands](https://docs.sentry.io/ai/dotagents.md#commands)

| Command         | Description                                     |
| --------------- | ----------------------------------------------- |
| `init`          | Create `agents.toml` and `.agents/skills/`      |
| `add <source>`  | Add a skill dependency                          |
| `remove <name>` | Remove a skill                                  |
| `install`       | Install all dependencies from `agents.toml`     |
| `update [name]` | Update skills to latest versions                |
| `list`          | Show installed skills and their status          |
| `sync`          | Reconcile gitignore, symlinks, and verify state |

## [Source Formats](https://docs.sentry.io/ai/dotagents.md#source-formats)

Skills can come from GitHub repos, pinned refs, non-GitHub git hosts, or local paths:

`agents.toml`

```toml
[[skills]]
name = "find-bugs"
source = "getsentry/skills"              # GitHub repo (auto-discover)

[[skills]]
name = "review"
source = "getsentry/skills@v1.0.0"       # Pinned to a ref

[[skills]]
name = "internal"
source = "git:https://git.corp.dev/repo"  # Non-GitHub git

[[skills]]
name = "local"
source = "path:./my-skills/local-skill"   # Local directory
```

## [Agent Targets](https://docs.sentry.io/ai/dotagents.md#agent-targets)

The `agents` field controls which tools dotagents configures. It handles skill symlinks, MCP config files, and hook config files for each agent:

`agents.toml`

```toml
agents = ["claude", "cursor"]
```

Supported agents: `claude`, `cursor`, `codex`, `vscode`, `opencode`.

## [MCP Servers](https://docs.sentry.io/ai/dotagents.md#mcp-servers)

Declare MCP servers once in `agents.toml` and dotagents generates the correct config file for each agent during `install` and `sync`:

`agents.toml`

```toml
agents = ["claude", "cursor"]

# Stdio transport
[[mcp]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = ["GITHUB_TOKEN"]

# HTTP transport
[[mcp]]
name = "remote-api"
url = "https://mcp.example.com/sse"
headers = { Authorization = "Bearer tok" }
```

Each server uses either `command` (stdio) or `url` (HTTP), not both. The `env` field lists environment variable names to pass through from the user's environment.

## [Hooks](https://docs.sentry.io/ai/dotagents.md#hooks)

Declare hooks once in `agents.toml` and dotagents writes the correct hook config for each agent that supports them:

`agents.toml`

```toml
agents = ["claude"]

[[hooks]]
event = "PreToolUse"
matcher = "Bash"
command = "my-lint-check"

[[hooks]]
event = "Stop"
command = "notify-done"
```

| Field     | Required | Description                                                |
| --------- | -------- | ---------------------------------------------------------- |
| `event`   | Yes      | `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, or `Stop` |
| `matcher` | No       | Filter to specific tool names (e.g., `Bash`, `Write`)      |
| `command` | Yes      | Shell command to run when the hook fires                   |

## [How It Works](https://docs.sentry.io/ai/dotagents.md#how-it-works)

1. Skills are declared in `agents.toml` at the project root.
2. `install` clones repos, discovers skills by convention, and copies them into `.agents/skills/`.
3. `agents.lock` records the resolved commit and a SHA-256 integrity hash.
4. By default (`gitignore = false`), skills are checked into git so collaborators get them immediately. Set `gitignore = true` to exclude managed skills instead.
5. Symlinks connect `.agents/skills/` to wherever your tools look (configured via the `agents` field).
6. MCP and hook configs are generated for each declared agent.

## [Checking In Skills](https://docs.sentry.io/ai/dotagents.md#checking-in-skills)

By default, `init` sets `gitignore = false` so installed skills are committed to git. Anyone cloning the repo gets skills immediately — they only need dotagents when adding or updating skills.

To gitignore managed skills instead (collaborators must run `install`), set `gitignore = true` in `agents.toml`.

## [Learn More](https://docs.sentry.io/ai/dotagents.md#learn-more)

* [dotagents on GitHub](https://github.com/getsentry/dotagents)
* [Agent Skills](https://docs.sentry.io/ai/agent-skills.md)
* [Sentry MCP Server](https://docs.sentry.io/ai/mcp.md)