Skip to main content

​
Overview

The warden sync command updates remote skills to their latest versions. It refreshes the local cache of skills from GitHub repositories.

​
Usage

warden sync [options]

​
How It Works

1

Discover remote skills

Warden scans warden.toml for skills with remote field:
warden.toml
[[skills]]
name = "security-audit"
remote = "getsentry/skills"
2

Check for updates

For unpinned skills (no @sha), Warden fetches the latest version from GitHub.
3

Update local cache

Downloads updated skill definitions to ~/.warden/cache/skills/.
4

Report changes

Shows which skills were updated.

​
Pinned vs Unpinned Skills

​
Unpinned (updates automatically)

warden.toml
[[skills]]
name = "security-audit"
remote = "getsentry/skills"  # No @sha - updates on sync
Running sync fetches the latest version.

​
Pinned (requires manual update)

warden.toml
[[skills]]
name = "security-audit"
remote = "getsentry/skills@abc1234"  # Pinned to SHA
Running sync has no effect. To update:
  1. Remove the @sha part
  2. Run warden sync
  3. Check the new version
  4. Pin to new SHA if desired

​
Examples

​
Sync all remote skills

$ npx warden sync

🔄 Syncing remote skills...

🔍 Found 2 remote skills:
  • security-audit (getsentry/skills)
  • code-quality (getsentry/skills)

✓ security-audit: Updated to abc1234 (was def5678)
✓ code-quality: Up to date (abc1234)

✓ Synced 2 skills

​
No updates available

$ npx warden sync

🔄 Syncing remote skills...

🔍 Found 2 remote skills:
  • security-audit (getsentry/skills@abc1234) [pinned]
  • code-quality (getsentry/skills) [up to date]

✓ All skills up to date

​
Options

​
—force

Force re-download even if up to date: 
npx warden sync --force
Useful if cache is corrupted.

​
—verbose

Show detailed progress: 
npx warden sync --verbose
Output: 
🔄 Syncing remote skills...

🔍 Checking getsentry/skills...
  • Fetching latest commit: abc1234
  • Downloading skills/security-audit/SKILL.md
  • Cache updated: ~/.warden/cache/skills/getsentry-skills-abc1234

✓ security-audit: Updated to abc1234

​
Cache Location

Remote skills are cached in: 
~/.warden/cache/skills/
├── getsentry-skills-abc1234/
│   ├── security-audit/
│   │   └── SKILL.md
│   └── code-quality/
│       └── SKILL.md
Each repository version is cached separately.

​
When to Sync

​
Regular maintenance

Sync weekly to get latest improvements: 
npx warden sync

​
Before important analysis

Sync before analyzing critical changes: 
npx warden sync
npx warden main..feature-branch

​
After skill updates

When skill maintainers release updates: 
npx warden sync --force

​
In CI/CD

Sync in CI to get latest versions:
.github/workflows/warden.yml
- name: Sync skills
  run: npx warden sync

- name: Run Warden
  run: npx warden

​
Comparison with add --force

CommandEffect
warden syncUpdates all unpinned remote skills
warden add <skill> --forceRe-adds one skill (overwrites config)

​
When to use sync

Update skills without changing configuration: 
npx warden sync

​
When to use add —force

Reset skill configuration to defaults: 
npx warden add security-audit --force

​
Managing Skill Versions

​
Check current versions

View remote references in warden.toml: 
grep -A 1 'remote =' warden.toml
Output: 
remote = "getsentry/skills"
--
remote = "getsentry/skills@abc1234"

​
Pin to current version

After syncing, pin to the new version: 
# Sync to get latest
npx warden sync --verbose

# Note the SHA from output: abc1234

# Edit warden.toml
remote = "getsentry/skills@abc1234"

​
Unpin to allow updates

Remove the @sha part:
warden.toml
# Before (pinned)
remote = "getsentry/skills@abc1234"

# After (unpinned)
remote = "getsentry/skills"
Then run sync to update.

​
Troubleshooting

The remote repository may not exist or is private:
✗ Failed to sync getsentry/nonexistent: Repository not found
Solutions:
  1. Verify the repository exists: https://github.com/getsentry/skills
  2. Check for typos in warden.toml
  3. For private repos, set GITHUB_TOKEN environment variable
GitHub API rate limit reached:
✗ Failed to sync: API rate limit exceeded
Solutions:
  1. Wait an hour for rate limit to reset
  2. Set GITHUB_TOKEN for higher rate limits (5,000/hour vs 60/hour)
export GITHUB_TOKEN=ghp_...
npx warden sync
Skills may be pinned:
$ npx warden sync
✓ All skills up to date
Solution: Check for @sha in warden.toml:
grep 'remote =' warden.toml
Remove @sha to allow updates.
If skills behave strangely after sync:
# Clear cache
rm -rf ~/.warden/cache/skills/

# Re-sync
npx warden sync --force

​
Best Practices

​
Development: Unpinned

Use unpinned skills for active development:
warden.toml
[[skills]]
name = "code-quality"
remote = "getsentry/skills"  # Gets latest improvements

​
Production: Pinned

Pin skills in production for stability:
warden.toml
[[skills]]
name = "security-audit"
remote = "getsentry/skills@abc1234"  # Stable, tested version

​
Update workflow

  1. Sync in development: 
    npx warden sync
npx warden  # Test new versions
  2. Pin to tested SHA: 
    remote = "getsentry/skills@abc1234"
  3. Deploy to production
  4. Repeat monthly or quarterly

Add skills

Add new skills to configuration

Remote skills

Complete guide to remote skills

Configuration

Skill configuration options

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us