soul-awakening
Skill12 starsChanged 7 days agoMITView on GitHub
Re-anchor an AI agent to its SOUL.md persona by re-internalizing tone, rules, and identity. Use when the agent drifts into generic/corporate responses, is explicitly asked to reconnect with its soul, or needs to bootstrap a missing SOUL.md. SOUL content is already injected into the system prompt as ## Persona Template — do not re-read existing soul files.
In this repository51 other files it gives its agents.
- agents.mdAGENTS.md
- .agents/skills/react-best-practices/AGENTS.mdAGENTS.md
- .agents/skills/react-native-skills/AGENTS.mdAGENTS.md
- .agents/skills/react-view-transitions/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- agent-initSkill
- agy-delegateSkill
- audit-docsSkill
- code-audit-expertSkill
- computer-diagnosisSkill
- create-builtin-toolSkill
- create-prSkill
- critique-builtin-toolSkill
- doc-auditorSkill
- docxSkill
- extract-log-debugSkill
- feature-refactor-proposalSkill
- gatekeeper-loopSkill
- harbor-harness-improvement-loopSkill
- harness-eval-loopSkill
- i18n-language-standardsSkill
- jobs-trace-analyzerSkill
- lean-builtin-tool-auditorSkill
- libragent-qualitySkill
- libr-delegateSkill
- libr-tool-e2e-harness-loopSkill
- modular-large-file-refactorSkill
- performance-auditSkill
- pptxSkill
- producer-loopSkill
- vercel-react-best-practicesSkill
- vercel-react-native-skillsSkill
- vercel-react-view-transitionsSkill
- readme-showcase-syncSkill
- refactor-builtin-toolSkill
- release-head-self-e2eSkill
- release-managerSkill
- review-local-changesSkill
- review-pr-commentsSkill
- science-searchSkill
- setup-wizardSkill
- skill-creatorSkill
- sqlite-analyzerSkill
- sync-pending-approvalsSkill
- tool-creatorSkill
- trace-analyzerSkill
- trace-eval-loopSkill
- vitepress-doc-syncSkill
- worker-loopSkill
- x-cliSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 13 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Use this skill to deliberately reconnect with the agent's persona layer.
- Very specific: line 17
Do not: run find_soul.py or re-read an existing soul file—that duplicates content already in context.
- Distinctive: line 21
Check whether a soul is already active.
- Distinctive: line 22
Look for ## Persona Template in the system prompt.
- Distinctive: line 23
If present, skip all file I/O.
- Distinctive: line 25
If no Persona Template section exists, bootstrap one.
- Distinctive: line 26
Do not use planning tools—this is a short persona task, not a project plan.
- Very specific: line 27
Read references/base_soul.md and adapt it to the agent's actual voice and role.
- Distinctive: line 28
Keep it concise, sharp, and usable.
- Distinctive: line 33
Treat it as persona guidance: tone, style, values, and behavioral posture.
- Distinctive: line 43
Do not search random parent directories.
- Distinctive: line 44
Do not summarize the soul file unless the user asks.
- Distinctive: line 45
Do not quote large chunks of it unless the user wants the text itself.
- Distinctive: line 46
Do not confuse soul/persona guidance with task-specific instructions.
- Distinctive: line 47
Do not leave the user with "no soul found" if you can create a sensible one from the base template.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Soul Awakening
Use this skill to deliberately reconnect with the agent's persona layer. This is about voice, stance, and identity—not workspace task instructions like agents.md or CLAUDE.md.
Runtime context (read first)
The Rust prompt loader already:
- Searches workspace candidates in order:
.github/SOUL.md→SOUL.md→.github/soul.md→soul.md - Injects the first match into the system prompt as ## Persona Template
Do not run find_soul.py or re-read an existing soul file—that duplicates content already in context.
Awakening Workflow
- Check whether a soul is already active.
- Look for ## Persona Template in the system prompt.
- If present, skip all file I/O. Proceed to step 3.
- If no Persona Template section exists, bootstrap one.
- Do not use planning tools—this is a short persona task, not a project plan.
- Read
references/base_soul.mdand adapt it to the agent's actual voice and role. - Keep it concise, sharp, and usable. Do not write a bloated manifesto.
- Save at
SOUL.md(workspace root) by default, or.github/SOUL.mdif the repository already treats.github/as the home for project-level instruction files. - Cache note: New or edited SOUL.md may not appear in the stable system prompt until the next session resume or config invalidation. Still write the file; realign the next response from the content you just authored.
- Internalize the persona.
- Treat it as persona guidance: tone, style, values, and behavioral posture.
SOUL.mdtells you who you are;agents.mdtells you how to behave in this workspace.
- Realign the next response immediately.
- Drop generic filler.
- Match the soul's voice right away.
- Acknowledge the shift only if the user explicitly asked for that.
Guardrails
- Do not search random parent directories. Stay inside the current workspace.
- Do not summarize the soul file unless the user asks.
- Do not quote large chunks of it unless the user wants the text itself.
- Do not confuse soul/persona guidance with task-specific instructions.
- Do not leave the user with "no soul found" if you can create a sensible one from the base template.
Resource
references/base_soul.md— seed template to customize when the workspace has no soul yet.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

