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 list
Commands
| 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 skills
agents.toml declares dependencies; agents.lock pins exact commits and integrity hashes
- 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: When
gitignore = true, managed skills are gitignored; custom in-place skills are tracked
- User scope:
--user flag manages skills in ~/.agents/ shared across all projects
1---2name: dotagents-23description: Manage agent skill dependencies with dotagents. Use when asked to "add a skill", "install skills", "remove a skill", "update skills", "dotagents init", "agents.toml", "agents.lock", "sync skills", "list skills", "set up dotagents", "configure trust", "add MCP server", "add hook", "wildcard skills", "user scope", or any dotagents-related task.4metadata:5 source: https://skillmd.com/skills/getsentry/dotagents-26---78Manage 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/`.910## Running dotagents1112If `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.1314## References1516Read the relevant reference when the task requires deeper detail:1718| Document | Read When |19| ---------------------------------------------------------- | ------------------------------------------------------------------------- |20| [references/cli-reference.md](references/cli-reference.md) | Full command options, flags, examples |21| [references/configuration.md](references/configuration.md) | Editing agents.toml, source formats, trust, MCP, hooks, wildcards, scopes |22| [references/config-schema.md](references/config-schema.md) | Exact field names, types, and defaults |2324## Quick Start2526```bash27# Initialize a new project (interactive TUI)28dotagents init2930# Add a skill from GitHub31dotagents add getsentry/skills find-bugs3233# Add multiple skills at once34dotagents add getsentry/skills find-bugs code-review commit3536# Add all skills from a repo37dotagents add getsentry/skills --all3839# Add a pinned skill40dotagents add getsentry/warden@v1.0.04142# Install all dependencies from agents.toml43dotagents install4445# List installed skills46dotagents list47```4849## Commands5051| Command | Description |52| --------------------------- | ------------------------------------------------------------------ |53| `dotagents init` | Initialize `agents.toml` and `.agents/` directory |54| `dotagents install` | Install all skills from `agents.toml` |55| `dotagents add <specifier>` | Add a skill dependency |56| `dotagents remove <name>` | Remove a skill |57| `dotagents update [name]` | Update skills to latest versions |58| `dotagents sync` | Reconcile state (adopt orphans, repair symlinks, verify integrity) |59| `dotagents list` | Show installed skills and their status |60| `dotagents mcp` | Add, remove, or list MCP server declarations |6162All commands accept `--user` to operate on user scope (`~/.agents/`) instead of the current project.6364For full options and flags, read [references/cli-reference.md](references/cli-reference.md).6566## Source Formats6768| Format | Example | Description |69| ---------------- | -------------------------------------- | ------------------------------------- |70| GitHub shorthand | `getsentry/skills` | Owner/repo (resolves to GitHub HTTPS) |71| GitHub pinned | `getsentry/warden@v1.0.0` | With tag, branch, or commit |72| GitHub SSH | `git@github.com:owner/repo.git` | SSH clone URL |73| GitHub HTTPS | `https://github.com/owner/repo` | Full HTTPS URL |74| Git URL | `git:https://git.corp.dev/team/skills` | Any non-GitHub git remote |75| Local path | `path:./my-skills/custom` | Relative to project root |7677## Key Concepts7879- **`.agents/skills/`** is the canonical home for all installed skills80- **`agents.toml`** declares dependencies; **`agents.lock`** pins exact commits and integrity hashes81- **Symlinks**: `.claude/skills/`, `.cursor/skills/` point to `.agents/skills/`82- **Wildcards**: `name = "*"` installs all skills from a source, with optional `exclude` list83- **Trust**: Optional `[trust]` section restricts which sources are allowed84- **Hooks**: `[[hooks]]` declarations write tool-event hooks to each agent's config85- **Gitignore**: When `gitignore = true`, managed skills are gitignored; custom in-place skills are tracked86- **User scope**: `--user` flag manages skills in `~/.agents/` shared across all projects