From fd2a53d63da0c7c8788b0ee9110311ac0c9660a8 Mon Sep 17 00:00:00 2001 From: Greg Pstrucha <875316+gricha@users.noreply.github.com> Date: Mon, 23 Feb 2026 16:14:28 -0800 Subject: [PATCH] docs(skill): Move dotagents skill to top-level and update content Move the dotagents skill from plugins/dotagents/skills/ to the top-level skills/ directory, symlinking back from the plugin structure. This keeps the source of truth at the repo level. Updates the skill content to reflect the current CLI: - Add mcp command to SKILL.md commands table - Add positional skill args and multi-skill support to add command - Add --skill alias alongside --name - Add list --json flag to cli-reference - Fix install --force description (lockfile bypass, not reinstall) - Expand source formats with GitHub SSH and HTTPS URLs - Add hooks to Key Concepts section - Document interactive prompt on wildcard remove - Add headers field to HTTP MCP example Agent transcript: https://claudescope.sentry.dev/share/w9kPvHx_axMCozPnoWsnsxdJHNQnaw1JFe1crylYCXw --- plugins/dotagents/skills/dotagents | 1 + .../skills => skills}/dotagents/SKILL.md | 13 ++- .../dotagents/references/cli-reference.md | 80 +++++++++++++++---- .../dotagents/references/config-schema.md | 0 .../dotagents/references/configuration.md | 9 ++- 5 files changed, 83 insertions(+), 20 deletions(-) create mode 120000 plugins/dotagents/skills/dotagents rename {plugins/dotagents/skills => skills}/dotagents/SKILL.md (83%) rename {plugins/dotagents/skills => skills}/dotagents/references/cli-reference.md (57%) rename {plugins/dotagents/skills => skills}/dotagents/references/config-schema.md (100%) rename {plugins/dotagents/skills => skills}/dotagents/references/configuration.md (93%) diff --git a/plugins/dotagents/skills/dotagents b/plugins/dotagents/skills/dotagents new file mode 120000 index 0000000..dbc567c --- /dev/null +++ b/plugins/dotagents/skills/dotagents @@ -0,0 +1 @@ +../../../skills/dotagents \ No newline at end of file diff --git a/plugins/dotagents/skills/dotagents/SKILL.md b/skills/dotagents/SKILL.md similarity index 83% rename from plugins/dotagents/skills/dotagents/SKILL.md rename to skills/dotagents/SKILL.md index f4354df..8a592f0 100644 --- a/plugins/dotagents/skills/dotagents/SKILL.md +++ b/skills/dotagents/SKILL.md @@ -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 @@ -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. @@ -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 @@ -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 diff --git a/plugins/dotagents/skills/dotagents/references/cli-reference.md b/skills/dotagents/references/cli-reference.md similarity index 57% rename from plugins/dotagents/skills/dotagents/references/cli-reference.md rename to skills/dotagents/references/cli-reference.md index a93b797..5b99aba 100644 --- a/plugins/dotagents/skills/dotagents/references/cli-reference.md +++ b/skills/dotagents/references/cli-reference.md @@ -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 @@ -64,35 +64,43 @@ dotagents install --force 8. Create/verify agent symlinks 9. Write MCP and hook configs -### `add ` +### `add [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 ` | Specify which skill to add (alias: `--skill`) | +| `--name ` | Specify which skill to add (repeatable; alias: `--skill`) | +| `--skill ` | Alias for `--name` (repeatable) | | `--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 ` @@ -104,7 +112,7 @@ dotagents remove find-bugs Removes from `agents.toml`, deletes `.agents/skills//`, 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]` @@ -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 ` + +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 ` | Command to run (stdio transport) | +| `--args ` | Command arguments (repeatable) | +| `--url ` | HTTP endpoint URL (HTTP transport) | +| `--header ` | HTTP headers (repeatable) | +| `--env ` | Environment variable names to pass through (repeatable) | + +Either `--command` or `--url` is required (mutually exclusive). + +#### `mcp remove ` + +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 | diff --git a/plugins/dotagents/skills/dotagents/references/config-schema.md b/skills/dotagents/references/config-schema.md similarity index 100% rename from plugins/dotagents/skills/dotagents/references/config-schema.md rename to skills/dotagents/references/config-schema.md diff --git a/plugins/dotagents/skills/dotagents/references/configuration.md b/skills/dotagents/references/configuration.md similarity index 93% rename from plugins/dotagents/skills/dotagents/references/configuration.md rename to skills/dotagents/references/configuration.md index b2fbd36..3885d23 100644 --- a/plugins/dotagents/skills/dotagents/references/configuration.md +++ b/skills/dotagents/references/configuration.md @@ -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._-]`. @@ -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: