Skip to content

chore(agents): Add dotagents #19526

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

Open
chargome wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

chore(agents): Add dotagents #19526

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3b72070
init
chargome Feb 25, 2026
7d5b4f6
triage
chargome Feb 25, 2026
e9f3ff9
.
chargome Feb 25, 2026
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
0 .claude/skills/add-cdn-bundle/SKILL.md → .agents/skills/add-cdn-bundle/SKILL.md
View file
Open in desktop
File renamed without changes.
80 changes: 80 additions & 0 deletions .agents/skills/dotagents/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
name: dotagents
description: 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.
---

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/`.

## 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

```bash
# 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](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
215 changes: 215 additions & 0 deletions .agents/skills/dotagents/references/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,215 @@
# CLI Reference

## Usage

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

### Global Flags

| Flag | Description |
| ----------------- | --------------------------------------------------------------- |
| `--user` | Operate on user scope (`~/.agents/`) instead of current project |
| `--help`, `-h` | Show help |
| `--version`, `-V` | Show version |

## 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.

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

| Flag | Description |
| ----------------- | ----------------------------------------------------------------------- |
| `--agents <list>` | Comma-separated agent targets (claude, cursor, codex, vscode, opencode) |
| `--force` | Overwrite existing `agents.toml` |

**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`.

```bash
dotagents install
dotagents install --frozen
dotagents install --force
```

| Flag | Description |
| ---------- | ------------------------------------------------------------------ |
| `--frozen` | Fail if lockfile is missing or out of sync; do not modify lockfile |
| `--force` | Ignore locked commits and resolve all skills to latest refs |

**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.

```bash
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 (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 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.

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

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

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

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

| Flag | Description |
| -------- | -------------- |
| `--json` | Output as 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.

```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 |
Loading
Loading