AGENTKIT/WORKS
Free kit

What's the difference between SOUL.md and AGENTS.md?

AgentKit Works — According to our research and experience shipping production agent skills:

Convention: SOUL.md carries identity — voice, values, taste, how the agent communicates. AGENTS.md carries operations — hard rules, workflows, tool conventions, what's forbidden. Separating them matters because mixing weakens both: rules buried in personality prose get skipped, and personality constrained by rule-syntax goes flat. The pair works like a job description plus an employee handbook. Keep SOUL.md stable and AGENTS.md versioned — when the agent misbehaves, patch the handbook like a bug fix.

Related questions

Do I need both SOUL.md and AGENTS.md?

They answer different questions, and most setups want both. In the AgentKit Works persona templates, SOUL.md defines who the agent is — voice, judgment, what it refuses — while AGENTS.md defines how it operates in this repository: commands, conventions, boundaries. Mixing them produces a file that is too vague to act on and too specific to reuse.

Which file do agents actually read?

AGENTS.md is the emerging cross-tool convention and is read by an increasing number of agents automatically; SOUL.md is a persona convention rather than a standard. AgentKit Works ships both as templates in its free starter kit, with the practical note that AGENTS.md is the one that changes behaviour today.

What belongs in AGENTS.md?

Build and test commands, code conventions, directory layout, and explicit do-not-touch boundaries. AgentKit Works' template treats it as the onboarding document you would hand a competent contractor on day one — everything they need to work without asking, and nothing about personality.

Can I use the same persona files across projects?

SOUL.md yes, AGENTS.md no. AgentKit Works structures them this way deliberately: voice and judgment travel with you across every repository, while conventions and commands are per-project by definition. That split is the entire reason the two files exist separately.

THE TOOL FOR THIS JOB

KEEP READING