dotagents

Manage dependencies declared in agents.toml. dotagents resolves skills, subagents, plugins, MCP servers, and hooks so agent tools (Claude Code, Cursor, Codex, GitHub Copilot, Grok, VS Code, OpenCode, Pi) can use shared global or project config.

References

Read the relevant reference when the task requires deeper detail:

Commands

All commands default to global scope (~/.agents/). --project selects the current repository (or current directory outside Git). --global is an explicit global spelling, and --user is its compatibility alias. Never combine --project with a global alias.

Adding Plugins

Use the same add command for plugins. Git and local sources are checked for plugins first; when any plugin is found, that source is treated as plugin-only. Well-known HTTPS sources remain skill-only.

# Add a plugin to this repository
npx @sentry/dotagents --project add getsentry/agent-plugins review-tools

add installs immediately, so do not follow it with a redundant install. For plugins, --all records a snapshot of every plugin currently found. For skills, --all creates a wildcard that can include future skills. Re-adding an identical declaration refreshes its installation without changing agents.toml; conflicting declarations still fail.

For full options and flags, read references/cli-reference.md.

Safe Removal and Trust

Use remove instead of manually deleting managed files or editing agents.lock. For a project dependency, keep explicit scope: npx @sentry/dotagents --project remove <name>. When a wildcard provides the skill, let remove add the name to the wildcard's exclude list so the next install does not restore it.

When trust blocks a source, inspect syntax without mutation using npx @sentry/dotagents trust add --help. Then show the exact scoped command, such as npx @sentry/dotagents trust add git.corp.example.com, and explicitly ask approval before running it. Never enable allow_all or add a trusted source without explicit user intent.

Source Formats

Key Concepts

• Managed paths live under ~/.agents/ globally or .agents/ in project scope
• agents.toml declares dependencies; agents.lock tracks managed skills, subagents, and plugins
• Symlinks: agent skill directories point to the selected scope's managed skills directory
• Wildcards: name = "*" installs all skills from a source, with optional exclude list
• Trust: Optional [trust] section restricts which sources are allowed
• Hooks: [[hooks]] declarations write tool-event hooks to each agent's config
• Subagents: [[subagents]] declarations install portable or native subagent files
• Plugins: [[plugins]] declarations install canonical bundles and generate runtime-specific plugin outputs
• Gitignore: In project scope, managed skills, subagents, and plugin bundles are gitignored; custom in-place sources are tracked
• Global scope: the default; manages dependencies in ~/.agents/ shared across projects, including plugins
• Project scope: --project manages repository-local agents.toml, agents.lock, and .agents/
• Updates: Run npx @sentry/dotagents install to refresh managed skills, subagents, and plugins; there is no update command

Running dotagents

Always use npx @sentry/dotagents to run commands. Unqualified commands are global by default. Add --project whenever the user asks to manage the current repository. Do not infer project intent merely because the current directory contains agents.toml.

Apply this literally: “add this skill” with no repository-local wording means npx @sentry/dotagents add ..., even inside a repository that has agents.toml. “Add this skill to this repository/project” means npx @sentry/dotagents --project add ....

Global add bootstraps ~/.agents/agents.toml when it is missing. Do not run a separate global init or install before or after add unless the user independently requested it.

Quick Start

# Initialize global state (interactive TUI)
npx @sentry/dotagents init

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

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

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

# Add a plugin
npx @sentry/dotagents add getsentry/agent-plugins review-tools

# Add a pinned skill
npx @sentry/dotagents add getsentry/warden@v1.0.0

# Install or refresh all dependencies from agents.toml
npx @sentry/dotagents install

# List installed skills
npx @sentry/dotagents list

For repository-local management, keep --project on every command:

npx @sentry/dotagents --project init
npx @sentry/dotagents --project add getsentry/skills find-bugs
npx @sentry/dotagents --project install
npx @sentry/dotagents --project list
npx @sentry/dotagents --project doctor --fix