dotagents

Manage agent skill dependencies declared in agents.toml. dotagents resolves, installs, and symlinks skills so multiple agent tools (Claude Code, Cursor, Codex, VS Code, OpenCode) discover them from .agents/skills/.

Running dotagents

Always use npx @sentry/dotagents to run commands. For example: npx @sentry/dotagents sync.

References

Read the relevant reference when the task requires deeper detail:

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

Quick Start

# Initialize a new project (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 pinned skill
npx @sentry/dotagents add getsentry/[email protected]

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

# List installed skills
npx @sentry/dotagents list

Commands

Command	Description
npx @sentry/dotagents init	Initialize agents.toml and .agents/ directory
npx @sentry/dotagents install	Install all skills from agents.toml
npx @sentry/dotagents add <specifier>	Add a skill dependency
npx @sentry/dotagents remove <name>	Remove a skill
npx @sentry/dotagents sync	Reconcile state (adopt orphans, repair symlinks, fix configs)
npx @sentry/dotagents list	Show installed skills and their 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 project health and fix issues

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

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

Source Formats

Format	Example	Description
GitHub shorthand	getsentry/skills	Owner/repo (resolves to GitHub HTTPS)
GitHub pinned	getsentry/[email protected]	With tag, branch, or commit
GitHub SSH	[email protected]: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-skills/custom	Relative to project root

Key Concepts

• .agents/skills/ is the canonical home for all installed skills
• agents.toml declares dependencies; agents.lock tracks managed skills
• Symlinks: .claude/skills/, .cursor/skills/ point to .agents/skills/
• 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
• Gitignore: Managed skills are always gitignored; custom in-place skills are tracked
• User scope: --user flag manages skills in ~/.agents/ shared across all projects
• Updates: Run npx @sentry/dotagents install to refresh managed skills; there is no update command