Skip to content

Commit 4cffe7d

Browse files
chargomechargome
committed
fmt
1 parent 9b7cc17 commit 4cffe7d

File tree

8 files changed

+256
-194
lines changed

8 files changed

+256
-194
lines changed

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

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,11 @@ Manage agent skill dependencies declared in `agents.toml`. dotagents resolves, i
99

1010
Read the relevant reference when the task requires deeper detail:
1111

12-
| Document | Read When |
13-
|----------|-----------|
14-
| [references/cli-reference.md](references/cli-reference.md) | Full command options, flags, examples |
12+
| Document | Read When |
13+
| ---------------------------------------------------------- | ------------------------------------------------------------------------- |
14+
| [references/cli-reference.md](references/cli-reference.md) | Full command options, flags, examples |
1515
| [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 |
16+
| [references/config-schema.md](references/config-schema.md) | Exact field names, types, and defaults |
1717

1818
## Quick Start
1919

@@ -42,31 +42,31 @@ dotagents list
4242

4343
## Commands
4444

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

5656
All commands accept `--user` to operate on user scope (`~/.agents/`) instead of the current project.
5757

5858
For full options and flags, read [references/cli-reference.md](references/cli-reference.md).
5959

6060
## Source Formats
6161

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

7171
## Key Concepts
7272

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

Lines changed: 33 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@ dotagents [--user] <command> [options]
88

99
### Global Flags
1010

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

1717
## Commands
1818

@@ -27,12 +27,13 @@ dotagents init --force
2727
dotagents --user init
2828
```
2929

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

3535
**Interactive mode** (when TTY is available):
36+
3637
1. Select agents (multiselect)
3738
2. Manage `.gitignore` for installed skills?
3839
3. Trust policy: allow all sources or restrict to trusted
@@ -48,12 +49,13 @@ dotagents install --frozen
4849
dotagents install --force
4950
```
5051

51-
| Flag | Description |
52-
|------|-------------|
52+
| Flag | Description |
53+
| ---------- | ------------------------------------------------------------------ |
5354
| `--frozen` | Fail if lockfile is missing or out of sync; do not modify lockfile |
54-
| `--force` | Ignore locked commits and resolve all skills to latest refs |
55+
| `--force` | Ignore locked commits and resolve all skills to latest refs |
5556

5657
**Workflow:**
58+
5759
1. Load config and lockfile
5860
2. Expand wildcard entries (discover all skills from source)
5961
3. Validate trust for each skill source
@@ -81,14 +83,15 @@ dotagents add git:https://git.corp.dev/team/skills # Non-GitHub git URL
8183
dotagents add path:./my-skills/custom # Local path
8284
```
8385

84-
| Flag | Description |
85-
|------|-------------|
86-
| `--name <name>` | Specify which skill to add (repeatable; alias: `--skill`) |
87-
| `--skill <name>` | Alias for `--name` (repeatable) |
88-
| `--ref <ref>` | Pin to a specific tag, branch, or commit |
89-
| `--all` | Add all skills from the source as a wildcard entry (`name = "*"`) |
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 = "*"`) |
9092

9193
**Specifier formats:**
94+
9295
- `owner/repo` -- GitHub shorthand
9396
- `owner/repo@ref` -- GitHub with pinned ref
9497
- `https://github.com/owner/repo` -- GitHub HTTPS URL
@@ -134,6 +137,7 @@ dotagents sync
134137
```
135138

136139
**Actions performed:**
140+
137141
1. Adopt orphaned skills (installed but not declared in config)
138142
2. Regenerate `.agents/.gitignore`
139143
3. Check for missing skills
@@ -153,11 +157,12 @@ dotagents list
153157
dotagents list --json
154158
```
155159

156-
| Flag | Description |
157-
|------|-------------|
160+
| Flag | Description |
161+
| -------- | -------------- |
158162
| `--json` | Output as JSON |
159163

160164
**Status indicators:**
165+
161166
- `✓` ok -- installed, integrity matches
162167
- `~` modified -- locally modified since install
163168
- `✗` missing -- in config but not installed
@@ -178,13 +183,13 @@ dotagents mcp add github --command npx --args -y --args @modelcontextprotocol/se
178183
dotagents mcp add remote-api --url https://mcp.example.com/sse --header "Authorization:Bearer token"
179184
```
180185

181-
| Flag | Description |
182-
|------|-------------|
183-
| `--command <cmd>` | Command to run (stdio transport) |
184-
| `--args <arg>` | Command arguments (repeatable) |
185-
| `--url <url>` | HTTP endpoint URL (HTTP transport) |
186-
| `--header <Key:Value>` | HTTP headers (repeatable) |
187-
| `--env <VAR>` | Environment variable names to pass through (repeatable) |
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) |
188193

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

@@ -205,6 +210,6 @@ dotagents mcp list
205210
dotagents mcp list --json
206211
```
207212

208-
| Flag | Description |
209-
|------|-------------|
213+
| Flag | Description |
214+
| -------- | -------------- |
210215
| `--json` | Output as JSON |

‎.agents/skills/dotagents/references/config-schema.md‎

Lines changed: 47 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,11 @@ agents = ["claude", "cursor"] # Optional, agent targets
1616

1717
## Top-Level Fields
1818

19-
| Field | Type | Required | Default | Description |
20-
|-------|------|----------|---------|-------------|
21-
| `version` | integer | Yes | -- | Schema version, must be `1` |
22-
| `gitignore` | boolean | No | `true` | Generate `.agents/.gitignore` for managed skills. |
23-
| `agents` | string[] | No | `[]` | Agent targets: `claude`, `cursor`, `codex`, `vscode`, `opencode` |
19+
| Field | Type | Required | Default | Description |
20+
| ----------- | -------- | -------- | ------- | ---------------------------------------------------------------- |
21+
| `version` | integer | Yes | -- | Schema version, must be `1` |
22+
| `gitignore` | boolean | No | `true` | Generate `.agents/.gitignore` for managed skills. |
23+
| `agents` | string[] | No | `[]` | Agent targets: `claude`, `cursor`, `codex`, `vscode`, `opencode` |
2424

2525
## Project Section
2626

@@ -50,12 +50,12 @@ ref = "v1.0.0" # Optional, pin to tag/branch/commit
5050
path = "tools/my-skill" # Optional, subdirectory within repo
5151
```
5252

53-
| Field | Type | Required | Description |
54-
|-------|------|----------|-------------|
55-
| `name` | string | Yes | Unique identifier. Pattern: `^[a-zA-Z0-9][a-zA-Z0-9._-]*$` |
56-
| `source` | string | Yes | `owner/repo`, `owner/repo@ref`, `git:url`, or `path:relative` |
57-
| `ref` | string | No | Tag, branch, or commit SHA to pin |
58-
| `path` | string | No | Subdirectory containing the skill within the source repo |
53+
| Field | Type | Required | Description |
54+
| -------- | ------ | -------- | ------------------------------------------------------------- |
55+
| `name` | string | Yes | Unique identifier. Pattern: `^[a-zA-Z0-9][a-zA-Z0-9._-]*$` |
56+
| `source` | string | Yes | `owner/repo`, `owner/repo@ref`, `git:url`, or `path:relative` |
57+
| `ref` | string | No | Tag, branch, or commit SHA to pin |
58+
| `path` | string | No | Subdirectory containing the skill within the source repo |
5959

6060
### Wildcard Skills
6161

@@ -67,12 +67,12 @@ ref = "v1.0.0" # Optional
6767
exclude = ["deprecated-skill"] # Optional, skills to skip
6868
```
6969

70-
| Field | Type | Required | Description |
71-
|-------|------|----------|-------------|
72-
| `name` | literal `"*"` | Yes | Wildcard marker |
73-
| `source` | string | Yes | Same formats as regular skills |
74-
| `ref` | string | No | Tag, branch, or commit SHA to pin |
75-
| `exclude` | string[] | No | Skill names to skip. Default: `[]` |
70+
| Field | Type | Required | Description |
71+
| --------- | ------------- | -------- | ---------------------------------- |
72+
| `name` | literal `"*"` | Yes | Wildcard marker |
73+
| `source` | string | Yes | Same formats as regular skills |
74+
| `ref` | string | No | Tag, branch, or commit SHA to pin |
75+
| `exclude` | string[] | No | Skill names to skip. Default: `[]` |
7676

7777
## Trust Section
7878

@@ -87,12 +87,12 @@ github_repos = ["ext-org/repo"] # Exact owner/repo pairs
8787
git_domains = ["git.corp.example.com"] # Git URL domains
8888
```
8989

90-
| Field | Type | Description |
91-
|-------|------|-------------|
92-
| `allow_all` | boolean | Allow all sources (overrides other fields) |
93-
| `github_orgs` | string[] | Allowed GitHub organizations |
94-
| `github_repos` | string[] | Allowed exact `owner/repo` pairs |
95-
| `git_domains` | string[] | Allowed domains for `git:` URLs |
90+
| Field | Type | Description |
91+
| -------------- | -------- | ------------------------------------------ |
92+
| `allow_all` | boolean | Allow all sources (overrides other fields) |
93+
| `github_orgs` | string[] | Allowed GitHub organizations |
94+
| `github_repos` | string[] | Allowed exact `owner/repo` pairs |
95+
| `git_domains` | string[] | Allowed domains for `git:` URLs |
9696

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

@@ -116,14 +116,14 @@ name = "remote-api" # Required, unique server name
116116
url = "https://mcp.example.com/sse" # Required for HTTP
117117
```
118118

119-
| Field | Type | Required | Description |
120-
|-------|------|----------|-------------|
121-
| `name` | string | Yes | Unique server identifier |
122-
| `command` | string | Stdio only | Command to execute |
123-
| `args` | string[] | No | Command arguments |
124-
| `env` | string[] | No | Environment variable names to pass through |
125-
| `url` | string | HTTP only | Server URL |
126-
| `headers` | table | No | HTTP headers |
119+
| Field | Type | Required | Description |
120+
| --------- | -------- | ---------- | ------------------------------------------ |
121+
| `name` | string | Yes | Unique server identifier |
122+
| `command` | string | Stdio only | Command to execute |
123+
| `args` | string[] | No | Command arguments |
124+
| `env` | string[] | No | Environment variable names to pass through |
125+
| `url` | string | HTTP only | Server URL |
126+
| `headers` | table | No | HTTP headers |
127127

128128
## Hooks Section
129129

@@ -134,11 +134,11 @@ matcher = "Bash" # Optional, tool name filter
134134
command = "my-lint-check" # Required
135135
```
136136

137-
| Field | Type | Required | Description |
138-
|-------|------|----------|-------------|
139-
| `event` | string | Yes | `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop` |
140-
| `matcher` | string | No | Tool name to match (omit for all tools) |
141-
| `command` | string | Yes | Shell command to execute |
137+
| Field | Type | Required | Description |
138+
| --------- | ------ | -------- | ------------------------------------------------------- |
139+
| `event` | string | Yes | `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop` |
140+
| `matcher` | string | No | Tool name to match (omit for all tools) |
141+
| `command` | string | Yes | Shell command to execute |
142142

143143
## Lockfile (agents.lock)
144144

@@ -156,20 +156,20 @@ commit = "c8881564e75eff4faaecc82d1c3f13356851b6e7"
156156
integrity = "sha256-FWmCLdOj+x+XffiEg7Bx19drylVypeKz8me9OA757js="
157157
```
158158

159-
| Field | Type | Description |
160-
|-------|------|-------------|
161-
| `source` | string | Original source from `agents.toml` |
162-
| `resolved_url` | string | Resolved git URL |
163-
| `resolved_path` | string | Subdirectory within repo |
164-
| `resolved_ref` | string | Ref that was resolved (omitted for default branch) |
165-
| `commit` | string | Full 40-char SHA of resolved commit |
166-
| `integrity` | string | `sha256-` prefixed base64 content hash |
159+
| Field | Type | Description |
160+
| --------------- | ------ | -------------------------------------------------- |
161+
| `source` | string | Original source from `agents.toml` |
162+
| `resolved_url` | string | Resolved git URL |
163+
| `resolved_path` | string | Subdirectory within repo |
164+
| `resolved_ref` | string | Ref that was resolved (omitted for default branch) |
165+
| `commit` | string | Full 40-char SHA of resolved commit |
166+
| `integrity` | string | `sha256-` prefixed base64 content hash |
167167

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

170170
## Environment Variables
171171

172-
| Variable | Purpose |
173-
|----------|---------|
172+
| Variable | Purpose |
173+
| --------------------- | ------------------------------------------------------- |
174174
| `DOTAGENTS_STATE_DIR` | Override cache location (default: `~/.local/dotagents`) |
175-
| `DOTAGENTS_HOME` | Override user-scope location (default: `~/.agents`) |
175+
| `DOTAGENTS_HOME` | Override user-scope location (default: `~/.agents`) |

0 commit comments

Comments
 (0)