Setup

Three commands to go from zero to working skills. Run these at the root of your repository.

1. Initialize

Create agents.toml and the .agents/skills/ directory. The interactive setup prompts for which agent tools you use (Claude, Cursor, etc.).

npx @sentry/dotagents init

This also adds agents.lock and .agents/.gitignore to your root .gitignore. These are generated files that should not be committed.

2. Add Skills

Install skills from GitHub repos, git URLs, or local directories.

# Add a single skill
dotagents add getsentry/skills --name find-bugs

# Add all skills from a repo
dotagents add getsentry/skills --all

# Pin to a specific ref
dotagents add getsentry/warden@v1.0.0

Each skill is copied into .agents/skills/ and symlinked to where your agent tools expect them. See the CLI reference for all source formats.

3. Install

After cloning the repo or pulling changes, run install to fetch skills. Managed skills are gitignored, so every collaborator needs to run this once.

dotagents install

This always fetches the latest skills. There is no separate update step.

What Gets Gitignored

dotagents manages gitignore automatically. Two generated files are kept out of version control:

Custom skills you create directly in .agents/skills/ are not gitignored. They're tracked by git normally, so collaborators get them without running install.

Trust Policies

By default, any source is allowed. For teams, add a [trust] section to restrict which sources can provide skills. Trust is validated before any network operations.

# Trust a GitHub org
dotagents trust add getsentry

# Trust a specific repo
dotagents trust add external-org/specific-repo

# Trust a self-hosted git server
dotagents trust add git.corp.example.com

See the Security page for the full trust configuration reference.

Auto-install with Git Hooks

Since managed skills are gitignored, collaborators need to run dotagents install after pulling. A post-merge hook automates this:

#!/bin/sh
# .git/hooks/post-merge
npx @sentry/dotagents install || echo "dotagents install failed"

Make it executable: chmod +x .git/hooks/post-merge

Git hooks aren't shared via git. Tools like lefthook or husky can set them up for the whole team.

Keeping Things in Sync

Use dotagents sync for offline repair. It doesn't fetch anything from the network. Instead, it:

Diagnosing Issues

Use dotagents doctor to check project health. It identifies configuration issues and can fix them automatically.

dotagents doctor        # check for issues
dotagents doctor --fix  # auto-fix what it can

Checks for missing gitignore entries, legacy config fields, missing skills, and broken symlinks. Especially useful when migrating from an older version.

Personal Skills

Project skills live in agents.toml and are shared with your team. Personal skills apply to all your projects — useful for tools and workflows only you need.

Use --user to manage personal skills:

dotagents --user init
dotagents --user add getsentry/skills --all
dotagents --user install

Personal skills live in ~/.agents/ and symlink to ~/.claude/skills/ and ~/.cursor/skills/. Override the location with DOTAGENTS_HOME.

When you run dotagents outside a git repo without an agents.toml, it falls back to user scope automatically.

Full Configuration Example

agents.toml with skills, wildcards, MCP servers, and hooks:

version = 1
agents = ["claude", "cursor"]

[trust]
github_orgs = ["getsentry"]

# Individual skill
[[skills]]
name = "find-bugs"
source = "getsentry/skills"

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

# Wildcard: all skills from a repo
[[skills]]
name = "*"
source = "myorg/skills"
exclude = ["deprecated-skill"]

# MCP server (stdio)
[[mcp]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = ["GITHUB_TOKEN"]

# MCP server (HTTP with OAuth)
[[mcp]]
name = "remote-api"
url = "https://mcp.example.com/sse"

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

See the CLI reference for all fields and options.