/dotagents

name: dotagents
description: Manage dotagents dependencies and runtime config. Use when asked to "add a skill", "install skills", "remove a skill", "configure plugins", "configure subagents", "dotagents init", "agents.toml", "agents.lock", "sync skills", "list skills", "set up dotagents", "configure trust", "add MCP server", "add hook", "wildcard skills", "global scope", "project scope", "dotagents doctor", or any dotagents-related task.
spec_hash: 98920b9b8a05

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.

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.

References

Read the relevant reference when the task requires deeper detail:

| Document | Read When | |----------|-----------| | [references/cli-reference.md](references/cli-reference.md) | Full command options, flags, examples | | [references/configuration.md](references/configuration.md) | Editing agents.toml, source formats, trust, MCP, hooks, wildcards, scopes | | [references/config-schema.md](references/config-schema.md) | Exact field names, types, and defaults |

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

Commands

| Command | Description | |---------|-------------| | `npx @sentry/dotagents init` | Initialize global config and managed directories | | `npx @sentry/dotagents install` | Install all dependencies from `agents.toml` | | `npx @sentry/dotagents add <specifier> [names...]` | Discover and add plugins, otherwise skills | | `npx @sentry/dotagents remove <name>` | Remove a skill or plugin | | `npx @sentry/dotagents sync` | Reconcile state (adopt orphans, prune stale managed artifacts, repair configs) | | `npx @sentry/dotagents list` | Show declared skills, plugins, and status | | `npx @sentry/dotagents mcp` | Add, remove, or list MCP server declarations | | `npx @sentry/dotagents trust` | Add, remove, or list trusted sources | | `npx @sentry/dotagents doctor` | Check global health and fix issues |

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](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

| Format | Example | Description | |--------|---------|-------------| | GitHub shorthand | `getsentry/skills` | Owner/repo (resolves to GitHub HTTPS) | | GitHub pinned | `getsentry/warden@v1.0.0` | With tag, branch, or commit | | GitHub SSH | `git@github.com:owner/repo.git` | SSH clone URL | | GitHub HTTPS | `https://github.com/owner/repo` | Full HTTPS URL | | Git URL | `git:https://git.corp.dev/team/skills` | Any non-GitHub git remote | | Well-known HTTPS | `https://cli.sentry.dev` | HTTP source using `.well-known/skills/` | | Local path | `path:./my-sk