diff --git a/README.md b/README.md index 91175d4..e25e065 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,13 @@ A package manager for `.agents` directories. Declare agent skill dependencies in npx @sentry/dotagents init # Add a skill from a GitHub repo -npx @sentry/dotagents add getsentry/skills find-bugs +npx @sentry/dotagents add https://github.com/getsentry/skills find-bugs # Add multiple skills at once -npx @sentry/dotagents add getsentry/skills find-bugs code-review commit +npx @sentry/dotagents add https://github.com/getsentry/skills find-bugs code-review commit # Or add all skills from a repo -npx @sentry/dotagents add getsentry/skills --all +npx @sentry/dotagents add https://github.com/getsentry/skills --all # Install all declared skills npx @sentry/dotagents install @@ -40,23 +40,23 @@ agents = ["claude"] [[skills]] name = "find-bugs" -source = "getsentry/skills" +source = "https://github.com/getsentry/skills" ``` And a lockfile (`agents.lock`) pinning the exact commit and integrity hash. ## Commands -| Command | Description | -|---------|-------------| -| `init` | Create `agents.toml` and `.agents/skills/` | -| `add [skills...]` | Add skill dependencies | -| `remove ` | Remove a skill | -| `install` | Install all dependencies from `agents.toml` | -| `update [name]` | Update skills to latest versions | -| `list` | Show installed skills and their status | -| `sync` | Reconcile gitignore, symlinks, and verify state | -| `mcp` | Manage MCP server declarations | +| Command | Description | +| -------------------------- | ----------------------------------------------- | +| `init` | Create `agents.toml` and `.agents/skills/` | +| `add [skills...]` | Add skill dependencies | +| `remove ` | Remove a skill | +| `install` | Install all dependencies from `agents.toml` | +| `update [name]` | Update skills to latest versions | +| `list` | Show installed skills and their status | +| `sync` | Reconcile gitignore, symlinks, and verify state | +| `mcp` | Manage MCP server declarations | All commands accept `--user` to operate on user scope (`~/.agents/`) instead of the current project. @@ -80,31 +80,34 @@ Use `--frozen` in CI to fail if the lockfile is missing or out of sync. Use `--f ```bash dotagents add [...] [--skill ...] [--ref ] [--all] +dotagents add [gh|gl] [...] [--skill ...] [--ref ] [--all] ``` Add one or more skills and install them. Specify skill names as positional arguments or with `--skill` flags. ```bash # Add a single skill -dotagents add getsentry/skills find-bugs +dotagents add https://github.com/getsentry/skills find-bugs # Add multiple skills -dotagents add getsentry/skills find-bugs code-review commit +dotagents add https://github.com/getsentry/skills find-bugs code-review commit # Equivalent using --skill flags -dotagents add getsentry/skills --skill find-bugs --skill code-review +dotagents add https://github.com/getsentry/skills --skill find-bugs --skill code-review # Pin to a ref -dotagents add getsentry/skills find-bugs --ref v1.0.0 +dotagents add https://github.com/getsentry/skills find-bugs --ref v1.0.0 # Add all skills as a wildcard entry -dotagents add getsentry/skills --all +dotagents add https://github.com/getsentry/skills --all ``` When a repo has one skill, it's added automatically. When multiple are found and no names are given, interactive mode shows a picker. When adding multiple skills, any that already exist in `agents.toml` are skipped with a warning. The rest are added normally. +Use explicit URLs (for example `https://github.com/getsentry/skills`) or use source hints with shorthand (for example `gh getsentry/skills` or `gl getsentry/skills`). + ### remove ```bash @@ -160,11 +163,15 @@ dotagents mcp list [--json] ```toml [[skills]] name = "find-bugs" -source = "getsentry/skills" # GitHub repo +source = "https://github.com/getsentry/skills" # GitHub URL [[skills]] name = "review" -source = "getsentry/skills@v1.0.0" # Pinned to a ref +source = "https://github.com/getsentry/skills@v1.0.0" # Pinned to a ref + +[[skills]] +name = "gitlab" +source = "https://gitlab.com/group/repo" # GitLab URL [[skills]] name = "internal" @@ -182,11 +189,12 @@ Add all skills from a repo with a single entry. Use `exclude` to skip specific o ```toml [[skills]] name = "*" -source = "getsentry/skills" +source = "https://github.com/getsentry/skills" exclude = ["deprecated-skill"] ``` -Or from the CLI: `dotagents add getsentry/skills --all` +Or from the CLI: `dotagents add https://github.com/getsentry/skills --all` +Or with shorthand + hint: `dotagents add gh getsentry/skills --all` ## Agent Targets @@ -196,13 +204,13 @@ The `agents` field tells dotagents which tools to configure. agents = ["claude", "cursor"] ``` -| Agent | Config Dir | MCP Config | Hooks | -|-------|-----------|------------|-------| -| `claude` | `.claude` | `.mcp.json` | `.claude/settings.json` | -| `cursor` | `.cursor` | `.cursor/mcp.json` | `.cursor/hooks.json` | -| `codex` | `.codex` | `.codex/config.toml` | -- | -| `vscode` | `.vscode` | `.vscode/mcp.json` | `.claude/settings.json` | -| `opencode` | `.claude` | `opencode.json` | -- | +| Agent | Config Dir | MCP Config | Hooks | +| ---------- | ---------- | -------------------- | ----------------------- | +| `claude` | `.claude` | `.mcp.json` | `.claude/settings.json` | +| `cursor` | `.cursor` | `.cursor/mcp.json` | `.cursor/hooks.json` | +| `codex` | `.codex` | `.codex/config.toml` | -- | +| `vscode` | `.vscode` | `.vscode/mcp.json` | `.claude/settings.json` | +| `opencode` | `.claude` | `opencode.json` | -- | ### Pi @@ -266,7 +274,7 @@ Use `--user` to manage skills shared across all projects: ```bash dotagents --user init -dotagents --user add getsentry/skills --all +dotagents --user add https://github.com/getsentry/skills --all ``` User-scope files live in `~/.agents/` (override with `DOTAGENTS_HOME`). diff --git a/docs/src/app/cli/page.tsx b/docs/src/app/cli/page.tsx index 618417b..947bddf 100644 --- a/docs/src/app/cli/page.tsx +++ b/docs/src/app/cli/page.tsx @@ -59,8 +59,8 @@ export default function CliPage() {

Global Options