SKILL.md
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](references/cli-reference.md) |
Full command options, flags, examples |
| [references/configuration.md](references/configuration.md) |
Editing agents.toml, source formats, trust, MCP, hooks, wildcards, scopes |
| [references/config-schema.md](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/[email protected]
# 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](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 |
| 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