dotagents

A package manager for .agents directories. Declare agent skill dependencies in agents.toml, lock versions for reproducibility, and let every tool on your team discover skills from a single place.

Why dotagents?

One source of truth. Skills live in .agents/skills/ and symlink into .claude/skills/, .cursor/skills/, or wherever your tools expect them. No copy-pasting between directories.

Reproducible. agents.lock tracks managed skills. Pin versions directly in agents.toml with ref syntax.

Shareable. Skills are directories with a SKILL.md. Host them in any git repo, discover them automatically, install with one command.

Multi-agent. Configure Claude, Cursor, Codex, VS Code, OpenCode, and Pi from a single agents.toml -- skills, MCP servers, and hooks.

Quick Start

npx @sentry/dotagents init

The interactive setup walks you through selecting agents and trust policy. Then add skills:

# Add a skill from a GitHub repo
npx @sentry/dotagents add getsentry/skills find-bugs

# Add multiple skills at once
npx @sentry/dotagents add getsentry/skills find-bugs code-review commit

# Or add all skills from a repo
npx @sentry/dotagents add getsentry/skills --all

This creates an agents.toml at your project root and an agents.lock tracking installed skills.

After cloning a project that already has agents.toml, run install to fetch everything:

npx @sentry/dotagents install

Commands

| Command | Description | |---------|-------------| | init | Create agents.toml and .agents/skills/ | | add <source> [skills...] | Add skill dependencies | | remove <name> | Remove a skill | | install | Install all dependencies from agents.toml | | list | Show installed skills and their status | | sync | Reconcile gitignore, symlinks, and verify state | | mcp | Manage MCP server declarations | | trust | Manage trusted sources | | doctor | Check project health and fix issues |

All commands accept --user to operate on user scope (~/.agents/) instead of the current project.

Source Formats

Skills can come from GitHub, GitLab, any git server, or local directories:

[[skills]]
name = "find-bugs"
source = "getsentry/skills"              # GitHub shorthand

[[skills]]
name = "review"
source = "getsentry/[email protected]"       # Pinned to a ref

[[skills]]
name = "gitlab-skill"
source = "https://gitlab.com/group/repo" # GitLab URL

[[skills]]
name = "internal"
source = "git:https://git.corp.dev/repo" # Any git server

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

Shorthand (owner/repo) resolves to GitHub by default. Set defaultRepositorySource = "gitlab" in agents.toml to resolve to GitLab instead.

Agent Targets

The agents field tells dotagents which tools to configure:

agents = ["claude", "cursor"]

| Agent | Config Dir | MCP Config | Hooks | |-------|-----------|------------|-------| | claude | .claude | .mcp.json | .claude/settings.json | | cursor | .cursor | .cursor/mcp.json | .cursor/hooks.json | | codex | .codex | .codex/config.toml | -- | | vscode | .vscode | .vscode/mcp.json | .claude/settings.json | | opencode | .claude | opencode.json | -- |

Pi reads .agents/skills/ natively and needs no configuration.

Documentation

For the full guide -- including MCP servers, hooks, trust policies, wildcard skills, user scope, and CI setup -- see the documentation site.

Contributing

git clone [email protected]:getsentry/dotagents.git
cd dotagents
pnpm install
pnpm check  # lint + typecheck + test

Requires Node.js 20+ and pnpm.

License

MIT