⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v3.4.0

warden-skill

getsentry@getsentry⭐ 263 stars· last commit 19d ago· 14 open issues

Guide for using Warden CLI locally to analyze code changes. Use when running warden commands, configuring warden.toml, creating custom skills, understanding triggers, or troubleshooting analysis issues. Triggers on "run warden", "warden config", "warden.toml", "create warden skill", "add trigger", or any Warden-related local development task.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 263 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

dotagents

Shared tooling for coding agents. Declare skills, MCP servers, hooks, subagents, and plugins in agents.toml — dotagents wires them into every agent tool on your team.

Why dotagents?

One source of truth. Skills live in .agents/skills/ and symlink into .claude/skills/ or wherever your tools expect them. Cursor shares Claude-compatible skills. No copy-pasting between directories.

One command to install. Global dependencies live under ~/.agents/. Repository-local dependencies can be declared in a committed agents.toml; collaborators run dotagents --project install to fetch or refresh that project's managed state.

Shareable. Skills are directories with a SKILL.md. Host them in any git repo, discover them automatically, install with one command.

Multi-agent. Configure Claude, Cursor, Codex, GitHub Copilot CLI, Grok, VS Code, OpenCode, and Pi from a single agents.toml -- skills, MCP servers, hooks, subagents, and plugins where supported. Pi reads .agents/skills/ directly.

Quick Start: Global by Default

npx @sentry/dotagents init

Without a scope flag, every command operates on global state under ~/.agents/, even when run inside a repository. The interactive setup walks you through selecting agents and trust policy. Then add skills or plugins:

# Add a skill from a GitHub repo
npx @sentry/dotagents add getsentry/skills find-bugs

# Add multiple skills at once
npx @sentry/dotagents add getsentry/skills find-bugs code-review commit

# Or add all skills from a repo
npx @sentry/dotagents add getsentry/skills --all

# Add a plugin (auto-detected from the source)
npx @sentry/dotagents add getsentry/agent-plugins review-tools

This creates ~/.agents/agents.toml and ~/.agents/agents.lock, making the dependencies available across projects.

Run install again whenever you want to refresh global managed state:

npx @sentry/dotagents install

Repository-Local Workflow

Use --project for repository-local state. Inside Git, dotagents uses the repository root; outside Git, --project init uses the current directory.

# Initialize this repository
npx @sentry/dotagents --project init

# Add a dependency only for this repository
npx @sentry/dotagents --project add getsentry/skills find-bugs

# After cloning or pulling a repository with agents.toml
npx @sentry/dotagents --project install

# Check and repair repository-local state
npx @sentry/dotagents --project doctor --fix

Project commands other than init require agents.toml and never fall back to global state. Existing project and global files are not copied, merged, or removed when switching scopes. Project-managed paths must also resolve inside the repository: traversal paths and symlinks that point outside it are rejected, while aliases to another location inside the repository remain supported.

The optional project post-merge hook clears inherited Git repository variables for its install command, keeping cache updates separate from the repository being merged. Run npx @sentry/dotagents --project init to refresh an existing managed hook.

Commands

CommandDescription
initCreate the selected scope's config and managed directories
add <source> [names...]Discover and add plugins, otherwise skills; exact repeats refresh installation
remove <name|source> [-y]Remove a skill, plugin, or all dependencies from a source
installInstall all dependencies from agents.toml
listShow declared skills, plugins, and their status
syncReconcile state offline: adopt local skills, prune stale managed ones, repair configs
mcpManage MCP server declarations
trustManage trusted sources
doctorCheck active-scope health, including plugin runtime projections, and fix supported issues

All commands default to global scope (~/.agents/). --global selects it explicitly, and legacy --user remains a compatibility alias. --project selects repository-local state. Combining --project with either global alias is an error.

Removing a wildcard-provided skill updates the source's exclude array, including multiline arrays, and preserves comments. If saving the exclusion fails, the skill and lock entry stay intact.

trust add and trust remove support inline and multiline arrays and preserve comments. Removing the last trusted source keeps an empty allow-list. If an edit cannot be applied safely, the config stays unchanged and the command fails.

sync repairs changed MCP server settings; matching entries, including Codex configs, stay unchanged.

Source Formats

Skills can come from GitHub, GitLab, any git server, well-known HTTPS skill sources, or local directories. Git and local sources are checked for plugins first. If any plugin is found, add treats the entire source as plugin-only; standalone and bundled skills in that source are not offered. Malformed plugin-shaped content is an error rather than a fallback to skills. Local plugin sources that overlap the project's managed .agents/plugins directory are rejected before configuration changes. Well-known HTTPS sources remain skill-only:

[[skills]]
name = "find-bugs"
source = "getsentry/skills"              # GitHub shorthand

[[skills]]
name = "review"
source = "getsentry/[email protected]"       # Pinned to a ref

[[skills]]
name = "gitlab-skill"
source = "https://gitlab.com/group/repo" # GitLab URL

[[skills]]
name = "internal"
source = "git:https://git.corp.dev/repo" # Any git server

[[skills]]
name = "error-tracking"
source = "https://cli.sentry.dev"        # Well-known HTTPS source

[[skills]]
name = "local"
source = "path:./my-skills/local-skill"  # Local directory

Shorthand (owner/repo) resolves to GitHub by default. Set defaultRepositorySource = "gitlab" in agents.toml to resolve to GitLab instead.

Agent Targets

The agents field tells dotagents which tools to configure:

agents = ["claude", "cursor", "codex", "copilot", "grok", "opencode", "pi"]
AgentConfig DirMCP ConfigHooksSubagents
claude.claude.mcp.json.claude/settings.json.claude/agents/*.md
cursor.cursor.cursor/mcp.json.cursor/hooks.json.cursor/agents/*.md
codex.codex.codex/config.toml--.codex/agents/*.toml
copilot.copilot.mcp.json or .github/mcp.json----
grok.grok------
vscode.vscode.vscode/mcp.json.claude/settings.json--
opencode.opencode.opencode/opencode.jsonc--.opencode/agents/*.md
pi.pi.pi/mcp.json----

Pi 0.99+ supports [[mcp]] declarations over stdio and Streamable HTTP. With pi in agents, dotagents writes .pi/mcp.json for project scope and ~/.pi/agent/mcp.json for global scope, or $PI_CODING_AGENT_DIR/mcp.json when overridden (~ is expanded). Existing unrelated servers and top-level settings are preserved. Pi server names allow only letters, digits, underscores, and hyphens. URLs must be literal; ${VAR} references work in headers and environment values. Pi only reads project MCP config after the project is trusted; use pi mcp list --json to check connections and pi mcp login <server> for OAuth. Plugin-bundled MCP is not projected to Pi yet.

Custom subagents are declared with [[subagents]] entries. dotagents writes generated runtime-specific files during install and repairs them during sync:

[[subagents]]
name = "code-reviewer"
source = "getsentry/agent-pack"
targets = ["claude", "codex", "opencode"]

If targets is omitted or empty, dotagents targets every configured agent and warns for agents that do not support custom subagents.

dotagents discovers portable subagent Markdown from conventional source directories such as agents/ and

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • .agents/skills/warden-skill/SKILL.md5.3 KBupstream ↗
    ---
    name: warden-skill
    description: Guide for using Warden CLI locally to analyze code changes. Use when running warden commands, configuring warden.toml, creating custom skills, understanding triggers, or troubleshooting analysis issues. Triggers on "run warden", "warden config", "warden.toml", "create warden skill", "add trigger", or any Warden-related local development task.
    ---
    
    # Warden Usage
    
    Warden is an event-driven AI agent that analyzes code changes and executes configurable skills to produce structured reports with findings.
    
    ## Quick Start
    
    ```bash
    # Set API key
    export WARDEN_ANTHROPIC_API_KEY=sk-ant-...
    
    # Analyze uncommitted changes (uses warden.toml triggers)
    warden
    
    # Run specific skill on uncommitted changes
    warden --skill find-bugs
    
    # Analyze specific files
    warden src/auth.ts src/database.ts
    
    # Analyze changes from git ref
    warden main..HEAD
    warden HEAD~3
    ```
    
    ## CLI Reference
    
    ```
    warden [command] [targets...] [options]
    ```
    
    **Commands:**
    - `(default)` - Run analysis
    - `init` - Initialize warden.toml and GitHub workflow
    - `add [skill]` - Add skill trigger to warden.toml
    - `sync [repo]` - Update cached remote skills to latest
    - `setup-app` - Create GitHub App via manifest flow
    
    **Targets:**
    - `<files>` - Specific files (e.g., `src/auth.ts`)
    - `<glob>` - Pattern match (e.g., `src/**/*.ts`)
    - `<git-ref>` - Git range (e.g., `main..HEAD`, `HEAD~3`)
    - `(none)` - Uncommitted changes
    
    **Key Options:**
    | Option | Description |
    |--------|-------------|
    | `--skill <name>` | Run only this skill |
    | `--config <path>` | Path to warden.toml (default: ./warden.toml) |
    | `-m, --model <model>` | Model to use |
    | `--json` | Output as JSON |
    | `-o, --output <path>` | Write output to JSONL file |
    | `--fail-on <severity>` | Exit 1 if findings >= severity |
    | `--comment-on <severity>` | Show findings >= severity |
    | `--fix` | Auto-apply suggested fixes |
    | `--parallel <n>` | Concurrent executions (default: 4) |
    | `--offline` | Use cached remote skills only |
    | `-q, --quiet` | Errors and summary only |
    | `-v, --verbose` | Show real-time findings |
    | `-vv` | Debug info (tokens, latency) |
    
    **Severity levels:** `critical`, `high`, `medium`, `low`, `info`, `off`
    
    ## Configuration (warden.toml)
    
    See [references/config-schema.md](references/config-schema.md) for complete schema.
    
    **Minimal example:**
    
    ```toml
    version = 1
    
    [defaults]
    model = "claude-sonnet-4-20250514"
    
    [[triggers]]
    name = "find-bugs"
    event = "pull_request"
    actions = ["opened", "synchronize"]
    skill = "find-bugs"
    
    [triggers.filters]
    paths = ["src/**/*.ts"]
    ```
    
    **With custom output thresholds:**
    
    ```toml
    [[triggers]]
    name = "security-strict"
    event = "pull_request"
    actions = ["opened", "synchronize"]
    skill = "security-review"
    
    [triggers.filters]
    paths = ["src/auth/**", "src/payments/**"]
    
    [triggers.output]
    failOn = "critical"
    commentOn = "high"
    maxFindings = 20
    ```
    
    ## Creating Custom Skills
    
    Skills live in `.warden/skills/`, `.agents/skills/`, or `.claude/skills/`.
    
    **Structure:**
    ```
    .warden/skills/my-skill/
    └── SKILL.md
    ```
    
    **SKILL.md format:**
    
    ```markdown
    ---
    name: my-skill
    description: What this skill analyzes
    allowed-tools: Read Grep Glob
    ---
    
    [Analysis instructions for the agent]
    
    ## What to Look For
    - Specific issue type 1
    - Specific issue type 2
    
    ## Output Format
    Report findings with severity, location, and suggested fix.
    ```
    
    **Available tools:** `Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Bash`, `Write`, `Edit`
    
    ## Remote Skills
    
    Skills can be fetched from GitHub repositories:
    
    ```bash
    # Add a remote skill
    warden add --remote getsentry/skills --skill security-review
    
    # Add with version pinning (recommended for reproducibility)
    warden add --remote getsentry/skills@abc123 --skill security-review
    
    # List skills in a remote repo
    warden add --remote getsentry/skills --list
    
    # Update all unpinned remote skills
    warden sync
    
    # Update specific repo
    warden sync getsentry/skills
    
    # Run with cached skills only (no network)
    warden --offline
    ```
    
    **Remote trigger in warden.toml:**
    
    ```toml
    [[triggers]]
    name = "security-review"
    event = "pull_request"
    actions = ["opened", "synchronize"]
    skill = "security-review"
    remote = "getsentry/skills@abc123"
    ```
    
    **Cache location:** `~/.local/warden/skills/` (override with `WARDEN_STATE_DIR`)
    
    **Cache TTL:** 24 hours for unpinned refs (override with `WARDEN_SKILL_CACHE_TTL` in seconds)
    
    ## Common Patterns
    
    **Strict security on critical files:**
    ```toml
    [[triggers]]
    name = "auth-security"
    event = "pull_request"
    actions = ["opened", "synchronize"]
    skill = "security-review"
    model = "claude-opus-4-20250514"
    maxTurns = 100
    
    [triggers.filters]
    paths = ["src/auth/**", "src/payments/**"]
    
    [triggers.output]
    failOn = "critical"
    ```
    
    **Skip test files:**
    ```toml
    [triggers.filters]
    paths = ["src/**/*.ts"]
    ignorePaths = ["**/*.test.ts", "**/*.spec.ts"]
    ```
    
    **Whole-file analysis for configs:**
    ```toml
    [defaults.chunking.filePatterns]
    pattern = "*.config.*"
    mode = "whole-file"
    ```
    
    ## Troubleshooting
    
    **No findings reported:**
    - Check `--comment-on` threshold (default shows all)
    - Verify skill matches file types in `filters.paths`
    - Use `-v` to see which files are being analyzed
    
    **Files being skipped:**
    - Built-in skip patterns: lock files, minified, `node_modules/`, `dist/`
    - Check `ignorePaths` in config
    - Use `-vv` to see skip reasons
    
    **Token/cost issues:**
    - Reduce `maxTurns` (default: 50)
    - Use chunking settings to control chunk size
    - Filter to relevant files with `paths`
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/getsentry-dotagents-agents-skills-warden-skill.md

// REPO STATS

263 stars
14 open issues
Last commit: 19d ago