Skip to content

docs(skill): Move dotagents skill to top-level and update content #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gricha merged 1 commit into from
Feb 24, 2026
+83 −20
Merged

docs(skill): Move dotagents skill to top-level and update content #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions plugins/dotagents/skills/dotagents
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../../../skills/dotagents
Copy link

@sentry sentry bot Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The new symlink at plugins/dotagents/skills/dotagents will fail to create on standard Windows environments, causing CLI commands to crash due to permission errors.
Severity: HIGH

Suggested Fix

Implement platform-specific logic for creating symlinks. On Windows, check for permissions and consider falling back to creating a directory junction if creating a symlink fails. Add a Windows runner to the CI/CD pipeline to test this behavior.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: plugins/dotagents/skills/dotagents#L1

Potential issue: The code uses Node.js's `fs.symlink()` API to create a symlink at
`plugins/dotagents/skills/dotagents`. This API lacks cross-platform handling and has
known issues on Windows, where creating symlinks typically requires Administrator
privileges or Developer Mode. For Windows users without these permissions, CLI commands
like `dotagents init` or `dotagents sync` will attempt to create the symlink and fail
with an `EPERM` error, causing the command to crash. The CI pipeline only runs on Linux,
so this platform-specific issue was not caught during testing.

Did we get this right? 👍 / 👎 to inform future reviews.

13 changes: 10 additions & 3 deletions plugins/dotagents/skills/dotagents/SKILL.md → skills/dotagents/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,10 @@ Read the relevant reference when the task requires deeper detail:
dotagents init

# Add a skill from GitHub
dotagents add getsentry/skills --name find-bugs
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
Expand All @@ -48,6 +51,7 @@ dotagents list
| `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.

Expand All @@ -57,9 +61,11 @@ For full options and flags, read [references/cli-reference.md](references/cli-re

| Format | Example | Description |
|--------|---------|-------------|
| GitHub | `getsentry/skills` | GitHub owner/repo |
| GitHub shorthand | `getsentry/skills` | Owner/repo (resolves to GitHub HTTPS) |
| GitHub pinned | `getsentry/warden@v1.0.0` | With tag, branch, or commit |
| Git URL | `git:https://git.corp.dev/team/skills` | Any git remote |
| 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
Expand All @@ -69,5 +75,6 @@ For full options and flags, read [references/cli-reference.md](references/cli-re
- **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
80 changes: 66 additions & 14 deletions ...lls/dotagents/references/cli-reference.md → skills/dotagents/references/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ dotagents install --force
| Flag | Description |
|------|-------------|
| `--frozen` | Fail if lockfile is missing or out of sync; do not modify lockfile |
| `--force` | Re-install all skills even if already present |
| `--force` | Ignore locked commits and resolve all skills to latest refs |

**Workflow:**
1. Load config and lockfile
Expand All @@ -64,35 +64,43 @@ dotagents install --force
8. Create/verify agent symlinks
9. Write MCP and hook configs

### `add <specifier>`
### `add <specifier> [skill...]`

Add a skill dependency and install it.
Add one or more skill dependencies and install them.

```bash
dotagents add getsentry/skills
dotagents add getsentry/skills --name find-bugs
dotagents add getsentry/skills --all
dotagents add getsentry/warden@v1.0.0
dotagents add git:https://git.corp.dev/team/skills
dotagents add path:./my-skills/custom
dotagents add getsentry/skills --ref v2.0.0
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
```

| Flag | Description |
|------|-------------|
| `--name <name>` | Specify which skill to add (alias: `--skill`) |
| `--name <name>` | Specify which skill to add (repeatable; alias: `--skill`) |
| `--skill <name>` | Alias for `--name` (repeatable) |
| `--ref <ref>` | Pin to a specific tag, branch, or commit |
| `--all` | Add all skills from the source as a wildcard entry (`name = "*"`) |

**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, they're listed for selection. Use `--all` to add a wildcard entry for the entire repo.
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).

`--all` and `--name` are mutually exclusive.
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>`

Expand All @@ -104,7 +112,7 @@ 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 = "*"`), prompts to add the skill to the wildcard's `exclude` list instead of removing the whole entry.
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]`

Expand Down Expand Up @@ -156,3 +164,47 @@ dotagents list --json
- `?` 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.

```bash
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"
```

| Flag | Description |
|------|-------------|
| `--command <cmd>` | Command to run (stdio transport) |
| `--args <arg>` | Command arguments (repeatable) |
| `--url <url>` | HTTP endpoint URL (HTTP transport) |
| `--header <Key:Value>` | HTTP headers (repeatable) |
| `--env <VAR>` | Environment variable names to pass through (repeatable) |

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

#### `mcp remove <name>`

Remove an MCP server declaration.

```bash
dotagents mcp remove github
```

#### `mcp list`

Show declared MCP servers.

```bash
dotagents mcp list
dotagents mcp list --json
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |
0 ...lls/dotagents/references/config-schema.md → skills/dotagents/references/config-schema.md
View file
Open in desktop
File renamed without changes.
9 changes: 6 additions & 3 deletions ...lls/dotagents/references/configuration.md → skills/dotagents/references/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,11 @@ path = "plugins/sentry-skills/skills/find-bugs"

| Format | Example | Resolves to |
|--------|---------|-------------|
| GitHub | `getsentry/skills` | `https://github.com/getsentry/skills.git` |
| GitHub shorthand | `getsentry/skills` | `https://github.com/getsentry/skills.git` |
| GitHub pinned | `getsentry/skills@v1.0.0` | Same, checked out at `v1.0.0` |
| Git URL | `git:https://git.corp.dev/team/skills` | URL used directly |
| GitHub HTTPS | `https://github.com/owner/repo` | URL used directly |
| GitHub SSH | `git@github.com:owner/repo.git` | SSH clone |
| Git URL | `git:https://git.corp.dev/team/skills` | Any non-GitHub git remote |
| Local | `path:./my-skills/custom` | Relative to project root |

**Skill name rules:** Must start with alphanumeric, contain only `[a-zA-Z0-9._-]`.
Expand Down Expand Up @@ -86,10 +88,11 @@ command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = ["GITHUB_TOKEN"]

# HTTP transport (OAuth)
# 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:
Expand Down