soul-guardian — Claude Code skill: file protection and setup
The soul-guardian skill watches agent workspace files against an approved baseline, restores selected files, and raises alerts when drift appears.
AGPL-3.0 258 installs ★ 1,135 updated 2026-10-25
npx skills add prompt-security/clawsec --skill soul-guardian -a claude-codeWhat soul-guardian 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.
What it helps with
- detect changes in agent workspace files
- restore
SOUL.mdandAGENTS.mdfrom a baseline - send drift alerts through a heartbeat workflow
- approve an intentional file update
- verify the audit log
Example prompts for the agent
- 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.
How to install soul-guardian
1Skills CLI (Vercel)
npx skills add prompt-security/clawsec --skill soul-guardian -a claude-code2Manually: put the files in place
~/.claude/skills/soul-guardian/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/soul-guardian/
1Skills CLI (Vercel)
npx skills add prompt-security/clawsec --skill soul-guardian -a codex2Manually: put the files in place
.agents/skills/soul-guardian/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add prompt-security/clawsec --skill soul-guardian -a cursor2Manually: put the files in place
.cursor/skills/soul-guardian/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install prompt-security/clawsec skills/soul-guardian2Manually: put the files in place
.github/skills/soul-guardian/SKILL.md1Skills CLI (Vercel)
npx skills add prompt-security/clawsec --skill soul-guardian -a gemini-cli2Platform CLI
gemini skills install https://github.com/prompt-security/clawsec --path skills/soul-guardianManually: put the files in place
.devin/skills/soul-guardian/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add prompt-security/clawsec --skill soul-guardian -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about soul-guardian
How do I install soul-guardian in Claude Code?
Run npx skills add prompt-security/clawsec --skill soul-guardian -a claude-code. The skill file is placed at ~/.claude/skills/soul-guardian/SKILL.md.
What does soul-guardian do?
It compares workspace files with an approved baseline, reports drift, and restores protected files when configured to do so. Checks also preserve audit information for review.
What does soul-guardian require?
It requires python3. Optional scheduling integrations use openclaw for cron workflows or launchctl on macOS.