{
  "schemaVersion": "1.0",
  "item": {
    "slug": "soul-guardian",
    "name": "soul-guardian",
    "source": "tencent",
    "type": "skill",
    "category": "效率提升",
    "sourceUrl": "https://clawhub.ai/davida-ps/soul-guardian",
    "canonicalUrl": "https://clawhub.ai/davida-ps/soul-guardian",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/soul-guardian",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=soul-guardian",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "scripts/install_launchd_plist.py",
      "scripts/onboard_state_dir.py",
      "scripts/soul_guardian.py",
      "scripts/test_soul_guardian.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/soul-guardian"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/soul-guardian",
    "agentPageUrl": "https://openagent3.xyz/skills/soul-guardian/agent",
    "manifestUrl": "https://openagent3.xyz/skills/soul-guardian/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/soul-guardian/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "soul-guardian 👻",
        "body": "Protects your agent's core files (SOUL.md, AGENTS.md, etc.) from unauthorized changes with automatic detection, restoration, and user alerting."
      },
      {
        "title": "Step 1: Initialize baselines",
        "body": "cd ~/.openclaw/workspace\npython3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note \"initial baseline\""
      },
      {
        "title": "Step 2: Enable monitoring",
        "body": "python3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring\n\nThis shows you how to add monitoring to your workflow."
      },
      {
        "title": "Step 3: Add to HEARTBEAT.md (Recommended)",
        "body": "Add this to your HEARTBEAT.md for automatic monitoring:\n\n## Soul Guardian Check\n- Run `python3 skills/soul-guardian/scripts/soul_guardian.py check --actor heartbeat --output-format alert`\n- If any output is produced, relay it to the user immediately as a security alert\n\nThat's it! Soul Guardian will now:\n\n✅ Detect unauthorized changes to protected files\n✅ Auto-restore SOUL.md and AGENTS.md to approved baseline\n✅ Alert you when drift is detected and handled"
      },
      {
        "title": "What it protects (default policy)",
        "body": "FileModeAction on driftSOUL.mdrestoreAuto-restore + alertAGENTS.mdrestoreAuto-restore + alertUSER.mdalertAlert onlyTOOLS.mdalertAlert onlyIDENTITY.mdalertAlert onlyHEARTBEAT.mdalertAlert onlyMEMORY.mdalertAlert onlymemory/*.mdignoreIgnored"
      },
      {
        "title": "Check for drift (with alert output)",
        "body": "python3 skills/soul-guardian/scripts/soul_guardian.py check --output-format alert\n\nSilent if no drift\nOutputs human-readable alert if drift detected\nPerfect for heartbeat integration"
      },
      {
        "title": "Watch mode (continuous monitoring)",
        "body": "python3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30\n\nRuns continuously, checking every 30 seconds."
      },
      {
        "title": "Approve intentional changes",
        "body": "python3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md --actor user --note \"intentional update\""
      },
      {
        "title": "View status",
        "body": "python3 skills/soul-guardian/scripts/soul_guardian.py status"
      },
      {
        "title": "Verify audit log integrity",
        "body": "python3 skills/soul-guardian/scripts/soul_guardian.py verify-audit"
      },
      {
        "title": "Alert Format",
        "body": "When drift is detected, the --output-format alert produces output like:\n\n==================================================\n🚨 SOUL GUARDIAN SECURITY ALERT\n==================================================\n\n📄 FILE: SOUL.md\n   Mode: restore\n   Status: ✅ RESTORED to approved baseline\n   Expected hash: abc123def456...\n   Found hash:    789xyz000111...\n   Diff saved: /path/to/patches/drift.patch\n\n==================================================\nReview changes and investigate the source of drift.\nIf intentional, run: soul_guardian.py approve --file <path>\n==================================================\n\nThis output is designed to be relayed directly to the user in TUI/chat."
      },
      {
        "title": "Security Model",
        "body": "What it does:\n\nDetects filesystem drift vs approved baseline (sha256)\nProduces unified diffs for review\nMaintains tamper-evident audit log with hash chaining\nRefuses to operate on symlinks\nUses atomic writes for restores\n\nWhat it doesn't do:\n\nCannot prove WHO made a change (actor is best-effort metadata)\nCannot protect if attacker controls both workspace AND state directory\nIs not a substitute for backups\n\nRecommendation: Store state directory outside workspace for better resilience."
      },
      {
        "title": "Demo",
        "body": "Run the full demo flow to see soul-guardian in action:\n\nbash skills/soul-guardian/scripts/demo.sh\n\nThis will:\n\nVerify clean state (silent check)\nInject malicious content into SOUL.md\nRun heartbeat check (produces alert)\nShow SOUL.md was restored"
      },
      {
        "title": "Troubleshooting",
        "body": "\"Not initialized\" error:\nRun init first to set up baselines.\n\nDrift keeps happening:\nCheck what's modifying your files. Review the audit log and patches.\n\nWant to approve a change:\nRun approve --file <path> after reviewing the change."
      }
    ],
    "body": "soul-guardian 👻\n\nProtects your agent's core files (SOUL.md, AGENTS.md, etc.) from unauthorized changes with automatic detection, restoration, and user alerting.\n\nQuick Start (3 Steps)\nStep 1: Initialize baselines\ncd ~/.openclaw/workspace\npython3 skills/soul-guardian/scripts/soul_guardian.py init --actor setup --note \"initial baseline\"\n\nStep 2: Enable monitoring\npython3 skills/soul-guardian/scripts/soul_guardian.py enable-monitoring\n\n\nThis shows you how to add monitoring to your workflow.\n\nStep 3: Add to HEARTBEAT.md (Recommended)\n\nAdd this to your HEARTBEAT.md for automatic monitoring:\n\n## Soul Guardian Check\n- Run `python3 skills/soul-guardian/scripts/soul_guardian.py check --actor heartbeat --output-format alert`\n- If any output is produced, relay it to the user immediately as a security alert\n\n\nThat's it! Soul Guardian will now:\n\n✅ Detect unauthorized changes to protected files\n✅ Auto-restore SOUL.md and AGENTS.md to approved baseline\n✅ Alert you when drift is detected and handled\nWhat it protects (default policy)\nFile\tMode\tAction on drift\nSOUL.md\trestore\tAuto-restore + alert\nAGENTS.md\trestore\tAuto-restore + alert\nUSER.md\talert\tAlert only\nTOOLS.md\talert\tAlert only\nIDENTITY.md\talert\tAlert only\nHEARTBEAT.md\talert\tAlert only\nMEMORY.md\talert\tAlert only\nmemory/*.md\tignore\tIgnored\nCommands\nCheck for drift (with alert output)\npython3 skills/soul-guardian/scripts/soul_guardian.py check --output-format alert\n\nSilent if no drift\nOutputs human-readable alert if drift detected\nPerfect for heartbeat integration\nWatch mode (continuous monitoring)\npython3 skills/soul-guardian/scripts/soul_guardian.py watch --interval 30\n\n\nRuns continuously, checking every 30 seconds.\n\nApprove intentional changes\npython3 skills/soul-guardian/scripts/soul_guardian.py approve --file SOUL.md --actor user --note \"intentional update\"\n\nView status\npython3 skills/soul-guardian/scripts/soul_guardian.py status\n\nVerify audit log integrity\npython3 skills/soul-guardian/scripts/soul_guardian.py verify-audit\n\nAlert Format\n\nWhen drift is detected, the --output-format alert produces output like:\n\n==================================================\n🚨 SOUL GUARDIAN SECURITY ALERT\n==================================================\n\n📄 FILE: SOUL.md\n   Mode: restore\n   Status: ✅ RESTORED to approved baseline\n   Expected hash: abc123def456...\n   Found hash:    789xyz000111...\n   Diff saved: /path/to/patches/drift.patch\n\n==================================================\nReview changes and investigate the source of drift.\nIf intentional, run: soul_guardian.py approve --file <path>\n==================================================\n\n\nThis output is designed to be relayed directly to the user in TUI/chat.\n\nSecurity Model\n\nWhat it does:\n\nDetects filesystem drift vs approved baseline (sha256)\nProduces unified diffs for review\nMaintains tamper-evident audit log with hash chaining\nRefuses to operate on symlinks\nUses atomic writes for restores\n\nWhat it doesn't do:\n\nCannot prove WHO made a change (actor is best-effort metadata)\nCannot protect if attacker controls both workspace AND state directory\nIs not a substitute for backups\n\nRecommendation: Store state directory outside workspace for better resilience.\n\nDemo\n\nRun the full demo flow to see soul-guardian in action:\n\nbash skills/soul-guardian/scripts/demo.sh\n\n\nThis will:\n\nVerify clean state (silent check)\nInject malicious content into SOUL.md\nRun heartbeat check (produces alert)\nShow SOUL.md was restored\nTroubleshooting\n\n\"Not initialized\" error: Run init first to set up baselines.\n\nDrift keeps happening: Check what's modifying your files. Review the audit log and patches.\n\nWant to approve a change: Run approve --file <path> after reviewing the change."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/davida-ps/soul-guardian",
    "publisherUrl": "https://clawhub.ai/davida-ps/soul-guardian",
    "owner": "davida-ps",
    "version": "0.0.2",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/soul-guardian",
    "downloadUrl": "https://openagent3.xyz/downloads/soul-guardian",
    "agentUrl": "https://openagent3.xyz/skills/soul-guardian/agent",
    "manifestUrl": "https://openagent3.xyz/skills/soul-guardian/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/soul-guardian/agent.md"
  }
}