Skip to main content
Part of the security infrastructure for AI agents

Curated SOUL.md collection.

SOUL.md identity files for AI agents. Organized by role, industry, organization type, use case, and fleet. Every soul covers behavioral boundaries, domain knowledge, and harm avoidance.

$npx opena2a-cli scan-soul

Scan any SOUL.md against the ABGS governance framework.

Browse the collectionGovernance specification

Why a curated collection

Writing a behavioral contract from scratch is hard. Most teams ship with no governance file at all. The collection gives you a starting point you can adopt and customize.

  • Identity portability. The same SOUL.md text can be given to Claude Code, Cursor, Copilot, Devin Desktop (formerly Windsurf), and Cline through each tool's own instruction file.
  • Tier aware governance. Pick the template that matches your agent capability level. No over governance for simple tools.
  • Scannable by HackMyAgent. Run scan-soul against any soul to verify behavioral domain coverage.
  • Public on GitHub. Additions arrive as pull requests, and a maintainer decides what is merged.

Where SOUL.md lives

Place SOUL.md in your project root, the same directory as package.json, go.mod, or Cargo.toml. Each tool reads its own instruction file, shown below, so SOUL.md reaches the tool through that file.

SOUL.md is an instruction file. The tool passes its text to the model, and nothing in the file is enforced. An agent can ignore it, and injected content can contradict it. Limits that must hold belong in controls outside the model: tool permissions, hooks, sandboxing or a capability policy.

my-project/
  SOUL.md              # agent identity (who it is)
  CLAUDE.md            # imports SOUL.md (Claude Code)
  AGENTS.md            # holds the SOUL.md text (Cursor)
  package.json
  src/
Claude CodeCLAUDE.mdAdd a line with @SOUL.md to CLAUDE.md. The tool documents this import syntax (checked 2026-10-02).
CursorAGENTS.mdCopy the content into AGENTS.md in the project root. The tool documents this file for agent instructions (checked 2026-10-02).
GitHub Copilotcopilot-instructions.mdCopy the content into .github/copilot-instructions.md. The tool documents this file for repository-wide instructions (checked 2026-10-02).
Devin Desktop (formerly Windsurf).windsurfrulesCopy the content into .windsurfrules. The tool's documentation calls this single file legacy and says it is still read (checked 2026-10-02).
Cline.clinerules/Save the content as a markdown file in .clinerules/. The tool documents this directory for workspace rules (checked 2026-10-02).

Five dimensions

Souls are organized across five dimensions so you can find the right starting point for your agent.

By Role

Souls for specific professional roles. Security engineer, DevOps specialist, data scientist, frontend architect, technical writer, and more.

Security EngineerDevOps SpecialistData ScientistAPI Designer

By Industry

Industry specific governance with compliance requirements. Healthcare (HIPAA), finance (SOX/PCI), government, education, and more.

Healthcare (HIPAA)Finance (SOX)GovernmentE-Commerce

By Organization Type

Governance tuned for different org structures. Startups, enterprises, open source projects, consultancies, agencies, and more.

StartupEnterpriseOpen SourceConsultancy

By Use Case

Task specific souls for common workflows. Code review, incident response, documentation, migration, testing, and security audit.

Code ReviewIncident ResponseMigrationSecurity Audit

By Fleet

Coordinated multi agent configurations where souls reference each other for delegation, escalation, and shared governance.

Lead and Junior PairSecurity Team FleetDevOps Pipeline Fleet

Tier templates

Start from a tier template that matches your agent capability level. Each template lays out the sections for that tier, with placeholders to fill in.

Basic

3 domains

For agents that answer questions and generate text. No tool access. Covers trust hierarchy, honesty, and data handling.

Tool Using

5 domains

For agents that call APIs, read files, or execute commands. Adds capability boundaries and injection hardening.

Agentic

7 domains

For autonomous agents that plan and execute multi step workflows. Adds agentic safety and human oversight.

Multi Agent

9 domains

For fleet deployments where agents delegate to and coordinate with other agents. Full coverage across all nine domains.

How to adopt a soul

Generate from a tier template, or copy a role specific soul and customize it. Then scan it for governance coverage.

terminal
# Generate a SOUL.md from the detected agent profile
$ npx hackmyagent harden-soul

# Or copy a role specific soul
$ curl -sO https://raw.githubusercontent.com/
    opena2a-org/awesome-agent-souls/main/
    souls/by-role/security/appsec-engineer.md

# Rename to SOUL.md in your project root
$ mv appsec-engineer.md SOUL.md

# Scan for governance coverage
$ npx opena2a-cli scan-soul

Give your agent a soul.

Pick a template, customize it for your use case, and scan it for governance coverage.

$npx opena2a-cli scan-soul
Browse the collectionRead the specification