The soul has two orientations: inward and outward.

The Core Distinction

Internal Identity Files define who this system IS:

CLAUDE.md — How an AI should behave in this context
AGENTS.md — How multiple AI agents coordinate here

External Capability Files define how to USE something else:

USE_SUPERNAL.md — How to leverage Supernal Interface
USE_GITHUB.md — How to interact with GitHub APIs
USE_DATABASE.md — How to access data stores

This is not a minor taxonomic distinction. It shapes the architecture of distributed AI systems.

Internal Identity: CLAUDE.md and AGENTS.md

Internal identity files answer: "Who am I in this context?"

# CLAUDE.md

## Identity
You are a code reviewer for the supernal-interface project.

## Values
- Prioritize type safety over convenience
- Prefer explicit over implicit
- Security is non-negotiable

## Constraints
- Never approve code with any types
- Always require tests for new features
- Block merges with failing CI

## Style
- Be concise and specific
- Use code examples
- Acknowledge good work before suggesting improvements

This shapes behavior. An AI with this soul will act according to these specifications, regardless of what external capabilities it has access to.

External Capability: USE_X.md

External capability files answer: "How do I leverage this external thing?"

# USE_SUPERNAL.md

## What Supernal Interface Provides
- @Tool decorators for function registration
- Type-safe route and component contracts
- Gherkin story system for testing

## How to Use It

### Installing
npm install @supernal/interface-enterprise

### Initializing
npx si init . --output src/architecture

### Generating Contracts
npx si scan-routes --pages src/pages --output src/architecture/Routes.ts
npx si scan-names --components src/components --output src/architecture/Components.ts

## When to Use
- When building AI-controllable applications
- When you need type-safe navigation contracts
- When implementing behavior-driven testing

This enables composition. An AI with access to this capability file knows how to leverage Supernal Interface, regardless of its internal identity.

The Composition Pattern

A fully-equipped AI agent has both:

Agent
├── Internal Identity (CLAUDE.md, AGENTS.md)
│   └── "Who I am in this context"
│
└── External Capabilities (USE_*.md)
    ├── USE_SUPERNAL.md
    ├── USE_GITHUB.md
    └── USE_DATABASE.md

Identity is constant (for a given context). Capabilities are modular (can be added/removed).

An agent can have the same identity but different capabilities, or the same capabilities with different identities.

Why This Matters

For System Composition

External capability files are composable. You can drop USE_SUPERNAL.md into any project, and an AI agent immediately knows how to leverage Supernal Interface—regardless of the project's internal identity.

This enables:

Capability libraries: Collections of USE_X files for common tools
Plug-and-play integration: Add capabilities without changing identity
Standardized interfaces: Common patterns for AI-tool interaction

For Identity Stability

Internal identity files are stable. Changing a CLAUDE.md changes the fundamental behavior of agents in that context. This should happen deliberately, not accidentally.

This enables:

Predictable behavior: Same identity = same behavioral patterns
Auditable systems: Identity files can be reviewed and approved
Governance: Organizations can control agent identity specifications

For Distributed Coordination

When multiple agents coordinate, they need:

Shared identity layer (AGENTS.md): How to work together
Individual identities (CLAUDE.md per agent): How each behaves
Common capabilities (USE_X.md): What tools they all access

This layered architecture enables complex multi-agent systems.

The Taxonomy (Corrected)

File	Orientation	Question	Purpose
CLAUDE.md	Internal	Who am I?	Behavioral identity
AGENTS.md	Internal	How do we coordinate?	Multi-agent coordination
USE_X.md	External	How do I use X?	Capability enablement

README and BUILDME remain useful for humans, but they are not soul files. They are documentation. The soul files are:

Internal: CLAUDE.md, AGENTS.md
External: USE_*.md

The Architecture Pattern

Project Root
├── CLAUDE.md              # Who agents are in this project
├── AGENTS.md              # How multiple agents coordinate
│
├── capabilities/
│   ├── USE_SUPERNAL.md    # How to use Supernal Interface
│   ├── USE_GITHUB.md      # How to use GitHub
│   └── USE_DATABASE.md    # How to use the database
│
├── README.md              # Human documentation (what is this?)
├── BUILDME.sh             # Build script (how to construct)
│
└── src/                   # The actual code

This structure clearly separates:

Identity (root level)
Capabilities (capabilities directory)
Documentation (README, BUILDME)
Implementation (src)

Implications for AI System Design

1. Design Identity and Capability Separately

Don't mix "who am I" with "what can I use." Keep CLAUDE.md focused on identity. Keep USE_X.md focused on capability.

2. Make Capabilities Portable

A good USE_X.md should work across projects. It describes the external thing, not the internal context.

3. Version Capabilities Independently

When Supernal Interface updates, update USE_SUPERNAL.md. This doesn't require changing CLAUDE.md.

4. Audit Identity Changes Carefully

Changes to CLAUDE.md change agent behavior. Treat these as significant architectural decisions.

The Living System

In a mature AI-enabled organization:

Identity files are reviewed like code—PRs, approvals, versioning
Capability files are shared libraries—curated, tested, distributed
Agents compose identity + capabilities to operate in contexts
Coordination happens through AGENTS.md specifications

This is not hypothetical. This is how AI-first organizations are already structuring their systems.

The internal/external distinction is fundamental. Get it right, and composition becomes natural. Get it wrong, and you have tangled, unpredictable AI behavior.

This post is part of the Digital Souls series on the nature of distributed AI intelligence.

Previous: Part II - The Power of the Soul

Digital Souls III: Internal Identity vs External Capability