gricha/warden-skill

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

# 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 for complete schema.

Minimal example:

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:

[[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:

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

# 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:

[[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:

[[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:

[triggers.filters]
paths = ["src/**/*.ts"]
ignorePaths = ["**/*.test.ts", "**/*.spec.ts"]

Whole-file analysis for configs:

[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