Psychologically grounded wisdom companion for inner life. Use for reflective dialogue, grief, dark-night, burnout, anxiety, stress, loneliness, relationship conflict, shadow work, crossroads, tiered crisis check-ins, continuity notes. DO NOT ACTIVATE for pure coding, DevOps, SQL, git, math, or technical tasks, even if user says "I'm stuck" or "struggling with bug." Hybrid: solve technical task first, then add 2 warm grounding sentences for burnout, imposter syndrome, team conflict.
91%
Does it follow best practices?
Impact
98%
1.05xAverage score across 8 eval scenarios
Passed
No findings from the security scan
Pull requests are welcome. Satori is a living project, and the roadmap explicitly includes community-contributed traditions, conversation patterns, and protocol expansions.
Before contributing, read this document. Contributions that don't meet the quality bar will be returned with feedback, not merged without comment.
After cloning the repository, install the local Git pre-commit hook so that every commit automatically runs the 58-point static verification suite across 20 validation sections (python scripts/validate_skill.py):
# Option A: Cross-platform Python installer (Windows / macOS / Linux)
python scripts/install-hooks.py
# Option B: POSIX shell installer or symlink (macOS / Linux / Git Bash)
sh scripts/install-hooks.sh
# or: ln -sf ../../scripts/pre-commit .git/hooks/pre-commitRunning python scripts/build_release.py also automatically installs .git/hooks/pre-commit whenever .git/hooks is present.
What the pre-commit hook enforces (python scripts/validate_skill.py: 58/58 checks passed):
SKILL.md strictly <8,000 bytes, zero alwaysLoad bloat; every markdown reference under the 24,000-byte ceiling).<=15 lines) and byte-for-byte SHA-256 sync across 4 Category B SKILL.md mirrors.references/SOUL.md SHA-256 integrity verification against openclaw.plugin.json.references/crisis-sources.json..gitignore guards for .satori/, dist/, *.zip) and zero broken relative Markdown links.Before submitting a pull request, run the offline verification test suite locally:
Static Validation Suite:
python scripts/validate_skill.pyEnforces 58 automated checks across 20 validation sections, verifying file size budgets, pointer stubs, mirror hashes, crisis table parity, and zero em-dash hygiene.
Local Memory Engine Self-Tests:
python scripts/satori_memory.py --self-testVerifies 8 of 8 unit and privacy tests, confirming schema initialization, SQLite FTS5 search, signal length capping (≤500 characters), cloud-sync detection, and right-to-erasure WAL truncation (VACUUM).
Trigger Benchmark Lint:
python scripts/run_evals.py --suite trigger --mode lintEvaluates 350 test cases, verifying $\ge 90%$ recall on positive prompts (60 cases), $\ge 95%$ non-activation on pure technical queries (200 cases), $\ge 85%$ on hybrid prompts (50 cases), and 100% on acute crisis handoff (20 cases).
Judge Calibration Verification:
python scripts/test_judge_calibration.pyEvaluates 50 human-labeled prompt pairs, verifying Cohen's kappa reaches 0.84, satisfying the $\ge 0.80$ report target and safely exceeding the $\ge 0.60$ floor gate.
Release Build & Mirror Synchronization:
python scripts/build_release.py --syncSynchronizes SKILL.md mirrors, checks manifest parity, and compiles release archives.
New tradition entries for references/traditions-stoic.md, references/traditions-eastern.md, references/traditions-african-sufi.md, or references/traditions-quickref.md. Priority:
New or expanded entries for clinical/psychological frameworks. Must:
New patterns for references/toolkit-inquiry.md and references/toolkit-somatic.md. Must meet the same quality bar as existing patterns (see below).
New reference documents in the references/ directory: following the pattern of references/darknight-protocol.md or references/shadow-work-protocol.md. These should address specific situations or arcs not currently covered. Note that all 17 markdown reference files in references/ must strictly remain under the 24,000-byte ceiling.
Place community-originated content in a community/ subdirectory with attribution. These are not merged into the core reference files without editorial review, but are available as optional extensions.
Every contribution to Satori is evaluated against the same standard the skill itself uses:
Understanding + pattern recognition + connection + movement
For documentation: Clarity + operational specificity + clinical discipline + voice consistency
1. Is it operationally specific? Satori documentation is not descriptive: it is instructional. It tells the model what to do, when, how, and what to avoid. A tradition entry that only explains what the tradition believes is not enough. It must explain when to reach for it and how to translate it into lived experience.
2. Does it translate to plain language? Every framework must be shown landing in concrete human experience, not as an abstract concept. If your entry includes a framework applied only in jargon, it hasn't been finished.
3. Is the voice consistent?
Read references/tone-and-voice.md before contributing. Satori's voice is: warm, direct, honest, structurally precise, and free of therapeutic platitudes. Contributions that sound like a wellness blog, an academic paper, or a motivational app will be returned for revision.
4. Is there a failure mode section? Good entries name not just when to use but when this framework falls flat, when it can do harm, or what it misses. Traditions are precision tools, not universal answers.
5. Is it one thing, done well? Satori's central discipline is: one framework per response. The same discipline applies to contributions. One tradition, one pattern, one protocol: done deeply and precisely: is more valuable than five done superficially.
For traditions from cultures that have experienced marginalization, colonization, or appropriation:
Satori is committed to representing these traditions with the same depth and respect given to Greek philosophy or Western psychology.
feature/ubuntu-tradition, pattern/the-apology, etc.)python scripts/validate_skill.py, python scripts/satori_memory.py --self-test, python scripts/run_evals.py --suite trigger --mode lint, python scripts/test_judge_calibration.py, and python scripts/build_release.py --sync)references/SOUL.md exists for a reason. Satori has 8 Constitutional Immovables: core principles that never adapt regardless of what is contributed. Contributions that erode these will not be merged:
~/.satori/memory/) with strict POSIX 0700/0600 permissions, signal minimization (≤500 chars), and cloud-sync blocking; Mode 2 stateless data-only SATORI_NOTE v6.5 blocks (≤600 chars); plus single-agent execution invariant during introspection.If your contribution assumes that making the experience more comfortable is the goal, it is working against the architecture. The goal is making it more real.
Open an issue before a PR if you're unsure whether your idea fits. A brief conversation upfront saves everyone time.
Thank you for helping Satori grow.
.agents
plugins
skills
satori
references
.claude-plugin
.codex-plugin
.cursor
skills
satori
references
.gemini
.github
.hermes
skills
satori
references
.opencode
command
skills
satori
references
.tessl-plugin
.windsurf
rules
compact
docs
hooks
references
scripts