dotagents

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?

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

npx @sentry/dotagents init

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

npx @sentry/dotagents install

This creates an agents.toml at your project root:

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

Source Formats

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

[[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

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

agents = ["claude", "cursor"]

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

MCP Servers

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

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

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

agents = ["claude"]

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

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

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

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

• dotagents on GitHub
• Agent Skills
• Sentry MCP Server