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
If dotagents is not available as a direct command, use npx @sentry/dotagents instead. For example: npx @sentry/dotagents sync. All commands and flags work the same way.
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)
dotagents init
# Add a skill from GitHub
dotagents add getsentry/skills find-bugs
# Add multiple skills at once
dotagents add getsentry/skills find-bugs code-review commit
# Add all skills from a repo
dotagents add getsentry/skills --all
# Add a pinned skill
dotagents add getsentry/warden@v1.0.0
# Install all dependencies from agents.toml
dotagents install
# List installed skills
dotagents listCommands
| Command | Description |
|---|---|
dotagents init | Initialize agents.toml and .agents/ directory |
dotagents install | Install all skills from agents.toml |
dotagents add <specifier> | Add a skill dependency |
dotagents remove <name> | Remove a skill |
dotagents update [name] | Update skills to latest versions |
dotagents sync | Reconcile state (adopt orphans, repair symlinks, verify integrity) |
dotagents list | Show installed skills and their status |
dotagents mcp | Add, remove, or list MCP server declarations |
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 |
| Local path | path:./my-skills/custom | Relative to project root |
Key Concepts
.agents/skills/is the canonical home for all installed skillsagents.tomldeclares dependencies;agents.lockpins exact commits and integrity hashes- Symlinks:
.claude/skills/,.cursor/skills/point to.agents/skills/ - Wildcards:
name = "*"installs all skills from a source, with optionalexcludelist - Trust: Optional
[trust]section restricts which sources are allowed - Hooks:
[[hooks]]declarations write tool-event hooks to each agent's config - Gitignore: When
gitignore = true, managed skills are gitignored; custom in-place skills are tracked - User scope:
--userflag manages skills in~/.agents/shared across all projects