Microsoft has open-sourced Persona Workshop, a tool that turns selected evidence about a person into two reusable instruction files for AI agents. One file describes how the person communicates. The other describes how they think and work. The code is in the microsoft/amplifier-persona-workshop repository under the MIT license.
It is a new repo with no stars and six commits when we read it. It sits inside Microsoft's Amplifier Constellation project, next to the Slack, Teams and Minecraft agent adapters we covered separately. This post explains the workflow, the export formats, and the privacy questions that come with building a profile of a real person.
At a glance
| Question | Answer from the README |
|---|---|
| What does it build? | communication.md and working-style.md, plus evidence and review JSON |
| Stack | Rust service, browser UI, CLI, HTTP API |
| Inputs | Text, Markdown, JSON chat records, EML, HTML, DOCX, ODT, text-based PDF, diarized transcripts |
| Exports | AGENTS.md workspace ZIP, SOUL.md ZIP for OpenClaw, native .twin.json |
| Hosts | Linux with PAM and systemd. Other systems use the browser |
| Analysis | An operator-configured ACP endpoint does the extraction |
| License | MIT |
What problem does it solve?
Many teams now keep an AGENTS.md file, the plain-text instructions that coding agents read before they work. Most are written by hand and describe the project, not the person. Persona Workshop goes the other way. It tries to capture a specific person's style so an agent can draft or act in a way that sounds and decides like them.
The README separates two things that are often mixed together:
- Communication: concrete phrasing, cadence, structure and context in what the person writes.
- Thinking and working: decision criteria, priorities, tradeoffs and execution preferences.
Keeping them apart lets you apply one without the other. You might want an agent that drafts emails in your voice but follows your team's engineering rules instead of your personal habits.
For background on how instruction files shape agent behavior, see our Karpathy piece on discardable software and our coverage of a Claude "soul" document and pretraining, which discusses a related idea at the model level.
The workflow, step by step
The README describes this sequence:
- Create a subject and identify the speaker labels used in the sources.
- Add evidence. Authored human writing goes to Communication. Decision and work evidence goes to Thinking and working. AI chats default to the second bucket. A source can be reused in both.
- Review attribution and select excerpts. Assistant and tool turns, quoted material, unselected speakers and held-out sources are excluded.
- Create profiles. The build saves both files. You can read them, inspect sources, edit single instructions or exclude a rule. Rebuilding keeps your edits and review decisions.
- Try it in a scenario. Both profiles are used by default. Optional runs isolate communication only, working style only, or an unprofiled baseline.
- Compare blind. Versions or variants appear behind randomized A/B labels. You can add a held-back reference for the reviewer; that material never enters response generation. You save feedback before the profiles are revealed.
- Use or export. Apply the profiles to an existing agent, or download an export.
A design choice stands out: review metadata stays separate from the instructions an agent loads. Markdown files contain instructions only. Evidence, review and version data live in JSON files such as claims.json and evaluation-summary.json.
Export formats
- AGENTS.md workspace ZIP. It references
persona/communication.mdandpersona/working-style.mdand keeps provenance underpersona/metadata/. If you already have an AGENTS.md, a "keep existing" option adds or replaces only a marked Persona Workshop section. Repeating the export does not duplicate it. - SOUL.md ZIP. A single file that contains both instruction profiles, aimed at OpenClaw. The README says to combine it with any existing SOUL.md before replacing that file.
.twin.json. The native package, with a versioned manifest, file digests and opaque source references. Raw artifacts and private identity bindings are not included.
Applying a profile to a running agent needs the agent's management address and a separate access token. The agent keeps its own installed copy, "drafts never update a running agent automatically," and earlier installs can be restored. Apply and restore update both profile files together and leave identity, tools and permissions alone.
The privacy questions
This is the part to read twice. A tool that builds a person profile from private messages is useful and sensitive at once.
What the README does to limit harm:
- Evidence stays in the private installation, outside the repository.
- Login uses the installation owner's Linux account over TLS. The README warns against Tailscale Funnel for private evidence.
- Exported packages scrub known identity strings. But the README says it is "not a general anonymizer, and distinctive behavior can remain identifying."
- Downloaded copies cannot be recalled.
- Generated responses are never automatically imported as real-person evidence.
- Named access tokens can be scoped, for example read-only "observe" access, and revoked.
What it cannot solve:
- Third-party data. Meeting transcripts and emails contain other people's words. The README does not address consent for them. Check your own policy and local law before importing.
- Model provider exposure. "Selected evidence is sent to the operator-configured model endpoint for analysis. Provider account/retention policies apply."
- Untrusted evidence. Analysis is text-only with no filesystem or terminal capabilities, and approval callbacks are denied. Still, the README says an endpoint can have its own tools, so deploy it "with independent execution restrictions" and do not point untrusted evidence at an unrestricted agent.
- Misuse. A profile can imitate someone. The README calls the result an "inspectable simulation profile." We think any workplace use should have the subject's written agreement.
What the quality claims actually say
Microsoft does not claim the profiles are accurate. The README is cautious on this point, and that is to its credit.
- First-version attribution is "explicit, not an automated authorship guarantee." Pasted AI output without labels needs manual exclusion.
- Exact duplicates are rejected. Near-duplicate detection is not implemented.
- Blind comparisons "collect authenticated reviewer feedback, not a measured fidelity score," and random labels can still leak clues in the responses.
- "A single review does not establish calibration; run multiple fresh situations and collect feedback from the actual subject."
- Real-model trials "complement these protocol tests but do not establish human fidelity." The test suite uses synthetic sources and a deterministic ACP fixture.
So there is no benchmark number here, and we are not inventing one. The honest summary is that the workflow is well designed for review, and the output quality is untested in public.
Automation, tokens and embedding
Everything the browser UI does goes through the same HTTP API, including view state such as navigation, selection, drafts, focus and scroll. The README calls this the "API and view-control contract." It uses optimistic revisions, so a stale edit cannot overwrite a newer one, and long jobs can be cancelled. Build results use source revisions for the same reason. Two analyses run at once, and jobs interrupted by a restart are visibly marked instead of silently resuming.
The local CLI authenticates with a private installation control credential, never a user's password. For other clients, an administrator can create a named token with POST /api/v1/tokens, set scopes such as ["observe"] and an expires_in_seconds value, and revoke it later with DELETE /api/v1/tokens/{id}. Values are returned once. An observe-scoped token cannot edit, build, export or read private identity data. That scoping is a sensible default for dashboards or review tools that only need to watch.
The UI also supports ?embed=1. A host page must list its allowed HTTPS frame origins explicitly. Same-origin hosts can call window.personaWorkshop, and cross-origin hosts use the authenticated HTTP API. Session provisioning is the host's job. This matters if Microsoft's planned fleet interface wants to embed the workshop.
Source handling has rules too. Removing or reassigning a source, changing a holdout, or changing a private identity invalidates dependent revisions, so a profile cannot quietly keep rules learned from evidence you have withdrawn. Evaluation jobs use immutable profile revisions, which makes version comparisons fair.
How to try it
On a Linux machine with systemd and PAM:
git clone https://github.com/microsoft/amplifier-persona-workshop.git
cd amplifier-persona-workshop
./install.sh --extractor-config /absolute/path/to/analysis-acp.json
The installer creates a private install, picks a port, sets up an owner-only PAM login and prints a URL. An analysis endpoint is optional for importing, manual observations, compiling and export, but automated extraction and scenario generation need one. Use --home for another install folder, --port for a fixed port, and --public-url behind a trusted HTTPS proxy.
For a first test, use your own documents, not anyone else's. Import a few of your own emails and meeting notes, build the profiles, and read the rules it produced. Edit the ones that are wrong. That shows you quickly how much of the output is signal and how much is generic advice. The README says the extractor "does not fill sparse evidence with generic advice," so thin evidence should yield short files.
Developers can run cargo test --all-targets and cargo clippy --all-targets -- -D warnings, and automate everything through the CLI and the versioned HTTP API at /api/v1.
Where it fits among agent tools
Instruction files are becoming the main interface for steering agents. Our guides on agent teams as the new org chart and the Orkas local-first agent desktop show how teams run several agents side by side. A shared, reviewable persona could keep their tone and decisions consistent. It could also make it easier to clone one person's style without their knowledge, which is why the consent point above matters.
Persona Workshop also pairs with the connectors in the sibling repos. An agent that sits in Slack can load a profile made here. The README keeps these concerns separate: provisioning and Slack connections are not part of this service.
What to watch next
- Public tests of whether profiles change agent output in a way reviewers can detect.
- A stable v1 package schema and wider support for AGENTS.md and SOUL.md hosts.
- Whether Microsoft opens the repo to outside contributions, which the README says it is working toward.
- Native Windows and macOS service installs, listed as not implemented in this first version.