Skip to content

Commit e8bf13a

Browse files
grichagricha
committed
Add warden skill
1 parent 53b80ba commit e8bf13a

File tree

3 files changed

+384
-0
lines changed

3 files changed

+384
-0
lines changed

‎.agents/skills/warden-skill/SKILL.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
---
2+
name: warden-skill
3+
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.
4+
---
5+
6+
# Warden Usage
7+
8+
Warden is an event-driven AI agent that analyzes code changes and executes configurable skills to produce structured reports with findings.
9+
10+
## Quick Start
11+
12+
```bash
13+
# Set API key
14+
export WARDEN_ANTHROPIC_API_KEY=sk-ant-...
15+
16+
# Analyze uncommitted changes (uses warden.toml triggers)
17+
warden
18+
19+
# Run specific skill on uncommitted changes
20+
warden --skill find-bugs
21+
22+
# Analyze specific files
23+
warden src/auth.ts src/database.ts
24+
25+
# Analyze changes from git ref
26+
warden main..HEAD
27+
warden HEAD~3
28+
```
29+
30+
## CLI Reference
31+
32+
```
33+
warden [command] [targets...] [options]
34+
```
35+
36+
**Commands:**
37+
- `(default)` - Run analysis
38+
- `init` - Initialize warden.toml and GitHub workflow
39+
- `add [skill]` - Add skill trigger to warden.toml
40+
- `sync [repo]` - Update cached remote skills to latest
41+
- `setup-app` - Create GitHub App via manifest flow
42+
43+
**Targets:**
44+
- `<files>` - Specific files (e.g., `src/auth.ts`)
45+
- `<glob>` - Pattern match (e.g., `src/**/*.ts`)
46+
- `<git-ref>` - Git range (e.g., `main..HEAD`, `HEAD~3`)
47+
- `(none)` - Uncommitted changes
48+
49+
**Key Options:**
50+
| Option | Description |
51+
|--------|-------------|
52+
| `--skill <name>` | Run only this skill |
53+
| `--config <path>` | Path to warden.toml (default: ./warden.toml) |
54+
| `-m, --model <model>` | Model to use |
55+
| `--json` | Output as JSON |
56+
| `-o, --output <path>` | Write output to JSONL file |
57+
| `--fail-on <severity>` | Exit 1 if findings >= severity |
58+
| `--comment-on <severity>` | Show findings >= severity |
59+
| `--fix` | Auto-apply suggested fixes |
60+
| `--parallel <n>` | Concurrent executions (default: 4) |
61+
| `--offline` | Use cached remote skills only |
62+
| `-q, --quiet` | Errors and summary only |
63+
| `-v, --verbose` | Show real-time findings |
64+
| `-vv` | Debug info (tokens, latency) |
65+
66+
**Severity levels:** `critical`, `high`, `medium`, `low`, `info`, `off`
67+
68+
## Configuration (warden.toml)
69+
70+
See [references/config-schema.md](references/config-schema.md) for complete schema.
71+
72+
**Minimal example:**
73+
74+
```toml
75+
version = 1
76+
77+
[defaults]
78+
model = "claude-sonnet-4-20250514"
79+
80+
[[triggers]]
81+
name = "find-bugs"
82+
event = "pull_request"
83+
actions = ["opened", "synchronize"]
84+
skill = "find-bugs"
85+
86+
[triggers.filters]
87+
paths = ["src/**/*.ts"]
88+
```
89+
90+
**With custom output thresholds:**
91+
92+
```toml
93+
[[triggers]]
94+
name = "security-strict"
95+
event = "pull_request"
96+
actions = ["opened", "synchronize"]
97+
skill = "security-review"
98+
99+
[triggers.filters]
100+
paths = ["src/auth/**", "src/payments/**"]
101+
102+
[triggers.output]
103+
failOn = "critical"
104+
commentOn = "high"
105+
maxFindings = 20
106+
```
107+
108+
## Creating Custom Skills
109+
110+
Skills live in `.warden/skills/`, `.agents/skills/`, or `.claude/skills/`.
111+
112+
**Structure:**
113+
```
114+
.warden/skills/my-skill/
115+
└── SKILL.md
116+
```
117+
118+
**SKILL.md format:**
119+
120+
```markdown
121+
---
122+
name: my-skill
123+
description: What this skill analyzes
124+
allowed-tools: Read Grep Glob
125+
---
126+
127+
[Analysis instructions for the agent]
128+
129+
## What to Look For
130+
- Specific issue type 1
131+
- Specific issue type 2
132+
133+
## Output Format
134+
Report findings with severity, location, and suggested fix.
135+
```
136+
137+
**Available tools:** `Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Bash`, `Write`, `Edit`
138+
139+
## Remote Skills
140+
141+
Skills can be fetched from GitHub repositories:
142+
143+
```bash
144+
# Add a remote skill
145+
warden add --repo getsentry/skills --skill security-review
146+
147+
# Add with version pinning (recommended for reproducibility)
148+
warden add --repo getsentry/skills@abc123 --skill security-review
149+
150+
# List skills in a remote repo
151+
warden add --repo getsentry/skills --list
152+
153+
# Update all unpinned remote skills
154+
warden sync
155+
156+
# Update specific repo
157+
warden sync getsentry/skills
158+
159+
# Run with cached skills only (no network)
160+
warden --offline
161+
```
162+
163+
**Remote trigger in warden.toml:**
164+
165+
```toml
166+
[[triggers]]
167+
name = "security-review"
168+
event = "pull_request"
169+
actions = ["opened", "synchronize"]
170+
skill = "security-review"
171+
remote = "getsentry/skills@abc123"
172+
```
173+
174+
**Cache location:** `~/.local/warden/skills/` (override with `WARDEN_STATE_DIR`)
175+
176+
**Cache TTL:** 24 hours for unpinned refs (override with `WARDEN_SKILL_CACHE_TTL` in seconds)
177+
178+
**Inline skill in warden.toml:**
179+
180+
```toml
181+
[[skills]]
182+
name = "custom-check"
183+
description = "Check for TODO comments"
184+
prompt = """
185+
Find TODO comments that have been in the code for too long.
186+
Report as low severity findings.
187+
"""
188+
189+
[skills.tools]
190+
allowed = ["Read", "Grep", "Glob"]
191+
```
192+
193+
## Built-in Skills
194+
195+
| Skill | Purpose |
196+
|-------|---------|
197+
| `find-bugs` | Logical/functional bugs, null handling, async issues |
198+
| `security-review` | Injection, auth, CSRF, crypto, race conditions |
199+
| `code-simplifier` | Readability, consistency, redundancy removal |
200+
| `performance-review` | N+1 queries, blocking I/O, memory leaks |
201+
202+
## Common Patterns
203+
204+
**Strict security on critical files:**
205+
```toml
206+
[[triggers]]
207+
name = "auth-security"
208+
event = "pull_request"
209+
actions = ["opened", "synchronize"]
210+
skill = "security-review"
211+
model = "claude-opus-4-20250514"
212+
maxTurns = 100
213+
214+
[triggers.filters]
215+
paths = ["src/auth/**", "src/payments/**"]
216+
217+
[triggers.output]
218+
failOn = "critical"
219+
```
220+
221+
**Skip test files:**
222+
```toml
223+
[triggers.filters]
224+
paths = ["src/**/*.ts"]
225+
ignorePaths = ["**/*.test.ts", "**/*.spec.ts"]
226+
```
227+
228+
**Whole-file analysis for configs:**
229+
```toml
230+
[defaults.chunking.filePatterns]
231+
pattern = "*.config.*"
232+
mode = "whole-file"
233+
```
234+
235+
## Troubleshooting
236+
237+
**No findings reported:**
238+
- Check `--comment-on` threshold (default shows all)
239+
- Verify skill matches file types in `filters.paths`
240+
- Use `-v` to see which files are being analyzed
241+
242+
**Files being skipped:**
243+
- Built-in skip patterns: lock files, minified, `node_modules/`, `dist/`
244+
- Check `ignorePaths` in config
245+
- Use `-vv` to see skip reasons
246+
247+
**Token/cost issues:**
248+
- Reduce `maxTurns` (default: 50)
249+
- Use chunking settings to control chunk size
250+
- Filter to relevant files with `paths`

‎.agents/skills/warden-skill/references/config-schema.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# warden.toml Configuration Schema
2+
3+
## Top-Level Structure
4+
5+
```toml
6+
version = 1 # Required, must be 1
7+
8+
[defaults] # Optional, inherited by all triggers
9+
[[triggers]] # Required, array of trigger configs
10+
[[skills]] # Optional, inline skill definitions
11+
```
12+
13+
## Defaults Section
14+
15+
```toml
16+
[defaults]
17+
model = "claude-sonnet-4-20250514" # Default model
18+
maxTurns = 50 # Max agentic turns per hunk
19+
defaultBranch = "main" # Base branch for comparisons
20+
21+
[defaults.output]
22+
failOn = "high" # Exit 1 if findings >= this severity
23+
commentOn = "medium" # Show findings >= this severity
24+
maxFindings = 50 # Max findings to report (0 = unlimited)
25+
commentOnSuccess = false # Post comment even with no findings
26+
27+
[defaults.filters]
28+
paths = ["src/**/*.ts"] # Include only matching files
29+
ignorePaths = ["*.test.ts"] # Exclude matching files
30+
31+
[defaults.chunking]
32+
enabled = true # Enable hunk-based chunking
33+
34+
[defaults.chunking.coalesce]
35+
enabled = true # Merge nearby hunks
36+
maxGapLines = 30 # Lines between hunks to merge
37+
maxChunkSize = 8000 # Max chars per chunk
38+
39+
[[defaults.chunking.filePatterns]]
40+
pattern = "*.config.*" # Glob pattern
41+
mode = "whole-file" # per-hunk | whole-file | skip
42+
```
43+
44+
## Triggers Section
45+
46+
```toml
47+
[[triggers]]
48+
name = "trigger-name" # Required, unique identifier
49+
event = "pull_request" # Required: pull_request | issues | issue_comment | schedule
50+
actions = ["opened", "synchronize"] # Required for non-schedule events
51+
skill = "find-bugs" # Required, skill name or path
52+
remote = "owner/repo@sha" # Optional, fetch skill from GitHub repo
53+
54+
# Optional overrides (inherit from defaults if not set)
55+
model = "claude-opus-4-20250514"
56+
maxTurns = 100
57+
58+
[triggers.filters]
59+
paths = ["src/**"]
60+
ignorePaths = ["**/*.test.ts"]
61+
62+
[triggers.output]
63+
failOn = "critical"
64+
commentOn = "high"
65+
maxFindings = 20
66+
commentOnSuccess = true
67+
68+
# Schedule-specific (only for event = "schedule")
69+
[triggers.schedule]
70+
issueTitle = "Daily Security Review" # GitHub issue title for tracking
71+
createFixPR = true # Create PR with fixes
72+
fixBranchPrefix = "security-fix" # Branch name prefix
73+
```
74+
75+
**Event types:**
76+
- `pull_request` - Triggers on PR events
77+
- `issues` - Triggers on issue events
78+
- `issue_comment` - Triggers on issue/PR comments
79+
- `schedule` - Triggers on cron schedule (GitHub Action)
80+
81+
**Actions (for non-schedule):**
82+
- `opened`, `synchronize`, `reopened`, `closed`
83+
84+
## Skills Section (Inline Skills)
85+
86+
```toml
87+
[[skills]]
88+
name = "custom-skill"
89+
description = "What this skill checks"
90+
prompt = """
91+
Analysis instructions here.
92+
Look for specific issues.
93+
"""
94+
95+
[skills.tools]
96+
allowed = ["Read", "Grep", "Glob"] # Whitelist tools
97+
denied = ["Write", "Edit", "Bash"] # Blacklist tools (optional)
98+
```
99+
100+
## Severity Values
101+
102+
Used in `failOn` and `commentOn`:
103+
- `critical` - Most severe
104+
- `high`
105+
- `medium`
106+
- `low`
107+
- `info` - Least severe
108+
- `off` - Disable threshold
109+
110+
## Built-in Skip Patterns
111+
112+
Always skipped (cannot be overridden):
113+
- Package locks: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `Cargo.lock`, etc.
114+
- Minified files: `**/*.min.js`, `**/*.min.css`
115+
- Build artifacts: `dist/`, `build/`, `node_modules/`, `.next/`, `__pycache__/`
116+
- Generated code: `*.generated.*`, `*.g.ts`, `__generated__/`
117+
118+
## Environment Variables
119+
120+
| Variable | Purpose |
121+
|----------|---------|
122+
| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required) |
123+
| `WARDEN_MODEL` | Default model (lowest priority) |
124+
| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |
125+
| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |
126+
127+
## Model Precedence (highest to lowest)
128+
129+
1. Trigger-level `model`
130+
2. `[defaults]` `model`
131+
3. CLI `--model` flag
132+
4. `WARDEN_MODEL` env var
133+
5. SDK default

‎.claude/skills/warden-skill‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../.agents/skills/warden-skill

0 commit comments

Comments
 (0)