Separate personas, skills and project data cleanly

Agentic systems are often built as one large instruction file. Role, tone, domain knowledge, tool access, customer data, exceptions and the current task sit together. This seems convenient, yet every edit affects several dimensions. A friendlier persona may alter a permission rule; a project path enters a global template; confidential data is copied with a reusable skill.

A defensible architecture separates persona, skill, tools, policy, project context and operational data. Runtime contracts compose them. Separation does not prevent collaboration; it gives each layer a purpose, owner, lifecycle and security scope.

Persona is an interaction layer

A persona describes voice, tone, explanation depth, language conventions and interaction behaviour. It does not decide which files may be read, commands executed or results approved.

This matters because a credible role can be confused with authority. „You are the lead reviewer" grants neither identity nor permission. Textual roles are semantic guidance; technical roles come from authenticated identity, policy and access controls. Persona must never replace them.

Stable project facts do not belong in personas. Customer names, paths, contract values and deadlines belong in project context. The same persona can then serve several environments without transferring data among them.

Skills encapsulate domain method and execution logic

A skill describes a reusable capability: activation, inputs, outputs, steps, quality criteria, failure states and required tools. It answers how a method runs, not which customer data applies today.

Examples inside skills are synthetic or explicitly approved. Real project data as hidden demonstration creates leakage and ages quickly. Project parameters enter through a validated invocation contract, keeping the package testable and versioned.

Expertise and permission also remain separate. A skill may know how to classify files without receiving every folder. The orchestrator binds only required tools and paths for a run.

Tools are capabilities, not personality

A tool is a callable operation: read a file, query records, generate a report or send a message. Its interface defines parameters and responses. Permissions define targets. Neither persona nor skill stores credentials or permanent global rights.

A tool adapter maps platform-specific detail onto a stable internal interface. Skills can retain domain operations while implementations change. The adapter handles timeouts, error normalisation, authentication and technical logging. Policy still decides whether a concrete call is allowed.

This reduces excessive agency. The agent chooses only among tools assigned to the task. Analysis receives read operations; publication requires a separate gate and narrow write destination.

Policy is non-negotiable control

Policy defines data classes, paths, regions, actions, limits, approvals and escalations. It sits outside persona and retrieved project data. A document cannot claim that a security rule is suspended. A friendly voice cannot create write permission.

Policies are machine-readable, versioned and independently tested. A request identifies agent, skill, project, tool, target and action. Policy returns allow, deny or approval_required with a rule reference. The agent cannot reinterpret deny in prose.

Separation of duties matters. The person developing a skill should not alone approve its high-risk rights and production outputs. NIST treats least privilege and separation of duties as distinct controls. Small teams may combine people, but decisions remain separately recorded.

Project context describes the assignment

Project context contains objective, scope, stakeholders, terminology, allowed sources, quality level, language and phase. It refers to data rather than copying it into global instructions. A context manifest carries project ID, owner, validity, sensitivity, allowed skills and approved data spaces.

Context expires. An obsolete phase must not remain active silently. Scope or approval changes create a revision, and every run binds that revision for later reconstruction.

JSON Schema can validate required properties, types and values. Domain consistency needs additional rules: a publication phase may require an approved owner and current source revision.

Project data remains in its data space

Operational data includes documents, tables, transcripts, records, images, intermediate states and results. It has its own access, retention and backup. It is not embedded in persona or skill files. Agents receive references and only necessary excerpts.

Project boundaries prevent cross-access. Work on project A does not automatically expose project B. Global indexes and caches must not bypass isolation. Derived embeddings, summaries and logs remain assigned to project and source revision.

File systems can separate configuration, durable data, mutable state and cache. The XDG Base Directory Specification illustrates the principle. Semantics matter: cache is disposable and rebuildable; authoritative project data is not.

State is neither configuration nor knowledge

Agents need runtime state: open task, last step, locks, retry count, temporary artefacts and checkpoints. State must not be silently written into persona or skill. Otherwise one project teaches a global package its local assumptions.