# soul-guardian

The soul-guardian skill watches agent workspace files against an approved baseline, restores selected files, and raises alerts when drift appears.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 258 installs · ★ 1135 repo stars
- Author: prompt-security
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/prompt-security/clawsec/tree/HEAD/skills/soul-guardian/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/soul-guardian

## What it does

soul-guardian checks agent workspace files against an approved SHA-256 baseline. Changes to `SOUL.md` and `AGENTS.md` can trigger restoration, while `USER.md`, `TOOLS.md`, `IDENTITY.md`, `HEARTBEAT.md`, and `MEMORY.md` produce alerts. Files under `memory/*.md` are ignored by the default policy.

The package includes `skills/soul-guardian/scripts/soul_guardian.py`. Its commands initialize a baseline, check for drift, keep watching at an interval, approve intentional edits, show status, and validate the audit log. Drift checks can save unified diffs and local audit or quarantine state. The skill rejects symlinks and uses atomic writes when restoring files.

\`python3` is required for the skill to run. Restore mode deliberately overwrites drifted files, so review the baseline before enabling monitoring.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add prompt-security/clawsec --skill soul-guardian -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/soul-guardian/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/soul-guardian/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add prompt-security/clawsec --skill soul-guardian -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/soul-guardian/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add prompt-security/clawsec --skill soul-guardian -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/soul-guardian/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install prompt-security/clawsec skills/soul-guardian
```

2. **Manually: put the files in place**
- File: `.github/skills/soul-guardian/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add prompt-security/clawsec --skill soul-guardian -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/prompt-security/clawsec --path skills/soul-guardian
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/soul-guardian/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add prompt-security/clawsec --skill soul-guardian -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/prompt-security/clawsec/tree/HEAD/skills/soul-guardian/SKILL.md

## When to use it
- detect changes in agent workspace files
- restore `SOUL.md` and `AGENTS.md` from a baseline
- send drift alerts through a heartbeat workflow
- approve an intentional file update
- verify the audit log

## Example prompts
- Initialize the approved baseline with `python3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note "initial baseline"`.
- Check the workspace and emit an alert with `python3 skills/soul-guardian/scripts/soul_guardian.py check --output-format alert`.
- Keep checking the files with `python3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30`.

## Similar
- [fullstack-guardian](https://affpapa.org/en/nevibecode/skills/fullstack-guardian.md) — skill · 6100 installs
- [kodeblue-self-integrity](https://affpapa.org/en/nevibecode/skills/kodeblue-self-integrity.md) — skill · ★ 71 repo stars
- [commit-guardian](https://affpapa.org/en/nevibecode/agents/commit-guardian.md) — subagent · 208 installs
- [code-guardian](https://affpapa.org/en/nevibecode/plugins/code-guardian.md) — plugin · ★ 2858 repo stars
- [skill-provenance](https://affpapa.org/en/nevibecode/plugins/skill-provenance.md) — plugin · ★ 8 repo stars
- [busabase](https://affpapa.org/en/nevibecode/mcp/busabase.md) — MCP server · ★ 3 repo stars

From the same set: [prompt-security/clawsec](https://affpapa.org/en/nevibecode/by/prompt-security/clawsec.md) — 9 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
