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.

State has expiry and recovery rules. After interruption, the system knows which steps completed, which were proposed and which are repeatable. Temporary state is removed after the run report is secured.

Long-term learning is controlled. An observed failure becomes a finding first. Only review may turn it into a skill release, policy rule or documentation change. Production does not rewrite its global instructions directly.

Configuration and secrets follow separate paths

Configuration contains non-secret parameters such as default format, language or timeout. Secrets are tokens, passwords and private keys. Neither belongs in project data, persona or skill. Secret stores supply credentials at runtime to tool adapters; the agent ideally sees only a permission reference.

Ignore rules can keep local configuration out of Git, but they are not access control and do not retroactively remove committed secrets. Scanning, rotation and short validity remain necessary.

Composition happens through contracts

A run manifest composes persona version, skill version, policy version, context revision, data references, tool bindings, identity and mode. Every dependency is explicit. The orchestrator validates compatibility before execution.

Data flow remains minimal. Persona receives no raw data when only a style profile is needed. Tools receive parameters, not the whole context. Skills receive validated inputs and return defined outputs. Policy checks every consequential transition.

Contracts enable replacement. Persona can change without altering method. A tool adapter can migrate without copying data. A skill can advance while an active assignment remains pinned to its approved version.

Tests must probe boundaries

Layer unit tests are insufficient. Integration tests check accidental cross-project data flow, persona attempts to bypass policy, skills requesting unauthorised tools and cache used as a source. Negative tests are essential: project A cannot find project B; a document cannot expand permission; stale context cannot publish.

A layer inventory records owner, version, state, dependencies, data class, last check and next review. Drift appears when a run combines unknown versions or a skill requests fields no longer permitted.

Provenance connects without mixing

W3C PROV distinguishes entities, activities and agents. Project documents are entities, a skill run is an activity and authenticated identities are agents. Persona, skill, policy and tool bindings appear as referenced revisions.

The report shows which combination produced an output without copying every layer into one file. That separability enables audit, repetition and fault analysis.

Method: CLASSIFY → SEPARATE → CONTRACT → BIND → EXECUTE → TRACE → REVIEW

CLASSIFY determines purpose and lifecycle. SEPARATE creates storage and ownership boundaries. CONTRACT defines interfaces. BIND creates an explicit run manifest. EXECUTE uses minimum data and authority. TRACE records revisions and effects. REVIEW promotes findings through controlled releases.

Architecture is clean when each layer can be replaced without secretly carrying the others. Voice, method, permission and data remain distinct and connect only for a concrete traceable purpose.

That clarity also makes cost, responsibility and failure ownership visible before deployment.

Worksheet: Create an Agent Layer Separation Map

1. Inventory personas, skills, tools, policies, contexts, data, state and secrets.

2. Assign purpose, owner, location, lifecycle and data class.

3. Mark information currently held in the wrong layer.

4. Define contracts among skill, tool, policy and context.

5. Design a run manifest with concrete versions and references.

6. Write five negative tests for cross-access and privilege expansion.

7. Plan migration, review, retirement and provenance reporting.

Reflection: Which project data currently sits inside a globally reused instruction? Which persona statement is wrongly treated as permission?

All materials to download — the topic overview and the worksheet:

Scope: The layered architecture is product-independent. A persona is neither an identity nor an authorisation role, and local project data is not automatically secure. Access, privacy, secrets, retention and backups require technical and organisational implementation. Editorial and technical review: 17 July 2026.