dotagents

by sentry

Manage agent skill dependencies with dotagents. Use when asked to "add a skill", "install skills", "remove a skill", "dotagents init", "agents.toml",…

npx skills add https://github.com/getsentry/dotagents --skill dotagents

Download ZIP GitHub

213

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/warden@v1.0.0

# 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/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-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