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

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:

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

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

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

CLI Reference

Usage

dotagents [--user] <command> [options]

Global Flags

Commands

init

Initialize a new project with agents.toml and .agents/ directory. Automatically includes the dotagents skill from getsentry/dotagents for CLI guidance, and attempts to install it.

dotagents init
dotagents init --agents claude,cursor
dotagents init --force
dotagents --user init

Interactive mode (when TTY is available):

1. Select agents (multiselect) 2. Manage .gitignore for installed skills? 3. Trust policy: allow all sources or restrict to trusted 4. If restricted: enter trusted GitHub orgs/repos (comma-separated)

install

Install all skill dependencies declared in agents.toml.

dotagents install
dotagents install --frozen
dotagents install --force

Workflow:

1. Load config and lockfile 2. Expand wildcard entries (discover all skills from source) 3. Validate trust for each skill source 4. Resolve skills (use locked commits when available) 5. Copy skills into .agents/skills/<name>/ 6. Write/update lockfile with integrity hashes 7. Generate .agents/.gitignore (if gitignore = true) 8. Create/verify agent symlinks 9. Write MCP and hook configs

add <specifier> [skill...]

Add one or more skill dependencies and install them.

dotagents add getsentry/skills                          # Interactive selection if multiple skills
dotagents add getsentry/skills find-bugs                # Add by positional name
dotagents add getsentry/skills find-bugs code-review    # Add multiple skills at once
dotagents add getsentry/skills --name find-bugs         # Add by --name flag
dotagents add getsentry/skills --skill find-bugs        # --skill is an alias for --name
dotagents add getsentry/skills --all                    # Add all as wildcard
dotagents add getsentry/warden@v1.0.0                   # Pinned ref (inline)
dotagents add getsentry/skills --ref v2.0.0             # Pinned ref (flag)
dotagents add git:https://git.corp.dev/team/skills      # Non-GitHub git URL
dotagents add path:./my-skills/custom                   # Local path

Specifier formats:

• owner/repo -- GitHub shorthand
• owner/repo@ref -- GitHub with pinned ref
• https://github.com/owner/repo -- GitHub HTTPS URL
• git@github.com:owner/repo.git -- GitHub SSH URL
• git:https://... -- Non-GitHub git URL
• path:../relative -- Local filesystem path

When a repo contains multiple skills, dotagents auto-discovers them. If only one skill is found, it's added automatically. If multiple are found and no names are given, an interactive picker is shown (TTY) or skills are listed (non-TTY).

When adding multiple skills, already-existing entries are skipped with a warning. An error is only raised if all specified skills already exist.

--all and --name/positional args are mutually exclusive.

remove <name>

Remove a skill dependency.

dotagents remove find-bugs

Removes from agents.toml, deletes .agents/skills/<name>/, updates lockfile, and regenerates .gitignore.

For skills sourced from a wildcard entry (name = "*"), interactively prompts whether to add the skill to the wildcard's exclude list. If declined, the removal is cancelled.

update [name]

Update skills to their latest versions.

dotagents update           # Update all
dotagents update find-bugs # Update one

Skips skills pinned to immutable commits (40-char SHAs). For wildcard entries, re-discovers all skills in the source -- adds new ones, removes deleted ones. Prints changelog showing old and new commits.

sync

Reconcile project state: adopt orphans, verify integrity, repair symlinks and configs.

dotagents sync

Actions performed:

1. Adopt orphaned skills (installed but not declared in config) 2. Regenerate .agents/.gitignore 3. Check for missing skills 4. Verify integrity hashes 5. Repair agent symlinks 6. Verify/repair MCP configs 7. Verify/repair hook configs

Reports issues as warnings (modified skills, missing MCP/hook configs) or errors (missing skills).

list

Show installed skills and their status.

dotagents list
dotagents list --json

Status indicators:

• ✓ ok -- installed, integrity matches
• ~ modified -- locally modified since install
• ✗ missing -- in config but not installed
• ? unlocked -- installed but not in lockfile

Skills from wildcard entries are marked with a wildcard indicator.

mcp

Manage MCP (Model Context Protocol) server declarations in agents.toml.

mcp add <name>

Add an MCP server declaration.

dotagents mcp add github --command npx --args -y --args @modelcontextprotocol/server-github --env GITHUB_TOKEN
dotagents mcp add remote-api --url https://mcp.example.com/sse --header "Authorization:Bearer token"

Either --command or --url is required (mutually exclusive).

mcp remove <name>

Remove an MCP server declaration.

dotagents mcp remove github

mcp list

Show declared MCP servers.

dotagents mcp list
dotagents mcp list --json

agents.toml Configuration Schema

Top-Level Structure

version = 1                     # Required, must be 1
gitignore = true                # Optional, default true
agents = ["claude", "cursor"]   # Optional, agent targets

[project]                       # Optional
[trust]                         # Optional
[[skills]]                      # Optional, array of skill entries
[[mcp]]                         # Optional, array of MCP servers
[[hooks]]                       # Optional, array of hook declarations

Top-Level Fields

Project Section

[project]
name = "my-project"             # Optional, display name

Symlinks Section

[symlinks]
targets = [".claude", ".cursor"]  # Legacy: explicit symlink targets

When agents is set, symlink targets are derived automatically. The [symlinks] section is for backward compatibility.

Skills Section

Regular Skills

[[skills]]
name = "find-bugs"              # Required, unique skill identifier
source = "getsentry/skills"     # Required, skill source
ref = "v1.0.0"                  # Optional, pin to tag/branch/commit
path = "tools/my-skill"         # Optional, subdirectory within repo

Wildcard Skills

[[skills]]
name = "*"                      # Wildcard: install all skills from source
source = "getsentry/skills"     # Required
ref = "v1.0.0"                  # Optional
exclude = ["deprecated-skill"]  # Optional, skills to skip

Trust Section

[trust]
allow_all = true                    # Allow any source

# OR restrict to specific sources:
[trust]
github_orgs = ["getsentry"]         # GitHub org names
github_repos = ["ext-org/repo"]     # Exact owner/repo pairs
git_domains = ["git.corp.example.com"]  # Git URL domains

No [trust] section = allow all sources (backward compatible).

MCP Section

Stdio Transport

[[mcp]]
name = "github"                     # Required, unique server name
command = "npx"                     # Required for stdio
args = ["-y", "@modelcontextprotocol/server-github"]  # Optional
env = ["GITHUB_TOKEN"]             # Optional, env vars to pass through

HTTP Transport

[[mcp]]
name = "remote-api"                 # Required, unique server name
url = "https://mcp.example.com/sse" # Required for HTTP

Hooks Section

[[hooks]]
event = "PreToolUse"                # Required
matcher = "Bash"                    # Optional, tool name filter
command = "my-lint-check"           # Required

Lockfile (agents.lock)

Auto-generated. Do not edit manually.

version = 1

[skills.find-bugs]
source = "getsentry/skills"
resolved_url = "https://github.com/getsentry/skills.git"
resolved_path = "plugins/sentry-skills/skills/find-bugs"
resolved_ref = "v1.0.0"
commit = "c8881564e75eff4faaecc82d1c3f13356851b6e7"
integrity = "sha256-FWmCLdOj+x+XffiEg7Bx19drylVypeKz8me9OA757js="

Local path skills have source and integrity only (no commit).

Environment Variables

Configuration (agents.toml)

See config-schema.md for the complete schema reference.

Minimal Example

version = 1
agents = ["claude"]

[[skills]]
name = "find-bugs"
source = "getsentry/skills"

Skills

Each skill requires name and source. Optionally pin with ref or specify a subdirectory with path.

[[skills]]
name = "find-bugs"
source = "getsentry/skills"
ref = "v1.0.0"
path = "plugins/sentry-skills/skills/find-bugs"

Source formats:

Skill name rules: Must start with alphanumeric, contain only [a-zA-Z0-9._-].

Wildcard Skills

Add all skills from a source with a single entry:

[[skills]]
name = "*"
source = "getsentry/skills"
exclude = ["deprecated-skill"]

During install and update, dotagents discovers all skills in the source and installs each one (except those in exclude). Each skill gets its own lockfile entry. Use dotagents add <source> --all to create a wildcard entry from the CLI.

Trust

Restrict which sources are allowed. Without a [trust] section, all sources are allowed.

# Allow all sources explicitly
[trust]
allow_all = true

# Restrict to specific GitHub orgs and repos
[trust]
github_orgs = ["getsentry"]
github_repos = ["external-org/specific-repo"]
git_domains = ["git.corp.example.com"]

• GitHub sources match against github_orgs (by owner) or github_repos (exact owner/repo)
• Git URL sources match against git_domains
• Local path: sources are always allowed
• A source passes if it matches any rule (org OR repo OR domain)

Trust is validated before any network operations in add and install.

MCP Servers

Declare MCP servers that get written to each agent's config.

# Stdio transport
[[mcp]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = ["GITHUB_TOKEN"]

# HTTP transport
[[mcp]]
name = "remote-api"
url = "https://mcp.example.com/sse"
headers = { Authorization = "Bearer token" }

MCP configs are written per-agent in the appropriate format:

• Claude: .mcp.json (JSON)
• Cursor: .cursor/mcp.json (JSON)
• Codex: .codex/config.toml (TOML, shared with other Codex config)
• VS Code: .vscode/mcp.json (JSON)
• OpenCode: opencode.json (JSON, shared)

Hooks

Declare hooks for agent tool events.

[[hooks]]
event = "PreToolUse"
matcher = "Bash"
command = "my-lint-check"

Supported events: PreToolUse, PostToolUse, UserPromptSubmit, Stop

Hook configs are written per-agent:

• Claude: .claude/settings.json (merged into existing file)
• Cursor: .cursor/hooks.json (dedicated file, events mapped to Cursor equivalents)
• VS Code: .claude/settings.json (same file as Claude)
• Codex/OpenCode: not supported (warnings emitted during install/sync)

Cursor event mapping:

• PreToolUse -> beforeShellExecution + beforeMCPExecution
• PostToolUse -> afterFileEdit
• UserPromptSubmit -> beforeSubmitPrompt
• Stop -> stop

Agents

The agents array controls which agent tools get symlinks and configs.

agents = ["claude", "cursor", "codex", "vscode", "opencode"]

Each agent gets:

• A <agent-dir>/skills/ symlink pointing to .agents/skills/ (Claude, Cursor)
• Or native discovery from .agents/skills/ (Codex, VS Code, OpenCode)
• MCP server configs in the agent's config file
• Hook configs (where supported)

Scopes

Project Scope (default)

Operates on the current project. Requires agents.toml at the project root.

User Scope (--user)

Operates on ~/.agents/ for skills shared across all projects. Override with DOTAGENTS_HOME.

dotagents --user init
dotagents --user add getsentry/skills --all

User-scope symlinks go to ~/.claude/skills/ and ~/.cursor/skills/.

When no agents.toml exists and you're not inside a git repo, dotagents falls back to user scope automatically.

Gitignore

When gitignore = true (schema default), dotagents generates .agents/.gitignore listing managed (remote) skills. In-place skills (path:.agents/skills/...) are never gitignored since they must be tracked in git.

When gitignore = false, no gitignore is created -- skills are checked into the repository. Anyone cloning gets skills without running install.

Caching

• Cache location: ~/.local/dotagents/ (override with DOTAGENTS_STATE_DIR)
• Unpinned repos: cached with 24-hour TTL
• Pinned refs (40-char SHA): cached immutably, never re-fetched
• Use dotagents install --force to bypass cache

Troubleshooting

Skills not installing:

• Check agents.toml syntax with dotagents list
• Verify source is accessible (git clone the URL manually)
• Check trust config if using restricted mode

Symlinks broken:

• Run dotagents sync to repair

Integrity mismatch:

• Skill was modified locally -- run dotagents install --force to restore
• Or run dotagents sync to detect and report issues