Skip to content

Commit 45868c9

Browse files
isaacsisaacs
authored
Merge branch 'develop' into chore/remix-replace-glob-with-native-fs
2 parents 646f09f + 03ea6dd commit 45868c9

File tree

44 files changed

+1532
-633
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+1532
-633
lines changed

.claude/skills/add-cdn-bundle/SKILL.md renamed to .agents/skills/add-cdn-bundle/SKILL.md

File renamed without changes.

‎.agents/skills/dotagents/SKILL.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
name: dotagents
3+
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.
4+
---
5+
6+
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/`.
7+
8+
## References
9+
10+
Read the relevant reference when the task requires deeper detail:
11+
12+
| Document | Read When |
13+
| ---------------------------------------------------------- | ------------------------------------------------------------------------- |
14+
| [references/cli-reference.md](references/cli-reference.md) | Full command options, flags, examples |
15+
| [references/configuration.md](references/configuration.md) | Editing agents.toml, source formats, trust, MCP, hooks, wildcards, scopes |
16+
| [references/config-schema.md](references/config-schema.md) | Exact field names, types, and defaults |
17+
18+
## Quick Start
19+
20+
```bash
21+
# Initialize a new project (interactive TUI)
22+
dotagents init
23+
24+
# Add a skill from GitHub
25+
dotagents add getsentry/skills find-bugs
26+
27+
# Add multiple skills at once
28+
dotagents add getsentry/skills find-bugs code-review commit
29+
30+
# Add all skills from a repo
31+
dotagents add getsentry/skills --all
32+
33+
# Add a pinned skill
34+
dotagents add getsentry/warden@v1.0.0
35+
36+
# Install all dependencies from agents.toml
37+
dotagents install
38+
39+
# List installed skills
40+
dotagents list
41+
```
42+
43+
## Commands
44+
45+
| Command | Description |
46+
| --------------------------- | ------------------------------------------------------------------ |
47+
| `dotagents init` | Initialize `agents.toml` and `.agents/` directory |
48+
| `dotagents install` | Install all skills from `agents.toml` |
49+
| `dotagents add <specifier>` | Add a skill dependency |
50+
| `dotagents remove <name>` | Remove a skill |
51+
| `dotagents update [name]` | Update skills to latest versions |
52+
| `dotagents sync` | Reconcile state (adopt orphans, repair symlinks, verify integrity) |
53+
| `dotagents list` | Show installed skills and their status |
54+
| `dotagents mcp` | Add, remove, or list MCP server declarations |
55+
56+
All commands accept `--user` to operate on user scope (`~/.agents/`) instead of the current project.
57+
58+
For full options and flags, read [references/cli-reference.md](references/cli-reference.md).
59+
60+
## Source Formats
61+
62+
| Format | Example | Description |
63+
| ---------------- | -------------------------------------- | ------------------------------------- |
64+
| GitHub shorthand | `getsentry/skills` | Owner/repo (resolves to GitHub HTTPS) |
65+
| GitHub pinned | `getsentry/warden@v1.0.0` | With tag, branch, or commit |
66+
| GitHub SSH | `git@github.com:owner/repo.git` | SSH clone URL |
67+
| GitHub HTTPS | `https://github.com/owner/repo` | Full HTTPS URL |
68+
| Git URL | `git:https://git.corp.dev/team/skills` | Any non-GitHub git remote |
69+
| Local path | `path:./my-skills/custom` | Relative to project root |
70+
71+
## Key Concepts
72+
73+
- **`.agents/skills/`** is the canonical home for all installed skills
74+
- **`agents.toml`** declares dependencies; **`agents.lock`** pins exact commits and integrity hashes
75+
- **Symlinks**: `.claude/skills/`, `.cursor/skills/` point to `.agents/skills/`
76+
- **Wildcards**: `name = "*"` installs all skills from a source, with optional `exclude` list
77+
- **Trust**: Optional `[trust]` section restricts which sources are allowed
78+
- **Hooks**: `[[hooks]]` declarations write tool-event hooks to each agent's config
79+
- **Gitignore**: When `gitignore = true`, managed skills are gitignored; custom in-place skills are tracked
80+
- **User scope**: `--user` flag manages skills in `~/.agents/` shared across all projects

‎.agents/skills/dotagents/references/cli-reference.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# CLI Reference
2+
3+
## Usage
4+
5+
```
6+
dotagents [--user] <command> [options]
7+
```
8+
9+
### Global Flags
10+
11+
| Flag | Description |
12+
| ----------------- | --------------------------------------------------------------- |
13+
| `--user` | Operate on user scope (`~/.agents/`) instead of current project |
14+
| `--help`, `-h` | Show help |
15+
| `--version`, `-V` | Show version |
16+
17+
## Commands
18+
19+
### `init`
20+
21+
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.
22+
23+
```bash
24+
dotagents init
25+
dotagents init --agents claude,cursor
26+
dotagents init --force
27+
dotagents --user init
28+
```
29+
30+
| Flag | Description |
31+
| ----------------- | ----------------------------------------------------------------------- |
32+
| `--agents <list>` | Comma-separated agent targets (claude, cursor, codex, vscode, opencode) |
33+
| `--force` | Overwrite existing `agents.toml` |
34+
35+
**Interactive mode** (when TTY is available):
36+
37+
1. Select agents (multiselect)
38+
2. Manage `.gitignore` for installed skills?
39+
3. Trust policy: allow all sources or restrict to trusted
40+
4. If restricted: enter trusted GitHub orgs/repos (comma-separated)
41+
42+
### `install`
43+
44+
Install all skill dependencies declared in `agents.toml`.
45+
46+
```bash
47+
dotagents install
48+
dotagents install --frozen
49+
dotagents install --force
50+
```
51+
52+
| Flag | Description |
53+
| ---------- | ------------------------------------------------------------------ |
54+
| `--frozen` | Fail if lockfile is missing or out of sync; do not modify lockfile |
55+
| `--force` | Ignore locked commits and resolve all skills to latest refs |
56+
57+
**Workflow:**
58+
59+
1. Load config and lockfile
60+
2. Expand wildcard entries (discover all skills from source)
61+
3. Validate trust for each skill source
62+
4. Resolve skills (use locked commits when available)
63+
5. Copy skills into `.agents/skills/<name>/`
64+
6. Write/update lockfile with integrity hashes
65+
7. Generate `.agents/.gitignore` (if `gitignore = true`)
66+
8. Create/verify agent symlinks
67+
9. Write MCP and hook configs
68+
69+
### `add <specifier> [skill...]`
70+
71+
Add one or more skill dependencies and install them.
72+
73+
```bash
74+
dotagents add getsentry/skills # Interactive selection if multiple skills
75+
dotagents add getsentry/skills find-bugs # Add by positional name
76+
dotagents add getsentry/skills find-bugs code-review # Add multiple skills at once
77+
dotagents add getsentry/skills --name find-bugs # Add by --name flag
78+
dotagents add getsentry/skills --skill find-bugs # --skill is an alias for --name
79+
dotagents add getsentry/skills --all # Add all as wildcard
80+
dotagents add getsentry/warden@v1.0.0 # Pinned ref (inline)
81+
dotagents add getsentry/skills --ref v2.0.0 # Pinned ref (flag)
82+
dotagents add git:https://git.corp.dev/team/skills # Non-GitHub git URL
83+
dotagents add path:./my-skills/custom # Local path
84+
```
85+
86+
| Flag | Description |
87+
| ---------------- | ----------------------------------------------------------------- |
88+
| `--name <name>` | Specify which skill to add (repeatable; alias: `--skill`) |
89+
| `--skill <name>` | Alias for `--name` (repeatable) |
90+
| `--ref <ref>` | Pin to a specific tag, branch, or commit |
91+
| `--all` | Add all skills from the source as a wildcard entry (`name = "*"`) |
92+
93+
**Specifier formats:**
94+
95+
- `owner/repo` -- GitHub shorthand
96+
- `owner/repo@ref` -- GitHub with pinned ref
97+
- `https://github.com/owner/repo` -- GitHub HTTPS URL
98+
- `git@github.com:owner/repo.git` -- GitHub SSH URL
99+
- `git:https://...` -- Non-GitHub git URL
100+
- `path:../relative` -- Local filesystem path
101+
102+
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).
103+
104+
When adding multiple skills, already-existing entries are skipped with a warning. An error is only raised if all specified skills already exist.
105+
106+
`--all` and `--name`/positional args are mutually exclusive.
107+
108+
### `remove <name>`
109+
110+
Remove a skill dependency.
111+
112+
```bash
113+
dotagents remove find-bugs
114+
```
115+
116+
Removes from `agents.toml`, deletes `.agents/skills/<name>/`, updates lockfile, and regenerates `.gitignore`.
117+
118+
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.
119+
120+
### `update [name]`
121+
122+
Update skills to their latest versions.
123+
124+
```bash
125+
dotagents update # Update all
126+
dotagents update find-bugs # Update one
127+
```
128+
129+
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.
130+
131+
### `sync`
132+
133+
Reconcile project state: adopt orphans, verify integrity, repair symlinks and configs.
134+
135+
```bash
136+
dotagents sync
137+
```
138+
139+
**Actions performed:**
140+
141+
1. Adopt orphaned skills (installed but not declared in config)
142+
2. Regenerate `.agents/.gitignore`
143+
3. Check for missing skills
144+
4. Verify integrity hashes
145+
5. Repair agent symlinks
146+
6. Verify/repair MCP configs
147+
7. Verify/repair hook configs
148+
149+
Reports issues as warnings (modified skills, missing MCP/hook configs) or errors (missing skills).
150+
151+
### `list`
152+
153+
Show installed skills and their status.
154+
155+
```bash
156+
dotagents list
157+
dotagents list --json
158+
```
159+
160+
| Flag | Description |
161+
| -------- | -------------- |
162+
| `--json` | Output as JSON |
163+
164+
**Status indicators:**
165+
166+
- `✓` ok -- installed, integrity matches
167+
- `~` modified -- locally modified since install
168+
- `✗` missing -- in config but not installed
169+
- `?` unlocked -- installed but not in lockfile
170+
171+
Skills from wildcard entries are marked with a wildcard indicator.
172+
173+
### `mcp`
174+
175+
Manage MCP (Model Context Protocol) server declarations in `agents.toml`.
176+
177+
#### `mcp add <name>`
178+
179+
Add an MCP server declaration.
180+
181+
```bash
182+
dotagents mcp add github --command npx --args -y --args @modelcontextprotocol/server-github --env GITHUB_TOKEN
183+
dotagents mcp add remote-api --url https://mcp.example.com/sse --header "Authorization:Bearer token"
184+
```
185+
186+
| Flag | Description |
187+
| ---------------------- | ------------------------------------------------------- |
188+
| `--command <cmd>` | Command to run (stdio transport) |
189+
| `--args <arg>` | Command arguments (repeatable) |
190+
| `--url <url>` | HTTP endpoint URL (HTTP transport) |
191+
| `--header <Key:Value>` | HTTP headers (repeatable) |
192+
| `--env <VAR>` | Environment variable names to pass through (repeatable) |
193+
194+
Either `--command` or `--url` is required (mutually exclusive).
195+
196+
#### `mcp remove <name>`
197+
198+
Remove an MCP server declaration.
199+
200+
```bash
201+
dotagents mcp remove github
202+
```
203+
204+
#### `mcp list`
205+
206+
Show declared MCP servers.
207+
208+
```bash
209+
dotagents mcp list
210+
dotagents mcp list --json
211+
```
212+
213+
| Flag | Description |
214+
| -------- | -------------- |
215+
| `--json` | Output as JSON |

0 commit comments

Comments
 (0)