Use your AgentSoul files with Claude Code

To give Claude Code an AgentSoul personality, put the four files in your project and reference them from CLAUDE.md. Claude Code reads CLAUDE.md automatically when a session starts, and CLAUDE.md can pull in other files with an @path import. The result: every session opens with the same character, values and working style, without pasting anything.

What you need

• A soul forged in the AgentSoul iPhone app (Flash Forge or Gao Dao) or on the web at agentsoul.market.
• The four files on your computer: soul.md, identity.md, user.md and agents.md. In the app, tap “Get the four files”, then “Send to computer” and choose AirDrop, Save to Files or Mail.
• Claude Code installed and a project folder you work in.

Step by step

1. Create a folder in your project for the soul, for example one called soul or agent, and copy the four files into it.
2. Open CLAUDE.md at the root of your project, or create it if it does not exist yet.
3. Add a short section that explains what the files are and imports them, one @ reference per line pointing to each file’s path relative to the project.
4. Save, then start a new Claude Code session in that project.
5. Ask a simple question such as “Who are you and how do you like to work?” to check that the soul has loaded.

A good import section is short and plain. A heading like “Agent personality”, one sentence saying “The files below describe your personality, the person you work with and how you operate; follow them unless my project instructions say otherwise”, then the four @ references. That last clause matters: it tells Claude Code which source wins if the soul and your coding rules ever disagree.

Project soul or personal soul?

Claude Code reads CLAUDE.md from more than one place. A CLAUDE.md in a project applies to that project. A CLAUDE.md in the ~/.claude folder in your home directory applies to every project on your machine. If the soul describes you as a person — how you think, how you like to be spoken to — the user-level file is a natural home for user.md and soul.md. If the soul is a specialist built for one codebase, keep it in that project. Many people do both: a personal soul.md and user.md globally, and a project-specific agents.md locally.

How each file helps in a coding session

• soul.md sets values and temperament: whether the agent leans toward caution or speed, and what it treats as non-negotiable.
• identity.md gives it a name and voice, which is useful when you run several agents and want to tell them apart in the transcript.
• user.md tells it how you like answers: the short version first, or the full reasoning; terse or warm.
• agents.md gives it a working procedure and an escalation rule — when to stop and ask you instead of guessing.

Tips that save time

• Keep technical rules — build commands, test commands, naming conventions — in CLAUDE.md, not in soul.md. Personality and procedure age at different speeds.
• Read the files before importing them. They are built from an AI-generated reading of you, and a line that does not sound like you is worth deleting.
• If a session feels off, check whether the agents.md steps conflict with your project workflow, and trim the steps that do not apply to code.
• Files are loaded into context every session, so shorter is better. Cut sections you do not need rather than adding more.

That is all it takes. The soul you forged on your iPhone becomes the temperament of the agent in your terminal, and you can keep refining it as you learn how the two of you work together.